idnits 2.17.1 draft-hartke-core-stateless-01.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 (September 18, 2018) is 2044 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-02 -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). 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) September 18, 2018 5 Intended status: Standards Track 6 Expires: March 22, 2019 8 Extended Tokens and Stateless Clients 9 in the Constrained Application Protocol (CoAP) 10 draft-hartke-core-stateless-01 12 Abstract 14 This document provides considerations for alleviating CoAP clients 15 and intermediaries of maintaining per-request state. Additionally, 16 it introduces a new, optional CoAP protocol extension for extended 17 token lengths. 19 This document updates RFCs 7252 and 8323. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 22, 2019. 38 Copyright Notice 40 Copyright (c) 2018 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 4 57 2. Extended Tokens . . . . . . . . . . . . . . . . . . . . . . . 4 58 2.1. Extended Token Length (TKL) Field . . . . . . . . . . . . 4 59 2.2. Discovering Support . . . . . . . . . . . . . . . . . . . 4 60 2.2.1. Extended-Token-Lengths Capability Option . . . . . . 5 61 2.2.2. Trial and Error . . . . . . . . . . . . . . . . . . . 5 62 2.3. Intermediaries . . . . . . . . . . . . . . . . . . . . . 6 63 3. Stateless Clients . . . . . . . . . . . . . . . . . . . . . . 6 64 3.1. Intermediaries . . . . . . . . . . . . . . . . . . . . . 6 65 3.2. Extended Tokens . . . . . . . . . . . . . . . . . . . . . 7 66 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 9 67 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 69 5.1. CoAP Signaling Option Number . . . . . . . . . . . . . . 9 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 72 6.2. Informative References . . . . . . . . . . . . . . . . . 11 73 Appendix A. Updated Message Formats . . . . . . . . . . . . . . 11 74 A.1. CoAP over UDP . . . . . . . . . . . . . . . . . . . . . . 12 75 A.2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . 13 76 A.3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . 14 77 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 80 1. Introduction 82 The Constrained Application Protocol (CoAP) [RFC7252] is a RESTful 83 application-layer protocol for constrained environments [RFC7228]. 84 In CoAP, clients (or intermediaries in the client role) make requests 85 to servers (or intermediaries in the server role), which serve the 86 requests by returning responses. 88 While a request is ongoing, a client typically maintains some state 89 that it requires for processing the response when it arrives. 90 Identification of this state is done by means of a _token_ in CoAP, 91 an opaque sequence of bytes chosen by the client and included in the 92 CoAP request. The server returns the token verbatim in any resulting 93 CoAP response (Figure 1). 95 +-----------------+ request with +------------+ 96 | | | state identifier | | 97 | | | as token | | 98 | .-<-+->------|--------------------->|------. | 99 | _|_ | | | | 100 | / \ stored | | | | 101 | \___/ state | | | | 102 | | | | | | 103 | '->-+-<------|<---------------------|------' | 104 | | | response with | | 105 | v | token echoed back | | 106 +-----------------+ +------------+ 107 Client Server 109 Figure 1: Token as an Identifier for Request State 111 In some scenarios, it can be beneficial to reduce the amount of state 112 stored at the client at the cost of increased message sizes. Clients 113 can implement this by serializing their state into the token itself 114 and recovering the state from the token in the response (Figure 2). 116 +-----------------+ request with +------------+ 117 | | | serialized state | | 118 | | | as token | | 119 | +--------|=====================>|------. | 120 | | | | | 121 | look, no | | | | 122 | state, ma! | | | | 123 | | | | | 124 | +--------|<=====================|------' | 125 | | | response with | | 126 | v | token echoed back | | 127 +-----------------+ +------------+ 128 Client Server 130 Figure 2: Token as Serialization of Request State 132 Section 3 of this document provides considerations for making clients 133 "stateless" in this way, i.e., avoiding per-request state. (They'll 134 still need to maintain per-server state and other kinds of state, so 135 they're not entirely stateless.) 137 Serializing state into tokens is complicated by the fact that both 138 CoAP over UDP [RFC7252] and CoAP over reliable transports [RFC8323] 139 limit the maximum token length to 8 bytes. To overcome this 140 limitation, Section 2 of this document first introduces a CoAP 141 protocol extension for extended token lengths. 143 1.1. Requirements Notation 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 147 "OPTIONAL" in this document are to be interpreted as described in BCP 148 14 [RFC2119] [RFC8174] when, and only when, they appear in all 149 capitals, as shown here. 151 2. Extended Tokens 153 2.1. Extended Token Length (TKL) Field 155 This document updates the message formats defined for CoAP over UDP 156 [RFC7252] and CoAP over TCP, TLS, and WebSockets [RFC8323] with the 157 following new definition of the TKL field, increasing the maximum 158 token length to 65804 bytes. 160 Token Length (TKL): 4-bit unsigned integer. A value between 0 and 161 12 inclusive indicates the length of the variable-length Token 162 field in bytes. Three values are reserved for special constructs: 164 13: An 8-bit unsigned integer precedes the Token field and 165 indicates the length of the Token field minus 13. 167 14: A 16-bit unsigned integer in network byte order precedes the 168 Token field and indicates the length of the Token field minus 169 269. 171 15: Reserved. This value MUST NOT be sent and MUST be processed 172 as a message format error. 174 All other fields retain their definition. 176 The updated message formats are illustrated in Appendix A. 178 2.2. Discovering Support 180 Extended token lengths require support from the server or, if there 181 are one or more intermediaries between the client and the server, the 182 intermediary in the server role that the client is interacting with. 184 Support can be discovered by a client (or intermediary in the client 185 role) in one of two ways: In case Capabilities and Settings Messages 186 (CSMs) are available, such as in CoAP over TCP, support can be 187 discovered using the Extended-Token-Lengths Capability Option defined 188 in Section 2.2.1. Otherwise, such as in CoAP over UDP, support can 189 only be discovered by trial and error, as described in Section 2.2.2. 191 2.2.1. Extended-Token-Lengths Capability Option 193 A sender can use the elective Extended-Token-Lengths Capability 194 Option to indicate its support for the new TKL field definition 195 specified in Section 2.1. 197 +----+---+---+-------+--------------------+-------+--------+--------+ 198 | # | C | R | Appli | Name | Forma | Length | Base | 199 | | | | es to | | t | | Value | 200 +----+---+---+-------+--------------------+-------+--------+--------+ 201 | TB | | | CSM | Extended-Token- | empty | 0 | (none) | 202 | D | | | | Lengths | | | | 203 +----+---+---+-------+--------------------+-------+--------+--------+ 205 C=Critical, R=Repeatable 207 Table 1: The Extended-Token-Lengths Capability Option 209 2.2.2. Trial and Error 211 A request with a TKL field value outside the range from 0 to 8 will 212 be considered a message format error (Section 3 of RFC 7252) and be 213 rejected by a recipient that does not support the updated TKL field 214 definition. A client thus can determine support by sending a request 215 with an extended token length and checking whether it's rejected by 216 the recipient or not. 218 In CoAP over UDP, a recipient rejects a malformed confirmable message 219 by sending a Reset message (Section 4.2 of RFC 7252). In case of a 220 non-confirmable message, sending a Reset message is permitted but not 221 required (Section 4.3 of RFC 7252). It is therefore RECOMMENDED that 222 clients use a confirmable message. 224 As per RFC 7252, Reset messages are empty and don't contain a token; 225 they only return the Message ID (Figure 3). They also don't contain 226 any indication of what caused a message format error. It is 227 therefore RECOMMENDED that clients use a request that contains no 228 potential message format error other than the extended token length. 230 In CoAP over TCP, TLS, and WebSockets, a recipient rejects a 231 malformed message by sending an Abort message and shutting down the 232 connection (Section 5.6 of RFC 8323). 234 +-----------------+ request message +------------+ 235 | | | with extended | | 236 | | | token length | | 237 | .-<-+->------|--------------------->|------. | 238 | _|_ | | | | 239 | / \ stored | | | | 240 | \___/ state | | | | 241 | | | | | | 242 | '->-+-<------|<---------------------|------' | 243 | | | reset message | | 244 | v | with only message | | 245 +-----------------+ ID echoed back +------------+ 246 Client Server 248 Figure 3: A Confirmable Request With an Extended Token is Rejected 249 With a Reset Message if the Next Hop Does Not Support It 251 2.3. Intermediaries 253 Tokens are a hop-by-hop feature: When an intermediary receives a 254 request, the only requirement is that it echoes the token back in any 255 resulting response. There is no requirement or expectation that an 256 intermediary passes a client's token on to a server or that an 257 intermediary uses extended token lengths itself when receiving a 258 request with an extended token length. 260 3. Stateless Clients 262 A client can be alleviated of keeping request state by serializing 263 the state into a sequence of bytes and sending the result as the 264 token of the request. The server will return the token to the client 265 in the response, so that the client can recover the state and process 266 the response as if it had kept the state locally. 268 The format of the serialized state is an implementation detail of the 269 client and opaque to any server implementation. For security, the 270 serialized state MUST be integrity protected and MUST include a 271 freshness indicator (e.g., a sequence number or timestamp). It MAY 272 additionally be encrypted. These requirement can be satisfied, for 273 example, using COSE [RFC8152] with a key only known to the client. 275 3.1. Intermediaries 277 Tokens are a hop-by-hop feature: If a client makes a request to an 278 intermediary, that intermediary needs to store the client's token 279 (along with the client's transport address) while it makes its own 280 request to the next hop towards the origin server and waits for the 281 response. 283 An intermediary might want to be "stateless" as well, i.e., be 284 alleviated of storing the client's token and transport address for 285 ongoing requests. This can be implemented by serializing this 286 information along the request state into the token to the next hop. 287 When the next hop returns the response, the intermediary can recover 288 the information from the token and use it to satisfy the client's 289 request. 291 The downside of this approach is that an intermediary, without 292 keeping request state, is unable to aggregate requests, which reduces 293 efficiency. In particular, when multiple clients observe [RFC7641] 294 the same resource, aggregating requests is REQUIRED for efficiency 295 (Section 3.1 of RFC 7641). This implies that an intermediary MUST 296 NOT include an Observe Option in requests it sends without keeping 297 request state. 299 When using blockwise transfers [RFC7959], a server might not be able 300 to distinguish blocks originating from different clients once they 301 have been forwarded by an intermediary. To ensure that this does not 302 lead to inconsistent resource state, a stateless intermediary MUST 303 include the Request-Tag Option [I-D.ietf-core-echo-request-tag] in 304 blockwise transfers with a value that uniquely identifies the next 305 hop towards the client in the intermediary's namespace. 307 3.2. Extended Tokens 309 A client (or intermediary in the role of a client) that depends on 310 support for extended token lengths (Section 2) from the next hop to 311 avoid keeping request state MUST perform a discovery of support 312 (Section 2.2) before it can be stateless. This discovery MUST be 313 performed in a stateful way, i.e., keeping state for the request 314 (Figure 4): If the client was stateless from the start and the next 315 hop doesn't support extended tokens, then any error message couldn't 316 be processed since the state would neither be present at the client 317 nor returned in the Reset message (Figure 5). 319 +-----------------+ dummy request +------------+ 320 | | | with extended | | 321 | | | token | | 322 | .-<-+->------|=====================>|------. | 323 | _|_ | | | | 324 | / \ stored | | | | 325 | \___/ state | | | | 326 | | | | | | 327 | '->-+-<------|<=====================|------' | 328 | | | response with | | 329 | | | extended token | | 330 | | | echoed back | | 331 | | | | | 332 | | | | | 333 | | | request with | | 334 | | | serialized state | | 335 | | | as token | | 336 | +--------|=====================>|------. | 337 | | | | | 338 | look, no | | | | 339 | state, ma! | | | | 340 | | | | | 341 | +--------|<=====================|------' | 342 | | | response with | | 343 | v | token echoed back | | 344 +-----------------+ +------------+ 345 Client Server 347 Figure 4: Depending on Extended Tokens for Being Stateless First 348 Requires a Successful Stateful Discovery of Support 350 +-----------------+ dummy request +------------+ 351 | | | with extended | | 352 | | | token | | 353 | +--------|=====================>|------. | 354 | | | | | 355 | | | | | 356 | | | | | 357 | | | | | 358 | ???|<---------------------|------' | 359 | | reset message | | 360 | | with only message | | 361 +-----------------+ ID echoed back +------------+ 362 Client Server 364 Figure 5: Stateless Discovery of Support Does Not Work 366 3.3. Message Transmission 368 As a further step in the case of CoAP over UDP [RFC7252], a client 369 (or intermediary in the client role) might want to also avoid keeping 370 message transmission state. 372 Generally, a client can use confirmable or non-confirmable messages 373 for requests. When using confirmable messages, it needs to keep 374 message exchange state for performing retransmissions and handling 375 Acknowledgement and Reset messages. When using non-confirmable 376 messages, it can keep no message exchange state. However, in either 377 case the client needs to keep congestion control state. That is, it 378 needs to maintain state for each node it communicates with and, e.g., 379 enforce NSTART. 381 As per RFC 7252, a client must be prepared to receive a response as a 382 piggybacked response, a separate response or non-confirmable response 383 (Section 5.2 of RFC 7252), regardless of the message type used for 384 the request. A stateless client needs to handle these response types 385 as follows: 387 o If a piggybacked response contains a valid authentication tag and 388 freshness indicator in the token, the client MUST process the 389 message as specified in RFC 7252; otherwise, it MUST silently 390 ignore the message. 392 o If a separate response contains a valid authentication tag and 393 freshness indicator in the token, the client MUST process the 394 message as specified in RFC 7252; otherwise, it MUST reject the 395 message as specified in Section 4.2 of RFC 7252. 397 o If a non-confirmable response contains a valid authentication tag 398 and freshness indicator in the token, the client MUST process the 399 message as specified in RFC 7252; otherwise, it MUST reject the 400 message as specified in Section 4.3 of RFC 7252. 402 4. Security Considerations 404 TODO. 406 5. IANA Considerations 408 5.1. CoAP Signaling Option Number 410 The following entries are added to the "CoAP Signaling Option 411 Numbers" registry within the "CoRE Parameters" registry. 413 +------------+--------+------------------------+-------------------+ 414 | Applies to | Number | Name | Reference | 415 +------------+--------+------------------------+-------------------+ 416 | 7.01 | TBD | Extended-Token-Lengths | [[this document]] | 417 +------------+--------+------------------------+-------------------+ 419 6. References 421 6.1. Normative References 423 [I-D.ietf-core-echo-request-tag] 424 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 425 Request-Tag", draft-ietf-core-echo-request-tag-02 (work in 426 progress), June 2018. 428 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 429 Requirement Levels", BCP 14, RFC 2119, 430 DOI 10.17487/RFC2119, March 1997, 431 . 433 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 434 Application Protocol (CoAP)", RFC 7252, 435 DOI 10.17487/RFC7252, June 2014, 436 . 438 [RFC7641] Hartke, K., "Observing Resources in the Constrained 439 Application Protocol (CoAP)", RFC 7641, 440 DOI 10.17487/RFC7641, September 2015, 441 . 443 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 444 the Constrained Application Protocol (CoAP)", RFC 7959, 445 DOI 10.17487/RFC7959, August 2016, 446 . 448 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 449 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 450 May 2017, . 452 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 453 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 454 Application Protocol) over TCP, TLS, and WebSockets", 455 RFC 8323, DOI 10.17487/RFC8323, February 2018, 456 . 458 6.2. Informative References 460 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 461 Constrained-Node Networks", RFC 7228, 462 DOI 10.17487/RFC7228, May 2014, 463 . 465 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 466 RFC 8152, DOI 10.17487/RFC8152, July 2017, 467 . 469 Appendix A. Updated Message Formats 471 This appendix illustrates the CoAP message formats updated with the 472 new definition of the TKL field (Section 2). 474 A.1. CoAP over UDP 476 0 1 2 3 4 5 6 7 477 +-------+-------+---------------+ 478 | | | | 479 | Ver | T | TKL | 1 byte 480 | | | | 481 +-------+-------+---------------+ 482 | | 483 | Code | 1 byte 484 | | 485 +-------------------------------+ 486 | | 487 | | 488 | | 489 +- Message ID -+ 2 bytes 490 | | 491 | | 492 | | 493 +-------------------------------+ 494 \ \ 495 / TKL / 0-2 bytes 496 \ (extended) \ 497 +-------------------------------+ 498 \ \ 499 / Token / 0 or more bytes 500 \ \ 501 +-------------------------------+ 502 \ \ 503 / / 504 \ \ 505 / Options / 0 or more bytes 506 \ \ 507 / / 508 \ \ 509 +---------------+---------------+ 510 | | | 511 | 15 | 15 | 1 byte (if payload) 512 | | | 513 +---------------+---------------+ 514 \ \ 515 / / 516 \ \ 517 / Payload / 0 or more bytes 518 \ \ 519 / / 520 \ \ 521 +-------------------------------+ 523 A.2. CoAP over TCP 525 0 1 2 3 4 5 6 7 526 +---------------+---------------+ 527 | | | 528 | Len | TKL | 1 byte 529 | | | 530 +---------------+---------------+ 531 \ \ 532 / Len / 0-2 bytes 533 \ (extended) \ 534 +-------------------------------+ 535 | | 536 | Code | 1 byte 537 | | 538 +-------------------------------+ 539 \ \ 540 / TKL / 0-2 bytes 541 \ (extended) \ 542 +-------------------------------+ 543 \ \ 544 / Token / 0 or more bytes 545 \ \ 546 +-------------------------------+ 547 \ \ 548 / / 549 \ \ 550 / Options / 0 or more bytes 551 \ \ 552 / / 553 \ \ 554 +---------------+---------------+ 555 | | | 556 | 15 | 15 | 1 byte (if payload) 557 | | | 558 +---------------+---------------+ 559 \ \ 560 / / 561 \ \ 562 / Payload / 0 or more bytes 563 \ \ 564 / / 565 \ \ 566 +-------------------------------+ 568 A.3. CoAP over WebSockets 570 0 1 2 3 4 5 6 7 571 +---------------+---------------+ 572 | | | 573 | 0 | TKL | 1 byte 574 | | | 575 +---------------+---------------+ 576 | | 577 | Code | 1 byte 578 | | 579 +-------------------------------+ 580 \ \ 581 / TKL / 0-2 bytes 582 \ (extended) \ 583 +-------------------------------+ 584 \ \ 585 / Token / 0 or more bytes 586 \ \ 587 +-------------------------------+ 588 \ \ 589 / / 590 \ \ 591 / Options / 0 or more bytes 592 \ \ 593 / / 594 \ \ 595 +---------------+---------------+ 596 | | | 597 | 15 | 15 | 1 byte (if payload) 598 | | | 599 +---------------+---------------+ 600 \ \ 601 / / 602 \ \ 603 / Payload / 0 or more bytes 604 \ \ 605 / / 606 \ \ 607 +-------------------------------+ 609 Acknowledgements 611 Thanks to Carsten Bormann, Ari Keranen, Jim Schaad, Goeran Selander, 612 and Malisa Vucinic for helpful comments and discussions that have 613 shaped the document. 615 Author's Address 617 Klaus Hartke 618 Ericsson 619 Torshamnsgatan 23 620 Stockholm SE-16483 621 Sweden 623 Email: klaus.hartke@ericsson.com