idnits 2.17.1 draft-ietf-core-stateless-06.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: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 864 lines 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 (April 12, 2020) is 1475 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-09 Summary: 0 errors (**), 0 flaws (~~), 3 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) April 12, 2020 5 Intended status: Standards Track 6 Expires: October 14, 2020 8 Extended Tokens and Stateless Clients 9 in the Constrained Application Protocol (CoAP) 10 draft-ietf-core-stateless-06 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. 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 October 14, 2020. 38 Copyright Notice 40 Copyright (c) 2020 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 56 1.1. Terminology 57 2. Extended Tokens 58 2.1. Extended Token Length (TKL) Field 59 2.2. Discovering Support 60 2.2.1. Extended-Token-Length Capability Option 61 2.2.2. Trial-and-Error 62 2.3. Intermediaries 63 3. Stateless Clients 64 3.1. Serializing Client State 65 3.2. Using Extended Tokens 66 3.3. Transmitting Messages 67 4. Stateless Intermediaries 68 4.1. Observing Resources 69 4.2. Block-Wise Transfers 70 4.3. Gateway Timeouts 71 5. Security Considerations 72 5.1. Extended Tokens 73 5.2. Stateless Clients and Intermediaries 74 6. IANA Considerations 75 6.1. CoAP Signaling Option Number 76 7. References 77 7.1. Normative References 78 7.2. Informative References 79 Appendix A. Updated Message Formats 80 A.1. CoAP over UDP 81 A.2. CoAP over TCP/TLS 82 A.3. CoAP over WebSockets 83 Acknowledgements 84 Author's Address 86 1. Introduction 88 The Constrained Application Protocol (CoAP) [RFC7252] is a RESTful 89 application-layer protocol for constrained environments [RFC7228]. 90 In CoAP, clients (or intermediaries in the client role) make requests 91 to servers (or intermediaries in the server role), which satisfy the 92 requests by returning responses. 94 While a request is ongoing, a client typically needs to keep some 95 state that it requires for processing the response when that arrives. 96 Identification of this state is done in CoAP by means of a token, an 97 opaque sequence of bytes chosen by the client and included in the 98 CoAP request, and that is returned by the server verbatim in any 99 resulting CoAP response (Figure 1). 101 +-----------------+ request with +------------+ 102 | | | state identifier | | 103 | | | as token | | 104 | .-<-+->------|--------------------->|------. | 105 | _|_ | | | | 106 | / \ stored | | | | 107 | \___/ state | | | | 108 | | | | | | 109 | '->-+-<------|<---------------------|------' | 110 | | | response with | | 111 | v | token echoed back | | 112 +-----------------+ +------------+ 113 Client Server 115 Figure 1: Token as an Identifier for Request State 117 In some scenarios, it can be beneficial to reduce the amount of state 118 that is stored at the client at the cost of increased message sizes. 119 A client can opt into this by serializing (parts of) its state into 120 the token itself and then recovering this state from the token in the 121 response (Figure 2). 123 +-----------------+ request with +------------+ 124 | | | serialized state | | 125 | | | as token | | 126 | +--------|=====================>|------. | 127 | | | | | 128 | look ma, | | | | 129 | no state! | | | | 130 | | | | | 131 | +--------|<=====================|------' | 132 | | | response with | | 133 | v | token echoed back | | 134 +-----------------+ +------------+ 135 Client Server 137 Figure 2: Token as Serialization of Request State 139 Section 3 of this document provides considerations for clients 140 becoming "stateless" in this way. (The term "stateless" is in quotes 141 here, because it's a bit oversimplified. Such clients still need to 142 maintain per-server state and other kinds of state. So it would be 143 more accurate to just say that the clients are avoiding per-request 144 state.) 146 Section 4 of this document extends the considerations for clients to 147 intermediaries, which may not only want to avoid keeping state for 148 the requests they send to servers but also for the requests they 149 receive from clients. 151 The serialization of state into tokens is limited by the fact that 152 both CoAP over UDP [RFC7252] and CoAP over reliable transports 153 [RFC8323] restrict the maximum token length to 8 bytes. To overcome 154 this limitation, Section 2 of this document first introduces a CoAP 155 protocol extension for extended token lengths. 157 While the use case (avoiding per-request state) and the mechanism 158 (extended token lengths) presented in this document are closely 159 related, both can be used independently of each other: Some 160 implementations may be able to fit their state in just 8 bytes; some 161 implementations may have other use cases for extended token lengths. 163 1.1. Terminology 165 In this document, the term "stateless" refers to an implementation 166 strategy for a client (or intermediary in the client role) that does 167 not require it to keep state for the individual requests it sends to 168 a server (or intermediary in the server role). The client still 169 needs to keep state for each server it communicates with (e.g., for 170 token generation, message retransmission, and congestion control). 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 174 "OPTIONAL" in this document are to be interpreted as described in BCP 175 14 [RFC2119] [RFC8174] when, and only when, they appear in all 176 capitals, as shown here. 178 2. Extended Tokens 180 This document updates the message formats defined for CoAP over UDP 181 [RFC7252] and CoAP over TCP, TLS, and WebSockets [RFC8323] with a new 182 definition of the TKL field. 184 2.1. Extended Token Length (TKL) Field 186 The definition of the TKL field is updated as follows: 188 Token Length (TKL): 4-bit unsigned integer. A value between 0 and 189 12 inclusive indicates the length of the variable-length Token 190 field in bytes. The other three values are reserved for special 191 constructs: 193 13: An 8-bit unsigned integer precedes the Token field and 194 indicates the length of the Token field minus 13. 196 14: A 16-bit unsigned integer in network byte order precedes the 197 Token field and indicates the length of the Token field minus 198 269. 200 15: Reserved. This value MUST NOT be sent and MUST be processed 201 as a message format error. 203 All other fields retain their definitions. 205 The updated message formats are illustrated in Appendix A. 207 The new definition of the TKL field increases the maximum token 208 length that can be represented in a message to 65804 bytes. However, 209 the maximum token length that sender and recipient implementations 210 support may be shorter. For example, a constrained node of Class 1 211 [RFC7228] might support extended token lengths only up to 32 bytes. 213 2.2. Discovering Support 215 Extended token lengths require support from server implementations. 216 Support can be discovered by a client implementation in one of two 217 ways: 219 o Where Capabilities and Settings Messages (CSMs) are available, 220 such as in CoAP over TCP, support can be discovered using the 221 Extended-Token-Length Capability Option defined in Section 2.2.1. 223 o Otherwise, such as in CoAP over UDP, support can only be 224 discovered by trial-and-error, as described in Section 2.2.2. 226 2.2.1. Extended-Token-Length Capability Option 228 A server can use the elective Extended-Token-Length Capability Option 229 to indicate the maximum token length it can accept in requests. 231 +----+---+---+--------+--------------------+-------+--------+-------+ 232 | # | C | R | Applie | Name | Forma | Length | Base | 233 | | | | s to | | t | | Value | 234 +----+---+---+--------+--------------------+-------+--------+-------+ 235 | TB | | | CSM | Extended-Token- | uint | 0-3 | 8 | 236 | D | | | | Length | | | | 237 +----+---+---+--------+--------------------+-------+--------+-------+ 239 C=Critical, R=Repeatable 241 Table 1: The Extended-Token-Length Capability Option 243 As per Section 3 of RFC 7252, the base value (and the value used when 244 this option is not implemented) is 8. 246 The active value of the Extended-Token-Length Option is replaced each 247 time the option is sent with a modified value. Its starting value is 248 its base value. 250 The option value MUST NOT be less than 8 or greater than 65804. If 251 an option value less than 8 is received, the option MUST be ignored. 252 If an option value greater than 65804 is received, the option value 253 MUST be set to 65804. 255 Any option value greater than 8 implies support for the new 256 definition of the TKL field specified in Section 2.1. Indication of 257 support by a server does not oblige a client to actually make use of 258 token lengths greater than 8. 260 If a server receives a request with a token of a length greater than 261 it indicated in its Extended-Token-Length Option, it MUST handle the 262 request as a message format error. 264 The Extended-Token-Length Capability Option does not apply to 265 responses. The sender of a request is simply expected not to use a 266 token of a length greater than it is willing to accept in a response. 268 2.2.2. Trial-and-Error 270 A server implementation that does not support the updated definition 271 of the TKL field specified in Section 2.1 will consider a request 272 with a TKL field value outside the range 0 to 8 a message format 273 error and reject it (Section 3 of RFC 7252). A client can therefore 274 determine support by sending a request with an extended token length 275 and checking whether it is rejected by the server or not. 277 In CoAP over UDP, the way a request message is rejected depends on 278 the message type. A Confirmable message with a message format error 279 is rejected with a Reset message (Section 4.2 of RFC 7252). A Non- 280 confirmable message with a message format error is either rejected 281 with a Reset message or just silently ignored (Section 4.3 of RFC 282 7252). It is therefore RECOMMENDED that clients use a Confirmable 283 message for determining support. 285 As per RFC 7252, Reset messages are empty and do not contain a token; 286 they only return the Message ID (Figure 3). They also do not contain 287 any indication of what caused a message format error. To avoid any 288 ambiguity, it is therefore RECOMMENDED that clients use a request 289 that has no potential message format error other than the extended 290 token length. 292 +-----------------+ request message +------------+ 293 | | | with extended | | 294 | | | token length | | 295 | .-<-+->------|--------------------->|------. | 296 | _|_ | | | | 297 | / \ stored | | | | 298 | \___/ state | | | | 299 | | | | | | 300 | '->-+-<------|<---------------------|------' | 301 | | | reset message | | 302 | v | with only message | | 303 +-----------------+ ID echoed back +------------+ 304 Client Server 306 Figure 3: A Confirmable Request With an Extended Token is Rejected 307 With a Reset Message if the Server Does Not Have Support 309 An example of a suitable request is a GET request in a Confirmable 310 message that includes only an If-None-Match option and a token of the 311 greatest length that the client intends to use. Any response with 312 the same token echoed back indicates that tokens up to that length 313 are supported by the server. 315 Since network addresses may change, a client SHOULD NOT assume that 316 extended token lengths are supported by a server later than 60 317 minutes after receiving a response with an extended token length. 319 If a server supports extended token lengths but receives a request 320 with a token of a length it is unwilling or unable to handle, it MUST 321 NOT reject the message, as that would imply that extended token 322 lengths are not supported at all. Instead, if the server cannot 323 handle the request at the time, it SHOULD return a 5.03 (Service 324 Unavailable) response; if the server will never be able to handle 325 (e.g., because the token is too large), it SHOULD return a 4.00 (Bad 326 Request) response. 328 Design Note: The requirement to return an error response when a 329 token cannot be handled might seem somewhat contradictory, as 330 returning the error response requires the server also to return 331 the token it cannot handle. However, processing a request usually 332 involves a number of steps from receiving the message to passing 333 it to application logic. The idea is that a server implementing 334 this document should at least support large tokens in its first 335 few processing steps, enough to return an error response rather 336 than a Reset message. 338 Design Note: To make the trial-and-error-based discovery not too 339 complicated, no effort is made to indicate the maximum supported 340 token length. A client implementation would probably already 341 choose the shortest token possible for the task (like being 342 stateless as described in Section 3), so it probably would not be 343 able to reduce the length any further anyway should a server 344 indicate a lower limit. 346 2.3. Intermediaries 348 Tokens are a hop-by-hop feature: If there are one or more 349 intermediaries between a client and a server, every token is scoped 350 to the exchange between a node in the client role and the node in the 351 server role that it is immediately interacting with. 353 When an intermediary receives a request, the only requirement is that 354 it echoes the token back in any resulting response. There is no 355 requirement or expectation that an intermediary passes a client's 356 token on to a server or that an intermediary uses extended token 357 lengths itself in its request to satisfy a request with an extended 358 token length. Discovery needs to be performed for each hop where 359 extended token lengths are to be used. 361 3. Stateless Clients 363 A client can be alleviated of keeping per-request state as follows: 365 1. The client serializes (parts of) its per-request state into a 366 sequence of bytes and sends those bytes as the token of its 367 request to the server. 369 2. The server returns the token verbatim in the response to the 370 client, which allows the client to recover the state and process 371 the response as if it had kept the state locally. 373 As servers are just expected to return any token verbatim to the 374 client, this implementation strategy for clients does impact the 375 interoperability of client and server implementations. However, 376 there are a number of significant, non-obvious implications (e.g., 377 related to security and other CoAP protocol features) that client 378 implementations need take into consideration. 380 The following subsections discuss some of these considerations. 382 3.1. Serializing Client State 384 The format of the serialized state is generally an implementation 385 detail of the client and opaque to the server. However, serialized 386 state information is an attractive target for both unwanted nodes 387 (e.g., on-path attackers) and wanted nodes (e.g., any configured 388 forward proxy) on the path. The serialization format therefore needs 389 to include security measures such as the following: 391 o A client SHOULD integrity protect the state information serialized 392 in a token, unless processing a response does not modify state or 393 cause any other significant side effects. 395 o Even when the serialized state is integrity protected, an attacker 396 may still replay a response, making the client believe it sent the 397 same request twice. For this reason, the client SHOULD implement 398 replay protection (e.g., by using sequence numbers and a replay 399 window), unless processing a response does not modify state or 400 cause other any significant side effects. For replay protection, 401 integrity protection is REQUIRED. 403 o If processing a response without keeping request state is 404 sensitive to the time elapsed since sending the request, then the 405 serialized state SHOULD include freshness information (e.g., a 406 timestamp). 408 o Information in the serialized state may be privacy sensitive. A 409 client SHOULD encrypt the serialized state if it contains privacy 410 sensitive information that an attacker would not get otherwise. 412 o When a client changes the format of the serialized state, it 413 SHOULD prevent false interoperability with the previous format 414 (e.g., by changing the key used for integration protection or 415 changing a field in the serialized state). 417 3.2. Using Extended Tokens 419 A client that depends on support for extended token lengths 420 (Section 2) from the server to avoid keeping request state SHOULD 421 perform a discovery of support (Section 2.2) before it can be 422 stateless. 424 This discovery MUST be performed in a stateful way, i.e., keeping 425 state for the request (Figure 4): If the client was stateless from 426 the start and the server does not support extended tokens, then any 427 error message could not be processed since the state would neither be 428 present at the client nor returned in the Reset message (Figure 5). 430 +-----------------+ dummy request +------------+ 431 | | | with extended | | 432 | | | token | | 433 | .-<-+->------|=====================>|------. | 434 | _|_ | | | | 435 | / \ stored | | | | 436 | \___/ state | | | | 437 | | | | | | 438 | '->-+-<------|<=====================|------' | 439 | | | response with | | 440 | | | extended token | | 441 | | | echoed back | | 442 | | | | | 443 | | | | | 444 | | | request with | | 445 | | | serialized state | | 446 | | | as token | | 447 | +--------|=====================>|------. | 448 | | | | | 449 | look ma, | | | | 450 | no state! | | | | 451 | | | | | 452 | +--------|<=====================|------' | 453 | | | response with | | 454 | v | token echoed back | | 455 +-----------------+ +------------+ 456 Client Server 458 Figure 4: Depending on Extended Tokens for Being Stateless First 459 Requires a Successful Stateful Discovery of Support 461 +-----------------+ dummy request +------------+ 462 | | | with extended | | 463 | | | token | | 464 | +--------|=====================>|------. | 465 | | | | | 466 | | | | | 467 | | | | | 468 | | | | | 469 | ???|<---------------------|------' | 470 | | reset message | | 471 | | with only message | | 472 +-----------------+ ID echoed back +------------+ 473 Client Server 475 Figure 5: Stateless Discovery of Support Does Not Work 477 In environments where support can be reliably discovered through some 478 other means, the discovery of support is OPTIONAL. An example for 479 this is the Constrained Join Protocol (CoJP) in a 6TiSCH network 480 [I-D.ietf-6tisch-minimal-security], where support for extended tokens 481 is required from all relevant parties. 483 3.3. Transmitting Messages 485 In CoAP over UDP [RFC7252], a client has the choice between 486 Confirmable and Non-confirmable messages for requests. When using 487 Non-confirmable messages, a client does not have to keep any message 488 exchange state, which can help in the goal of avoiding state. When 489 using Confirmable messages, a client needs to keep message exchange 490 state for performing retransmissions and handling Acknowledgement and 491 Reset messages, however. Non-confirmable messages are therefore 492 better suited. In any case, a client still needs to keep congestion 493 control state, i.e., maintain state for each node it communicates 494 with and enforce limits like NSTART. 496 As per Section 5.2 of RFC 7252, a client must be prepared to receive 497 a response as a piggybacked response, a separate response or Non- 498 confirmable response, regardless of the message type used for the 499 request. A stateless client MUST handle these response types as 500 follows: 502 o If a piggybacked response passes the token integrity protection 503 and freshness checks, the client processes the message as 504 specified in RFC 7252; otherwise, it silently discards the 505 message. 507 o If a separate response passes the token integrity protection and 508 freshness checks, the client processes the message as specified in 509 RFC 7252; otherwise, it rejects the message as specified in 510 Section 4.2 of RFC 7252. 512 o If a Non-confirmable response passes the token integrity 513 protection and freshness checks, the client processes the message 514 as specified in RFC 7252; otherwise, it rejects the message as 515 specified in Section 4.3 of RFC 7252. 517 4. Stateless Intermediaries 519 Tokens are a hop-by-hop feature: If a client makes a request to an 520 intermediary, that intermediary needs to store the client's token 521 (along with the client's transport address) while it makes its own 522 request towards the origin server and waits for the response. When 523 the intermediary receives the response, it looks up the client's 524 token and transport address for the received request and sends an 525 appropriate response to the client. 527 An intermediary might want to be "stateless" not only in its role as 528 a client but also in its role as a server, i.e., be alleviated of 529 storing the client information for the requests it receives. 531 Such an intermediary can be implemented by serializing the client 532 information along the request state into the token towards the origin 533 server. When the intermediary receives the response, it can recover 534 the client information from the token and use it to satisfy the 535 client's request and therefore doesn't need to store it itself. 537 The following subsections discuss some considerations for this 538 approach. 540 4.1. Observing Resources 542 One drawback of the approach is that an intermediary, without keeping 543 request state, is unable to aggregate multiple requests for the same 544 target resource, which can significantly reduce efficiency. In 545 particular, when clients observe [RFC7641] the same resource, 546 aggregating requests is REQUIRED (Section 3.1 of RFC 7641). This 547 requirement cannot be satisfied without keeping request state. 549 Furthermore, an intermediary that does not keep track of the clients 550 observing a resource is not able to determine whether these clients 551 are still interested in receiving further notifications (Section 3.5 552 of RFC 7641) or want to cancel an observation (Section 3.6 of RFC 553 7641). 555 Therefore, an intermediary MUST NOT include an Observe Option in 556 requests it sends without keeping both the request state for the 557 requests it sends and the client information for the requests it 558 receives. 560 4.2. Block-Wise Transfers 562 When using block-wise transfers [RFC7959], a server might not be able 563 to distinguish blocks originating from different clients once they 564 have been forwarded by an intermediary. Intermediaries need to 565 ensure that this does not lead to inconsistent resource state by 566 keeping distinct block-wise request operations on the same resource 567 apart, e.g., utilizing the Request-Tag Option 568 [I-D.ietf-core-echo-request-tag]. 570 4.3. Gateway Timeouts 572 As per Section 5.7.1 of RFC 7252, an intermediary is REQUIRED to 573 return a 5.04 (Gateway Timeout) response if it cannot obtain a 574 response within a timeout. However, if an intermediary does not keep 575 the client information for the requests it receives, it cannot return 576 such a response. Therefore, in this case, the timeout should be set 577 to infinite. 579 5. Security Considerations 581 5.1. Extended Tokens 583 Tokens significantly larger than the 8 bytes specified in RFC 7252 584 have implications in particular for nodes with constrained memory 585 size that need to be mitigated. A node in the server role supporting 586 extended token lengths may be vulnerable to a denial-of-service when 587 an attacker (either on-path or a malicious client) sends large tokens 588 to fill up the memory of the node. Implementations need to be 589 prepared to handle such messages. 591 5.2. Stateless Clients and Intermediaries 593 Transporting the state needed by a client to process a response as 594 serialized state information in the token has several significant and 595 non-obvious security and privacy implications that need to be 596 mitigated; see Section 3.1 for recommendations. In addition to the 597 format requirements outlined there, implementations need to ensure 598 that they are not vulnerable to maliciously crafted, delayed, or 599 replayed tokens. 601 The use of encryption, integrity protection, and replay protection of 602 serialized state is recommended, unless a careful analysis of any 603 potential attacks to security and privacy is performed. AES-CCM with 604 a 64 bit tag is recommended, combined with a sequence number and a 605 replay window. Where encryption is not needed, HMAC-SHA-256, 606 combined with a sequence number and a replay window, may be used. 608 When using an encryption mode that depends on a nonce, such as AES- 609 CCM, repeated use of the same nonce under the same key causes the 610 cipher to fail catastrophically. If a nonce is ever used for more 611 than one encryption operation with the same key, then the same key 612 stream gets used to encrypt both plaintexts and the confidentiality 613 guarantees are voided. Devices with low-entropy sources -- as is 614 typical with constrained devices, which incidentally happen to be a 615 natural candidate for the stateless mechanism described in this 616 document -- need to carefully pick a nonce generation mechanism that 617 provides the above uniqueness guarantee. Additionally, since it can 618 be difficult to use AES-CCM securely when using statically configured 619 keys, implementations should use automated key management [RFC4107]. 621 6. IANA Considerations 623 6.1. CoAP Signaling Option Number 625 The following entries are added to the "CoAP Signaling Option 626 Numbers" registry within the "CoRE Parameters" registry. 628 +------------+--------+-----------------------+-------------------+ 629 | Applies to | Number | Name | Reference | 630 +------------+--------+-----------------------+-------------------+ 631 | 7.01 | TBD | Extended-Token-Length | [[this document]] | 632 +------------+--------+-----------------------+-------------------+ 634 [[NOTE TO RFC EDITOR: Please replace "TBD" in this section and in 635 Table 1 with the code point assigned by IANA.]] 637 7. References 639 7.1. Normative References 641 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 642 Requirement Levels", BCP 14, RFC 2119, 643 DOI 10.17487/RFC2119, March 1997, 644 . 646 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 647 Application Protocol (CoAP)", RFC 7252, 648 DOI 10.17487/RFC7252, June 2014, 649 . 651 [RFC7641] Hartke, K., "Observing Resources in the Constrained 652 Application Protocol (CoAP)", RFC 7641, 653 DOI 10.17487/RFC7641, September 2015, 654 . 656 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 657 the Constrained Application Protocol (CoAP)", RFC 7959, 658 DOI 10.17487/RFC7959, August 2016, 659 . 661 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 662 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 663 May 2017, . 665 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 666 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 667 Application Protocol) over TCP, TLS, and WebSockets", 668 RFC 8323, DOI 10.17487/RFC8323, February 2018, 669 . 671 7.2. Informative References 673 [I-D.ietf-6tisch-minimal-security] 674 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 675 "Constrained Join Protocol (CoJP) for 6TiSCH", draft-ietf- 676 6tisch-minimal-security-15 (work in progress), December 677 2019. 679 [I-D.ietf-core-echo-request-tag] 680 Amsuess, C., Mattsson, J., and G. Selander, "CoAP: Echo, 681 Request-Tag, and Token Processing", draft-ietf-core-echo- 682 request-tag-09 (work in progress), March 2020. 684 [RFC4107] Bellovin, S. and R. Housley, "Guidelines for Cryptographic 685 Key Management", BCP 107, RFC 4107, DOI 10.17487/RFC4107, 686 June 2005, . 688 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 689 Constrained-Node Networks", RFC 7228, 690 DOI 10.17487/RFC7228, May 2014, 691 . 693 Appendix A. Updated Message Formats 695 In Section 2, this document updates the CoAP message formats by 696 specifying a new definition of the TKL field in the message header. 697 As an alternative presentation of this update, this appendix shows 698 the CoAP message formats for CoAP over UDP [RFC7252] and CoAP over 699 TCP, TLS, and WebSockets [RFC8323] with the new definition applied. 701 A.1. CoAP over UDP 703 0 1 2 3 4 5 6 7 704 +-------+-------+---------------+ 705 | | | | 706 | Ver | T | TKL | 1 byte 707 | | | | 708 +-------+-------+---------------+ 709 | | 710 | Code | 1 byte 711 | | 712 +-------------------------------+ 713 | | 714 | | 715 | | 716 +- Message ID -+ 2 bytes 717 | | 718 | | 719 | | 720 +-------------------------------+ 721 \ \ 722 / TKL / 0-2 bytes 723 \ (extended) \ 724 +-------------------------------+ 725 \ \ 726 / Token / 0 or more bytes 727 \ \ 728 +-------------------------------+ 729 \ \ 730 / / 731 \ \ 732 / Options / 0 or more bytes 733 \ \ 734 / / 735 \ \ 736 +---------------+---------------+ 737 | | | 738 | 15 | 15 | 1 byte (if payload) 739 | | | 740 +---------------+---------------+ 741 \ \ 742 / / 743 \ \ 744 / Payload / 0 or more bytes 745 \ \ 746 / / 747 \ \ 748 +-------------------------------+ 750 A.2. CoAP over TCP/TLS 752 0 1 2 3 4 5 6 7 753 +---------------+---------------+ 754 | | | 755 | Len | TKL | 1 byte 756 | | | 757 +---------------+---------------+ 758 \ \ 759 / Len / 0-2 bytes 760 \ (extended) \ 761 +-------------------------------+ 762 | | 763 | Code | 1 byte 764 | | 765 +-------------------------------+ 766 \ \ 767 / TKL / 0-2 bytes 768 \ (extended) \ 769 +-------------------------------+ 770 \ \ 771 / Token / 0 or more bytes 772 \ \ 773 +-------------------------------+ 774 \ \ 775 / / 776 \ \ 777 / Options / 0 or more bytes 778 \ \ 779 / / 780 \ \ 781 +---------------+---------------+ 782 | | | 783 | 15 | 15 | 1 byte (if payload) 784 | | | 785 +---------------+---------------+ 786 \ \ 787 / / 788 \ \ 789 / Payload / 0 or more bytes 790 \ \ 791 / / 792 \ \ 793 +-------------------------------+ 795 A.3. CoAP over WebSockets 797 0 1 2 3 4 5 6 7 798 +---------------+---------------+ 799 | | | 800 | 0 | TKL | 1 byte 801 | | | 802 +---------------+---------------+ 803 | | 804 | Code | 1 byte 805 | | 806 +-------------------------------+ 807 \ \ 808 / TKL / 0-2 bytes 809 \ (extended) \ 810 +-------------------------------+ 811 \ \ 812 / Token / 0 or more bytes 813 \ \ 814 +-------------------------------+ 815 \ \ 816 / / 817 \ \ 818 / Options / 0 or more bytes 819 \ \ 820 / / 821 \ \ 822 +---------------+---------------+ 823 | | | 824 | 15 | 15 | 1 byte (if payload) 825 | | | 826 +---------------+---------------+ 827 \ \ 828 / / 829 \ \ 830 / Payload / 0 or more bytes 831 \ \ 832 / / 833 \ \ 834 +-------------------------------+ 836 Acknowledgements 838 This document is based on the requirements of and work on the Minimal 839 Security Framework for 6TiSCH [I-D.ietf-6tisch-minimal-security] by 840 Malisa Vucinic, Jonathan Simon, Kris Pister, and Michael Richardson. 842 Thanks to Christian Amsuess, Carsten Bormann, Christer Holmberg, Ari 843 Keranen, Barry Leiba, David Mandelberg, Dan Romascanu, Jim Schaad, 844 Goeran Selander, and Malisa Vucinic for helpful comments and 845 discussions that have shaped the document. 847 Special thanks to John Mattsson for his contributions to the security 848 considerations of the document, and to Thomas Fossati for his in- 849 depth review, copious comments, and suggested text. 851 Author's Address 853 Klaus Hartke 854 Ericsson 855 Torshamnsgatan 23 856 Stockholm SE-16483 857 Sweden 859 Email: klaus.hartke@ericsson.com