idnits 2.17.1 draft-ietf-core-stateless-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 16, 2020) is 1250 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-11 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke 3 Internet-Draft Ericsson 4 Updates: 7252, 8323 (if approved) M. Richardson 5 Intended status: Standards Track Sandelman 6 Expires: May 20, 2021 November 16, 2020 8 Extended Tokens and Stateless Clients 9 in the Constrained Application Protocol (CoAP) 10 draft-ietf-core-stateless-08 12 Abstract 14 This document provides considerations for alleviating CoAP clients 15 and intermediaries of keeping per-request state. To facilitate this, 16 this document additionally introduces a new, optional CoAP protocol 17 extension for extended token lengths. 19 This document updates RFCs 7252 and 8323 with an extended definition 20 of the TKL field in the CoAP message header. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 20, 2021. 39 Copyright Notice 41 Copyright (c) 2020 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Extended Tokens . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.1. Extended Token Length (TKL) Field . . . . . . . . . . . . 4 60 2.2. Discovering Support . . . . . . . . . . . . . . . . . . . 5 61 2.2.1. Extended-Token-Length Capability Option . . . . . . . 5 62 2.2.2. Trial-and-Error . . . . . . . . . . . . . . . . . . . 6 63 2.3. Intermediaries . . . . . . . . . . . . . . . . . . . . . 8 64 3. Stateless Clients . . . . . . . . . . . . . . . . . . . . . . 9 65 3.1. Serializing Client State . . . . . . . . . . . . . . . . 9 66 3.2. Using Extended Tokens . . . . . . . . . . . . . . . . . . 10 67 3.3. Transmitting Messages . . . . . . . . . . . . . . . . . . 12 68 4. Stateless Intermediaries . . . . . . . . . . . . . . . . . . 12 69 4.1. Observing Resources . . . . . . . . . . . . . . . . . . . 13 70 4.2. Block-Wise Transfers . . . . . . . . . . . . . . . . . . 13 71 4.3. Gateway Timeouts . . . . . . . . . . . . . . . . . . . . 14 72 4.4. Extended Tokens . . . . . . . . . . . . . . . . . . . . . 14 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 74 5.1. Extended Tokens . . . . . . . . . . . . . . . . . . . . . 14 75 5.2. Stateless Clients and Intermediaries . . . . . . . . . . 14 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 77 6.1. CoAP Signaling Option Number . . . . . . . . . . . . . . 16 78 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 79 7.1. Normative References . . . . . . . . . . . . . . . . . . 16 80 7.2. Informative References . . . . . . . . . . . . . . . . . 17 81 Appendix A. Updated Message Formats . . . . . . . . . . . . . . 18 82 A.1. CoAP over UDP . . . . . . . . . . . . . . . . . . . . . . 18 83 A.2. CoAP over TCP/TLS . . . . . . . . . . . . . . . . . . . . 20 84 A.3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . 21 85 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 88 1. Introduction 90 The Constrained Application Protocol (CoAP) [RFC7252] is a RESTful 91 application-layer protocol for constrained environments [RFC7228]. 92 In CoAP, clients (or intermediaries in the client role) make requests 93 to servers (or intermediaries in the server role), which satisfy the 94 requests by returning responses. 96 While a request is ongoing, a client typically needs to keep some 97 state that it requires for processing the response when that arrives. 98 Identification of this state is done in CoAP by means of a token, an 99 opaque sequence of bytes chosen by the client and included in the 100 CoAP request, and that is returned by the server verbatim in any 101 resulting CoAP response (Figure 1). 103 +-----------------+ request with +------------+ 104 | | | state identifier | | 105 | | | as token | | 106 | .-<-+->------|--------------------->|------. | 107 | _|_ | | | | 108 | / \ stored | | | | 109 | \___/ state | | | | 110 | | | | | | 111 | '->-+-<------|<---------------------|------' | 112 | | | response with | | 113 | v | token echoed back | | 114 +-----------------+ +------------+ 115 Client Server 117 Figure 1: Token as an Identifier for Request State 119 In some scenarios, it can be beneficial to reduce the amount of state 120 that is stored at the client at the cost of increased message sizes. 121 A client can opt into this by serializing (parts of) its state into 122 the token itself and then recovering this state from the token in the 123 response (Figure 2). 125 +-----------------+ request with +------------+ 126 | | | serialized state | | 127 | | | as token | | 128 | +--------|=====================>|------. | 129 | | | | | 130 | look ma, | | | | 131 | no state! | | | | 132 | | | | | 133 | +--------|<=====================|------' | 134 | | | response with | | 135 | v | token echoed back | | 136 +-----------------+ +------------+ 137 Client Server 139 Figure 2: Token as Serialization of Request State 141 Section 3 of this document provides considerations for clients 142 becoming "stateless" in this way. (The term "stateless" is in quotes 143 here, because it's a bit oversimplified. Such clients still need to 144 maintain per-server state and other kinds of state. So it would be 145 more accurate to just say that the clients are avoiding per-request 146 state.) 148 Section 4 of this document extends the considerations for clients to 149 intermediaries, which may not only want to avoid keeping state for 150 the requests they send to servers but also for the requests they 151 receive from clients. 153 The serialization of state into tokens is limited by the fact that 154 both CoAP over UDP [RFC7252] and CoAP over reliable transports 155 [RFC8323] restrict the maximum token length to 8 bytes. To overcome 156 this limitation, Section 2 of this document first introduces a CoAP 157 protocol extension for extended token lengths. 159 While the use case (avoiding per-request state) and the mechanism 160 (extended token lengths) presented in this document are closely 161 related, both can be used independently of each other: Some 162 implementations may be able to fit their state in just 8 bytes; some 163 implementations may have other use cases for extended token lengths. 165 1.1. Terminology 167 In this document, the term "stateless" refers to an implementation 168 strategy for a client (or intermediary in the client role) that does 169 not require it to keep state for the individual requests it sends to 170 a server (or intermediary in the server role). The client still 171 needs to keep state for each server it communicates with (e.g., for 172 token generation, message retransmission, and congestion control). 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 176 "OPTIONAL" in this document are to be interpreted as described in BCP 177 14 [RFC2119] [RFC8174] when, and only when, they appear in all 178 capitals, as shown here. 180 2. Extended Tokens 182 This document updates the message formats defined for CoAP over UDP 183 [RFC7252] and CoAP over TCP, TLS, and WebSockets [RFC8323] with a new 184 definition of the TKL field. 186 2.1. Extended Token Length (TKL) Field 188 The definition of the TKL field is updated as follows: 190 Token Length (TKL): 4-bit unsigned integer. A value between 0 and 191 12 inclusive indicates the length of the variable-length Token 192 field in bytes. The other three values are reserved for special 193 constructs: 195 13: An 8-bit unsigned integer directly precedes the Token field 196 and indicates the length of the Token field minus 13. 198 14: A 16-bit unsigned integer in network byte order directly 199 precedes the Token field and indicates the length of the Token 200 field minus 269. 202 15: Reserved. This value MUST NOT be sent and MUST be processed 203 as a message format error. 205 All other fields retain their definitions. 207 The updated message formats are illustrated in Appendix A. 209 The new definition of the TKL field increases the maximum token 210 length that can be represented in a message to 65804 bytes. However, 211 the maximum token length that sender and recipient implementations 212 support may be shorter. For example, a constrained node of Class 1 213 [RFC7228] might support extended token lengths only up to 32 bytes. 215 In CoAP over UDP, it is often beneficial to keep CoAP messages small 216 enough to avoid IP fragmentation. The maximum practical token length 217 may therefore also be influenced by the Path MTU. See Section 4.6 of 218 RFC 7252 for details. 220 2.2. Discovering Support 222 Extended token lengths require support from server implementations. 223 Support can be discovered by a client implementation in one of two 224 ways: 226 o Where Capabilities and Settings Messages (CSMs) are available, 227 such as in CoAP over TCP, support can be discovered using the 228 Extended-Token-Length Capability Option defined in Section 2.2.1. 230 o Otherwise, such as in CoAP over UDP, support can only be 231 discovered by trial-and-error, as described in Section 2.2.2. 233 2.2.1. Extended-Token-Length Capability Option 235 A server can use the elective Extended-Token-Length Capability Option 236 to indicate the maximum token length it can accept in requests. 238 +----+---+---+--------+--------------------+-------+--------+-------+ 239 | # | C | R | Applie | Name | Forma | Length | Base | 240 | | | | s to | | t | | Value | 241 +----+---+---+--------+--------------------+-------+--------+-------+ 242 | TB | | | CSM | Extended-Token- | uint | 0-3 | 8 | 243 | D | | | | Length | | | | 244 +----+---+---+--------+--------------------+-------+--------+-------+ 246 C=Critical, R=Repeatable 248 Table 1: The Extended-Token-Length Capability Option 250 As per Section 3 of RFC 7252, the base value (and the value used when 251 this option is not implemented) is 8. 253 The active value of the Extended-Token-Length Option is replaced each 254 time the option is sent with a modified value. Its starting value is 255 its base value. 257 The option value MUST NOT be less than 8 or greater than 65804. If 258 an option value less than 8 is received, the option MUST be ignored. 259 If an option value greater than 65804 is received, the option value 260 MUST be set to 65804. 262 Any option value greater than 8 implies support for the new 263 definition of the TKL field specified in Section 2.1. Indication of 264 support by a server does not oblige a client to actually make use of 265 token lengths greater than 8. 267 If a server receives a request with a token of a length greater than 268 what it indicated in its Extended-Token-Length Option, it MUST handle 269 the request as a message format error. 271 If a server receives a request with a token of a length less than or 272 equal to what it indicated in its Extended-Token-Length Option but is 273 unwilling or unable to handle the token at that time, it MUST NOT 274 handle the request as a message format error. Instead, it SHOULD 275 return a 5.03 (Service Unavailable) response. 277 The Extended-Token-Length Capability Option does not apply to 278 responses. The sender of a request is simply expected not to use a 279 token of a length greater than it is willing to accept in a response. 281 2.2.2. Trial-and-Error 283 A server implementation that does not support the updated definition 284 of the TKL field specified in Section 2.1 will consider a request 285 with a TKL field value outside the range 0 to 8 a message format 286 error and reject it (Section 3 of RFC 7252). A client can therefore 287 determine support by sending a request with an extended token length 288 and checking whether it is rejected by the server or not. 290 In CoAP over UDP, the way a request message is rejected depends on 291 the message type. A Confirmable message with a message format error 292 is rejected with a Reset message (Section 4.2 of RFC 7252). A Non- 293 confirmable message with a message format error is either rejected 294 with a Reset message or just silently ignored (Section 4.3 of RFC 295 7252). To reliably get a Reset message, it is therefore REQUIRED 296 that clients use a Confirmable message for determining support. 298 As per RFC 7252, Reset messages are empty and do not contain a token; 299 they only return the Message ID (Figure 3). They also do not contain 300 any indication of what caused a message format error. To avoid any 301 ambiguity, it is therefore RECOMMENDED that clients use a request 302 that has no potential message format error other than the extended 303 token length. 305 +-----------------+ request message +------------+ 306 | | | with extended | | 307 | | | token length | | 308 | .-<-+->------|--------------------->|------. | 309 | _|_ | | | | 310 | / \ stored | | | | 311 | \___/ state | | | | 312 | | | | | | 313 | '->-+-<------|<---------------------|------' | 314 | | | reset message | | 315 | v | with only message | | 316 +-----------------+ ID echoed back +------------+ 317 Client Server 319 Figure 3: A Confirmable Request With an Extended Token is Rejected 320 With a Reset Message if the Server Does Not Have Support 322 An example of a suitable request is a GET request in a Confirmable 323 message that includes only an If-None-Match option and a token of the 324 greatest length that the client intends to use. Any response with 325 the same token echoed back indicates that tokens up to that length 326 are supported by the server. 328 Since network addresses may change, a client SHOULD NOT assume that 329 extended token lengths are supported by a server for an unlimited 330 duration. Unless additional information is available, the client 331 should assume that addresses (and therefore extended token lengths) 332 are valid for a minimum of 1800 s, and for a maximum of 86400 s (1 333 day). A client may use additional forms of input into this 334 determination. For instance a client may assume a server which is in 335 the same subnet as the client has a similar address lifetime as the 336 client. The client may use DHCP lease times or Router Advertisements 337 to set the limits. For servers that are not local, if the server was 338 looked up using DNS, then the DNS resource record will have a Time To 339 Live, and the extended token length should be kept for only that 340 amount of time. 342 If a server supports extended token lengths but receives a request 343 with a token of a length it is unwilling or unable to handle, it MUST 344 NOT reject the message, as that would imply that extended token 345 lengths are not supported at all. Instead, if the server cannot 346 handle the request at the time, it SHOULD return a 5.03 (Service 347 Unavailable) response; if the server will never be able to handle the 348 request (e.g., because the token is too large), it SHOULD return a 349 4.00 (Bad Request) response. 351 Design Note: The requirement to return an error response when a 352 token cannot be handled might seem somewhat contradictory, as 353 returning the error response requires the server also to return 354 the token it cannot handle. However, processing a request usually 355 involves a number of steps from receiving the message to passing 356 it to application logic. The idea is that a server implementing 357 this extension supports large tokens at least in its first few 358 processing steps, enough to return an error response rather than a 359 Reset message. 361 Design Note: To make the trial-and-error-based discovery not too 362 complicated, no effort is made to indicate the maximum supported 363 token length. A client implementation would probably already 364 choose the shortest token possible for the task (like being 365 stateless as described in Section 3), so it would probably not be 366 able to reduce the length any further anyway should a server 367 indicate a lower limit. 369 2.3. Intermediaries 371 Tokens are a hop-by-hop feature: If there are one or more 372 intermediaries between a client and a server, every token is scoped 373 to the exchange between a node in the client role and the node in the 374 server role that it is immediately interacting with. 376 When an intermediary receives a request, the only requirement is that 377 it echoes the token back in any resulting response. There is no 378 requirement or expectation that an intermediary passes a client's 379 token on to a server or that an intermediary uses extended token 380 lengths itself in its request to satisfy a request with an extended 381 token length. Discovery needs to be performed for each hop where 382 extended token lengths are to be used. 384 3. Stateless Clients 386 A client can be alleviated of keeping per-request state as follows: 388 1. The client serializes (parts of) its per-request state into a 389 sequence of bytes and sends those bytes as the token of its 390 request to the server. 392 2. The server returns the token verbatim in the response to the 393 client, which allows the client to recover the state and process 394 the response as if it had kept the state locally. 396 As servers are just expected to return any token verbatim to the 397 client, this implementation strategy for clients does not impact the 398 interoperability of client and server implementations. However, 399 there are a number of significant, non-obvious implications (e.g., 400 related to security and other CoAP protocol features) that client 401 implementations need take into consideration. 403 The following subsections discuss some of these considerations. 405 3.1. Serializing Client State 407 The format of the serialized state is generally an implementation 408 detail of the client and opaque to the server. However, serialized 409 state information is an attractive target for both unwanted nodes 410 (e.g., on-path attackers) and wanted nodes (e.g., any configured 411 forward proxy) on the path. The serialization format therefore needs 412 to include security measures such as the following: 414 o A client SHOULD protect the integrity of the state information 415 serialized in a token. 417 o Even when the integrity of the serialized state is protected, an 418 attacker may still replay a response, making the client believe it 419 sent the same request twice. For this reason, the client SHOULD 420 implement replay protection (e.g., by using sequence numbers and a 421 replay window). For replay protection, integrity protection is 422 REQUIRED. 424 o If processing a response without keeping request state is 425 sensitive to the time elapsed since sending the request, then the 426 client SHOULD include freshness information (e.g., a timestamp) in 427 the serialized state and reject any response where the freshness 428 information is insufficiently fresh. 430 o Information in the serialized state may be privacy sensitive. A 431 client SHOULD encrypt the serialized state if it contains privacy 432 sensitive information that an attacker would not get otherwise. 434 o When a client changes the format of the serialized state, it 435 SHOULD prevent false interoperability with the previous format 436 (e.g., by changing the key used for integrity protection or 437 changing a field in the serialized state). 439 3.2. Using Extended Tokens 441 A client that depends on support for extended token lengths 442 (Section 2) from the server to avoid keeping request state needs to 443 perform a discovery of support (Section 2.2) before it can be 444 stateless. 446 This discovery MUST be performed in a stateful way, i.e., keeping 447 state for the request (Figure 4): If the client was stateless from 448 the start and the server does not support extended tokens, then any 449 error message could not be processed since the state would neither be 450 present at the client nor returned in the Reset message (Figure 5). 452 +-----------------+ dummy request +------------+ 453 | | | with extended | | 454 | | | token | | 455 | .-<-+->------|=====================>|------. | 456 | _|_ | | | | 457 | / \ stored | | | | 458 | \___/ state | | | | 459 | | | | | | 460 | '->-+-<------|<=====================|------' | 461 | | | response with | | 462 | | | extended token | | 463 | | | echoed back | | 464 | | | | | 465 | | | | | 466 | | | request with | | 467 | | | serialized state | | 468 | | | as token | | 469 | +--------|=====================>|------. | 470 | | | | | 471 | look ma, | | | | 472 | no state! | | | | 473 | | | | | 474 | +--------|<=====================|------' | 475 | | | response with | | 476 | v | token echoed back | | 477 +-----------------+ +------------+ 478 Client Server 480 Figure 4: Depending on Extended Tokens for Being Stateless First 481 Requires a Successful Stateful Discovery of Support 483 +-----------------+ dummy request +------------+ 484 | | | with extended | | 485 | | | token | | 486 | +--------|=====================>|------. | 487 | | | | | 488 | | | | | 489 | | | | | 490 | | | | | 491 | ???|<---------------------|------' | 492 | | reset message | | 493 | | with only message | | 494 +-----------------+ ID echoed back +------------+ 495 Client Server 497 Figure 5: Stateless Discovery of Support Does Not Work 499 In environments where support can be reliably discovered through some 500 other means, the discovery of support is OPTIONAL. An example for 501 this is the Constrained Join Protocol (CoJP) in a 6TiSCH network 502 [I-D.ietf-6tisch-minimal-security], where support for extended tokens 503 is required from all relevant parties. 505 3.3. Transmitting Messages 507 In CoAP over UDP [RFC7252], a client has the choice between 508 Confirmable and Non-confirmable messages for requests. When using 509 Non-confirmable messages, a client does not have to keep any message 510 exchange state, which can help in the goal of avoiding state. When 511 using Confirmable messages, a client needs to keep message exchange 512 state for performing retransmissions and handling Acknowledgement and 513 Reset messages, however. Non-confirmable messages are therefore 514 better suited for avoiding state. In any case, a client still needs 515 to keep congestion control state, i.e., maintain state for each node 516 it communicates with and enforce limits like NSTART. 518 As per Section 5.2 of RFC 7252, a client must be prepared to receive 519 a response as a piggybacked response, a separate response, or Non- 520 confirmable response, regardless of the message type used for the 521 request. A stateless client MUST handle these response types as 522 follows: 524 o If a piggybacked response passes the checks for token integrity 525 and freshness (Section 3.1), the client processes the message as 526 specified in RFC 7252; otherwise, it processes the acknowledgement 527 portion of the message as specified in RFC 7252 and silently 528 discards the response portion. 530 o If a separate response passes the checks for token integrity and 531 freshness, the client processes the message as specified in RFC 532 7252; otherwise, it rejects the message as specified in 533 Section 4.2 of RFC 7252. 535 o If a Non-confirmable response passes the checks for token 536 integrity and freshness, the client processes the message as 537 specified in RFC 7252; otherwise, it rejects the message as 538 specified in Section 4.3 of RFC 7252. 540 4. Stateless Intermediaries 542 Tokens are a hop-by-hop feature: If a client makes a request to an 543 intermediary, that intermediary needs to store the client's token 544 (along with the client's transport address) while it makes its own 545 request towards the origin server and waits for the response. When 546 the intermediary receives the response, it looks up the client's 547 token and transport address for the received request and sends an 548 appropriate response to the client. 550 An intermediary might want to be "stateless" not only in its role as 551 a client but also in its role as a server, i.e., be alleviated of 552 storing the client information for the requests it receives. 554 Such an intermediary can be implemented by serializing the client 555 information along with the request state into the token towards the 556 origin server. When the intermediary receives the response, it can 557 recover the client information from the token and use it to satisfy 558 the client's request and therefore doesn't need to store it itself. 560 The following subsections discuss some considerations for this 561 approach. 563 4.1. Observing Resources 565 One drawback of the approach is that an intermediary, without keeping 566 request state, is unable to aggregate multiple requests for the same 567 target resource, which can significantly reduce efficiency. In 568 particular, when clients observe [RFC7641] the same resource, 569 aggregating requests is REQUIRED (Section 3.1 of RFC 7641). This 570 requirement cannot be satisfied without keeping request state. 572 Furthermore, an intermediary that does not keep track of the clients 573 observing a resource is not able to determine whether these clients 574 are still interested in receiving further notifications (Section 3.5 575 of RFC 7641) or want to cancel an observation (Section 3.6 of RFC 576 7641). 578 Therefore, an intermediary MUST NOT include an Observe Option in 579 requests it sends without keeping both the request state for the 580 requests it sends and the client information for the requests it 581 receives. 583 4.2. Block-Wise Transfers 585 When using block-wise transfers [RFC7959], a server might not be able 586 to distinguish blocks originating from different clients once they 587 have been forwarded by an intermediary. Intermediaries need to 588 ensure that this does not lead to inconsistent resource state by 589 keeping distinct block-wise request operations on the same resource 590 apart, e.g., utilizing the Request-Tag Option 591 [I-D.ietf-core-echo-request-tag]. 593 4.3. Gateway Timeouts 595 As per Section 5.7.1 of RFC 7252, an intermediary is REQUIRED to 596 return a 5.04 (Gateway Timeout) response if it cannot obtain a 597 response within a timeout. However, if an intermediary does not keep 598 the client information for the requests it receives, it cannot return 599 such a response. Therefore, in this case, the gateway cannot return 600 such a response and as such cannot implement such a timeout. 602 4.4. Extended Tokens 604 A client may make use of extended token lengths in a request to an 605 intermediary that wants to be "stateless". This means that such an 606 intermediary may have to serialize potentially very large client 607 information into its token towards the origin server. The tokens can 608 grow even further when it progresses along a chain of intermediaries 609 that all want to be "stateless". 611 Intermediaries SHOULD limit the size of client information they are 612 serializing into their own tokens. An intermediary can do this, for 613 example, by limiting the extended token lengths it accepts from its 614 clients (see Section 2.2) or by keeping the client information 615 locally when the client information exceeds the limit (i.e., not 616 being "stateless"). 618 5. Security Considerations 620 5.1. Extended Tokens 622 Tokens significantly larger than the 8 bytes specified in RFC 7252 623 have implications in particular for nodes with constrained memory 624 size that need to be mitigated. A node in the server role supporting 625 extended token lengths may be vulnerable to a denial-of-service when 626 an attacker (either on-path or a malicious client) sends large tokens 627 to fill up the memory of the node. Implementations need to be 628 prepared to handle such messages. 630 5.2. Stateless Clients and Intermediaries 632 Transporting the state needed by a client to process a response as 633 serialized state information in the token has several significant and 634 non-obvious security and privacy implications that need to be 635 mitigated; see Section 3.1 for recommendations. 637 In addition to the format requirements outlined there, 638 implementations need to ensure that they are not vulnerable to 639 maliciously crafted, delayed, or replayed tokens. 641 It is generally expected that the use of encryption, integrity 642 protection, and replay protection for serialized state is 643 appropriate. 645 In the absence of integrity and replay protection, an on-path 646 attacker or rogue server/intermediary could return a state (either 647 one modified in a reply, or an unsolicited one) that could alter the 648 internal state of the client. 650 It is for this reason that at least the use of integrity protection 651 on the token is always recommended. 653 It maybe that in some very specific case, as a result of a careful 654 and detailed analysis of any potential attacks, that there may be 655 cases where such cryptographic protections do not add value. The 656 authors of this document have not found such a use case as yet, but 657 this is a local decision. 659 It should further be emphasized that the encrypted state is created 660 by the sending node, and decrypted by the same node when receiving a 661 response. The key is not shared with any other system. Therefore 662 the choice of encryption scheme and the generation of the key for 663 this system is purely a local matter. 665 When encryption is used, the use of AES-CCM [RFC3610] with a 64-bit 666 tag is recommended, combined with a sequence number and a replay 667 window. This choice is informed by available hardware acceleration 668 of on many constrained systems. If a different algorithm is 669 available accelerated on the sender, with similar or stronger 670 strength, then it SHOULD be preferred. Where privacy of the state is 671 not required, and encryption is not needed, HMAC-SHA-256 [RFC6234], 672 combined with a sequence number and a replay window, may be used. 674 This size of the replay window depends upon the number of requests 675 that need to be outstanding. This can be determined from the rate at 676 which new ones are made, and the expected duration in which responses 677 are expected. 679 For instance, given a CoAP MAX_TRANSMIT_WAIT of 93 s (Section 4.8.2 680 of [RFC7252], any request that is not answered within 93 s will be 681 considered to have failed. At a request rate of one request per 10 682 s, at most 10 (ceil(9.3)) requests can be outstanding at a time, and 683 any convenient replay window larger than 20 will work. As replay 684 windows are often implemented with a sliding window and a bit, the 685 use of a 32-bit window would be sufficient. 687 For use cases where requests are being relayed from another node, the 688 request rate may be estimated by the total link capacity allocated 689 for that kind of traffic. An alternate view would consider how many 690 IPv6 Neighbor Cache Entries (NCEs) the system can afford to allocate 691 for this use. 693 When using an encryption mode that depends on a nonce, such as AES- 694 CCM, repeated use of the same nonce under the same key causes the 695 cipher to fail catastrophically. 697 If a nonce is ever used for more than one encryption operation with 698 the same key, then the same key stream gets used to encrypt both 699 plaintexts and the confidentiality guarantees are voided. Devices 700 with low-quality entropy sources -- as is typical with constrained 701 devices, which incidentally happen to be a natural candidate for the 702 stateless mechanism described in this document -- need to carefully 703 pick a nonce generation mechanism that provides the above uniqueness 704 guarantee. 706 [RFC8613] appendix B.1.1 ("Sender Sequence Number") provides a model 707 for how to maintain non-repeating nonces without causing excessive 708 wear of flash memory. 710 6. IANA Considerations 712 6.1. CoAP Signaling Option Number 714 The following entries are added to the "CoAP Signaling Option 715 Numbers" registry within the "CoRE Parameters" registry. 717 +------------+--------+-----------------------+-------------------+ 718 | Applies to | Number | Name | Reference | 719 +------------+--------+-----------------------+-------------------+ 720 | 7.01 | TBD | Extended-Token-Length | [[this document]] | 721 +------------+--------+-----------------------+-------------------+ 723 [[NOTE TO RFC EDITOR: Please replace "TBD" in this section and in 724 Table 1 with the code point assigned by IANA.]] 726 7. References 728 7.1. Normative References 730 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 731 Requirement Levels", BCP 14, RFC 2119, 732 DOI 10.17487/RFC2119, March 1997, 733 . 735 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 736 Application Protocol (CoAP)", RFC 7252, 737 DOI 10.17487/RFC7252, June 2014, 738 . 740 [RFC7641] Hartke, K., "Observing Resources in the Constrained 741 Application Protocol (CoAP)", RFC 7641, 742 DOI 10.17487/RFC7641, September 2015, 743 . 745 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 746 the Constrained Application Protocol (CoAP)", RFC 7959, 747 DOI 10.17487/RFC7959, August 2016, 748 . 750 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 751 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 752 May 2017, . 754 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 755 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 756 Application Protocol) over TCP, TLS, and WebSockets", 757 RFC 8323, DOI 10.17487/RFC8323, February 2018, 758 . 760 7.2. Informative References 762 [I-D.ietf-6tisch-minimal-security] 763 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 764 "Constrained Join Protocol (CoJP) for 6TiSCH", draft-ietf- 765 6tisch-minimal-security-15 (work in progress), December 766 2019. 768 [I-D.ietf-core-echo-request-tag] 769 Amsuess, C., Mattsson, J., and G. Selander, "CoAP: Echo, 770 Request-Tag, and Token Processing", draft-ietf-core-echo- 771 request-tag-11 (work in progress), November 2020. 773 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 774 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 775 2003, . 777 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 778 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 779 DOI 10.17487/RFC6234, May 2011, 780 . 782 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 783 Constrained-Node Networks", RFC 7228, 784 DOI 10.17487/RFC7228, May 2014, 785 . 787 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 788 "Object Security for Constrained RESTful Environments 789 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 790 . 792 Appendix A. Updated Message Formats 794 In Section 2, this document updates the CoAP message formats by 795 specifying a new definition of the TKL field in the message header. 796 As an alternative presentation of this update, this appendix shows 797 the CoAP message formats for CoAP over UDP [RFC7252] and CoAP over 798 TCP, TLS, and WebSockets [RFC8323] with the new definition applied. 800 A.1. CoAP over UDP 801 0 1 2 3 4 5 6 7 802 +-------+-------+---------------+ 803 | | | | 804 | Ver | T | TKL | 1 byte 805 | | | | 806 +-------+-------+---------------+ 807 | | 808 | Code | 1 byte 809 | | 810 +-------------------------------+ 811 | | 812 | | 813 | | 814 +- Message ID -+ 2 bytes 815 | | 816 | | 817 | | 818 +-------------------------------+ 819 \ \ 820 / TKL / 0-2 bytes 821 \ (extended) \ 822 +-------------------------------+ 823 \ \ 824 / Token / 0-65804 bytes 825 \ \ 826 +-------------------------------+ 827 \ \ 828 / / 829 \ \ 830 / Options / 0 or more bytes 831 \ \ 832 / / 833 \ \ 834 +---------------+---------------+ 835 | | | 836 | 15 | 15 | 1 byte (if payload) 837 | | | 838 +---------------+---------------+ 839 \ \ 840 / / 841 \ \ 842 / Payload / 0 or more bytes 843 \ \ 844 / / 845 \ \ 846 +-------------------------------+ 848 A.2. CoAP over TCP/TLS 850 0 1 2 3 4 5 6 7 851 +---------------+---------------+ 852 | | | 853 | Len | TKL | 1 byte 854 | | | 855 +---------------+---------------+ 856 \ \ 857 / Len / 0-4 bytes 858 \ (extended) \ 859 +-------------------------------+ 860 | | 861 | Code | 1 byte 862 | | 863 +-------------------------------+ 864 \ \ 865 / TKL / 0-2 bytes 866 \ (extended) \ 867 +-------------------------------+ 868 \ \ 869 / Token / 0-65804 bytes 870 \ \ 871 +-------------------------------+ 872 \ \ 873 / / 874 \ \ 875 / Options / 0 or more bytes 876 \ \ 877 / / 878 \ \ 879 +---------------+---------------+ 880 | | | 881 | 15 | 15 | 1 byte (if payload) 882 | | | 883 +---------------+---------------+ 884 \ \ 885 / / 886 \ \ 887 / Payload / 0 or more bytes 888 \ \ 889 / / 890 \ \ 891 +-------------------------------+ 893 A.3. CoAP over WebSockets 895 0 1 2 3 4 5 6 7 896 +---------------+---------------+ 897 | | | 898 | 0 | TKL | 1 byte 899 | | | 900 +---------------+---------------+ 901 | | 902 | Code | 1 byte 903 | | 904 +-------------------------------+ 905 \ \ 906 / TKL / 0-2 bytes 907 \ (extended) \ 908 +-------------------------------+ 909 \ \ 910 / Token / 0-65804 bytes 911 \ \ 912 +-------------------------------+ 913 \ \ 914 / / 915 \ \ 916 / Options / 0 or more bytes 917 \ \ 918 / / 919 \ \ 920 +---------------+---------------+ 921 | | | 922 | 15 | 15 | 1 byte (if payload) 923 | | | 924 +---------------+---------------+ 925 \ \ 926 / / 927 \ \ 928 / Payload / 0 or more bytes 929 \ \ 930 / / 931 \ \ 932 +-------------------------------+ 934 Acknowledgements 936 This document is based on the requirements of and work on the Minimal 937 Security Framework for 6TiSCH [I-D.ietf-6tisch-minimal-security] by 938 Malisa Vucinic, Jonathan Simon, Kris Pister, and Michael Richardson. 940 Thanks to Christian Amsuss, Carsten Bormann, Roman Danyliw, Christer 941 Holmberg, Benjamin Kaduk, Ari Keranen, Erik Kline, Murray Kucherawy, 942 Warren Kumari, Barry Leiba, David Mandelberg, Dan Romascanu, Jim 943 Schaad, Goran Selander, Malisa Vucinic, Eric Vyncke, and Robert 944 Wilton for helpful comments and discussions that have shaped the 945 document. 947 Special thanks to John Mattsson for his contributions to the security 948 considerations of the document, and to Thomas Fossati for his in- 949 depth review, copious comments, and suggested text. 951 Authors' Addresses 953 Klaus Hartke 954 Ericsson 955 Torshamnsgatan 23 956 Stockholm SE-16483 957 Sweden 959 Email: klaus.hartke@ericsson.com 961 Michael C. Richardson 962 Sandelman Software Works 964 Email: mcr+ietf@sandelman.ca 965 URI: http://www.sandelman.ca/