idnits 2.17.1 draft-ietf-core-new-block-11.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 (April 28, 2021) is 1084 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) == Missing Reference: 'Missing 1' is mentioned on line 1518, but not defined -- Looks like a reference, but probably isn't: '9' on line 1207 == Missing Reference: 'Missing 10' is mentioned on line 1217, but not defined -- Looks like a reference, but probably isn't: '2' on line 1518 == Missing Reference: 'RFCXXXX' is mentioned on line 1681, but not defined == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-11 == Outdated reference: A later version (-03) exists of draft-bosh-dots-quick-blocks-01 == Outdated reference: A later version (-25) exists of draft-ietf-dots-telemetry-15 -- Obsolete informational reference (is this intentional?): RFC 8782 (Obsoleted by RFC 9132) Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group M. Boucadair 3 Internet-Draft Orange 4 Intended status: Standards Track J. Shallow 5 Expires: October 30, 2021 April 28, 2021 7 Constrained Application Protocol (CoAP) Block-Wise Transfer Options for 8 Faster Transmission 9 draft-ietf-core-new-block-11 11 Abstract 13 This document specifies alternative Constrained Application Protocol 14 (CoAP) Block-Wise transfer options: Q-Block1 and Q-Block2 Options. 16 These options are similar to the CoAP Block1 and Block2 Options 17 defined in RFC 7959, not a replacement for them, but do enable faster 18 transmission rates for large amounts of data with less packet 19 interchanges. Also, Q-Block1 and Q-Block2 Options support faster 20 recovery should any of the blocks get lost in transmission. 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 October 30, 2021. 39 Copyright Notice 41 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Alternative CoAP Block-Wise Transfer Options . . . . . . . . 4 59 3.1. CoAP Response Code (4.08) Usage . . . . . . . . . . . . . 6 60 3.2. Applicability Scope . . . . . . . . . . . . . . . . . . . 6 61 4. The Q-Block1 and Q-Block2 Options . . . . . . . . . . . . . . 7 62 4.1. Properties of Q-Block1 and Q-Block2 Options . . . . . . . 7 63 4.2. Structure of Q-Block1 and Q-Block2 Options . . . . . . . 9 64 4.3. Using the Q-Block1 Option . . . . . . . . . . . . . . . . 9 65 4.4. Using the Q-Block2 Option . . . . . . . . . . . . . . . . 13 66 4.5. Using Observe Option . . . . . . . . . . . . . . . . . . 16 67 4.6. Using Size1 and Size2 Options . . . . . . . . . . . . . . 16 68 4.7. Using Q-Block1 and Q-Block2 Options Together . . . . . . 16 69 4.8. Using Q-Block2 Option With Multicast . . . . . . . . . . 16 70 5. The Use of 4.08 (Request Entity Incomplete) Response Code . . 16 71 6. The Use of Tokens . . . . . . . . . . . . . . . . . . . . . . 18 72 7. Congestion Control for Unreliable Transports . . . . . . . . 18 73 7.1. Confirmable (CON) . . . . . . . . . . . . . . . . . . . . 18 74 7.2. Non-confirmable (NON) . . . . . . . . . . . . . . . . . . 19 75 8. Caching Considerations . . . . . . . . . . . . . . . . . . . 22 76 9. HTTP-Mapping Considerations . . . . . . . . . . . . . . . . . 24 77 10. Examples with Non-confirmable Messages . . . . . . . . . . . 24 78 10.1. Q-Block1 Option . . . . . . . . . . . . . . . . . . . . 24 79 10.1.1. A Simple Example . . . . . . . . . . . . . . . . . . 24 80 10.1.2. Handling MAX_PAYLOADS Limits . . . . . . . . . . . . 25 81 10.1.3. Handling MAX_PAYLOADS with Recovery . . . . . . . . 25 82 10.1.4. Handling Recovery with Failure . . . . . . . . . . . 27 83 10.2. Q-Block2 Option . . . . . . . . . . . . . . . . . . . . 27 84 10.2.1. A Simple Example . . . . . . . . . . . . . . . . . . 28 85 10.2.2. Handling MAX_PAYLOADS Limits . . . . . . . . . . . . 28 86 10.2.3. Handling MAX_PAYLOADS with Recovery . . . . . . . . 29 87 10.2.4. Handling Recovery using M-bit Set . . . . . . . . . 30 88 10.3. Q-Block1 and Q-Block2 Options . . . . . . . . . . . . . 31 89 10.3.1. A Simple Example . . . . . . . . . . . . . . . . . . 31 90 10.3.2. Handling MAX_PAYLOADS Limits . . . . . . . . . . . . 32 91 10.3.3. Handling Recovery . . . . . . . . . . . . . . . . . 33 92 11. Security Considerations . . . . . . . . . . . . . . . . . . . 35 93 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 94 12.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 36 95 12.2. Media Type Registration . . . . . . . . . . . . . . . . 36 96 12.3. CoAP Content-Formats Registry . . . . . . . . . . . . . 37 98 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 99 13.1. Normative References . . . . . . . . . . . . . . . . . . 38 100 13.2. Informative References . . . . . . . . . . . . . . . . . 39 101 Appendix A. Examples with Confirmable Messages . . . . . . . . . 40 102 A.1. Q-Block1 Option . . . . . . . . . . . . . . . . . . . . . 40 103 A.2. Q-Block2 Option . . . . . . . . . . . . . . . . . . . . . 42 104 Appendix B. Examples with Reliable Transports . . . . . . . . . 44 105 B.1. Q-Block1 Option . . . . . . . . . . . . . . . . . . . . . 44 106 B.2. Q-Block2 Option . . . . . . . . . . . . . . . . . . . . . 44 107 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 110 1. Introduction 112 The Constrained Application Protocol (CoAP) [RFC7252], although 113 inspired by HTTP, was designed to use UDP instead of TCP. The 114 message layer of CoAP over UDP includes support for reliable 115 delivery, simple congestion control, and flow control. [RFC7959] 116 introduced the CoAP Block1 and Block2 Options to handle data records 117 that cannot fit in a single IP packet, so not having to rely on IP 118 fragmentation and was further updated by [RFC8323] for use over TCP, 119 TLS, and WebSockets. 121 The CoAP Block1 and Block2 Options work well in environments where 122 there are no or minimal packet losses. These options operate 123 synchronously, i.e., each individual block has to be requested. A 124 CoAP endpoint can only ask for (or send) the next block when the 125 transfer of the previous block has completed. Packet transmission 126 rate, and hence block transmission rate, is controlled by Round Trip 127 Times (RTTs). 129 There is a requirement for these blocks of data to be transmitted at 130 higher rates under network conditions where there may be asymmetrical 131 transient packet loss (i.e., responses may get dropped). An example 132 is when a network is subject to a Distributed Denial of Service 133 (DDoS) attack and there is a need for DDoS mitigation agents relying 134 upon CoAP to communicate with each other (e.g., 135 [RFC8782][I-D.ietf-dots-telemetry]). As a reminder, [RFC7959] 136 recommends the use of Confirmable (CON) responses to handle potential 137 packet loss. However, such a recommendation does not work with a 138 flooded pipe DDoS situation. 140 This document introduces the CoAP Q-Block1 and Q-Block2 Options 141 (Section 3). 143 2. Terminology 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 Readers should be familiar with the terms and concepts defined in 152 [RFC7252], [RFC7959], and [RFC8132]. 154 The terms "payload" and "body" are defined in [RFC7959]. The term 155 "payload" is thus used for the content of a single CoAP message 156 (i.e., a single block being transferred), while the term "body" is 157 used for the entire resource representation that is being transferred 158 in a block-wise fashion. 160 3. Alternative CoAP Block-Wise Transfer Options 162 This document introduces the CoAP Q-Block1 and Q-Block2 Options. 163 These options are similar in operation to the CoAP Block1 and Block2 164 Options, respectively. They are not a replacement for them, but have 165 the following benefits: 167 o They can operate in environments where packet loss is highly 168 asymmetrical. 170 o They enable faster transmissions of sets of blocks of data with 171 less packet interchanges. 173 o They support faster recovery should any of the blocks get lost in 174 transmission. 176 o They support sending an entire body using Non-confirmable (NON) 177 messages without requiring a response from the peer. 179 There are the following disadvantages over using CoAP Block1 and 180 Block2 Options: 182 o Loss of lock-stepping so payloads are not always received in the 183 correct (block ascending) order. 185 o Additional congestion control measures need to be put in place for 186 NON messages (Section 7.2). 188 o To reduce the transmission times for CON transmission of large 189 bodies, NSTART needs to be increased from 1, but this affects 190 congestion control where other parameters need to be tuned 191 (Section 4.7 of [RFC7252]). Such tuning is out of scope of this 192 document. 194 o Mixing of NON and CON during requests/responses using Q-Block is 195 not supported. 197 o The Q-Block Options do not support stateless operation/random 198 access. 200 o Proxying of Q-Block is limited to caching full representations. 202 o There is no multicast support. 204 Q-Block1 and Q-Block2 Options are designed to work in particular with 205 NON requests and responses. 207 Using NON messages, the faster transmissions occur as all the blocks 208 can be transmitted serially (as are IP fragmented packets) without 209 having to wait for a response or next request from the remote CoAP 210 peer. Recovery of missing blocks is faster in that multiple missing 211 blocks can be requested in a single CoAP message. Even if there is 212 asymmetrical packet loss, a body can still be sent and received by 213 the peer whether the body comprises of a single or multiple payloads 214 assuming no recovery is required. 216 A CoAP endpoint can acknowledge all or a subset of the blocks. 217 Concretely, the receiving CoAP endpoint either informs the CoAP 218 sender endpoint of successful reception or reports on all blocks in 219 the body that have not yet been received. The CoAP sender endpoint 220 will then retransmit only the blocks that have been lost in 221 transmission. 223 Note that similar performance benefits can be applied to Confirmable 224 messages if the value of NSTART is increased from 1 (Section 4.7 of 225 [RFC7252]). However, the use of Confirmable messages will not work 226 if there is asymmetrical packet loss. Some examples with Confirmable 227 messages are provided in Appendix A. 229 There is little, if any, benefit of using these options with CoAP 230 running over a reliable connection [RFC8323]. In this case, there is 231 no differentiation between CON and NON as they are not used. Some 232 examples using a reliable transport are provided in Appendix B. 234 Q-Block1 and Q-Block2 Options can be used instead of Block1 and 235 Block2 Options when the different transmission properties are 236 required. If the new options are not supported by a peer, then 237 transmissions can fall back to using Block1 and Block2 Options 238 (Section 4.1). 240 The deviations from Block1 and Block2 Options are specified in 241 Section 4. Pointers to appropriate [RFC7959] sections are provided. 243 The specification refers to the base CoAP methods defined in 244 Section 5.8 of [RFC7252] and the new CoAP methods, FETCH, PATCH, and 245 iPATCH introduced in [RFC8132]. 247 The No-Response Option [RFC7967] was considered but was abandoned as 248 it does not apply to Q-Block2 responses. A unified solution is 249 defined in the document. 251 3.1. CoAP Response Code (4.08) Usage 253 This document adds a media type for the 4.08 (Request Entity 254 Incomplete) response defining an additional message format for 255 reporting on payloads using the Q-Block1 Option that are not received 256 by the server. 258 See Section 5 for more details. 260 3.2. Applicability Scope 262 The block-wise transfer specified in [RFC7959] covers the general 263 case, but falls short in situations where packet loss is highly 264 asymmetrical. The mechanism specified in this document provides 265 roughly similar features to the Block1/Block2 Options. It provides 266 additional properties that are tailored towards the intended use case 267 of Non-Confirmable transmission. Concretely, this mechanism 268 primarily targets applications such as DDoS Open Threat Signaling 269 (DOTS) that cannot use CON responses to handle potential packet loss 270 and that support application-specific mechanisms to assess whether 271 the remote peer is able to handle the messages sent by a CoAP 272 endpoint (e.g., DOTS heartbeats in Section 4.7 of [RFC8782]). 274 The mechanism includes guards to prevent a CoAP agent from 275 overloading the network by adopting an aggressive sending rate. 276 These guards MUST be followed in addition to the existing CoAP 277 congestion control as specified in Section 4.7 of [RFC7252]. See 278 Section 7 for more details. 280 This mechanism is not intended for general CoAP usage, and any use 281 outside the intended use case should be carefully weighed against the 282 loss of interoperability with generic CoAP applications. It is hoped 283 that the experience gained with this mechanism can feed future 284 extensions of the block-wise mechanism that will both be generally 285 applicable and serve this particular use case. 287 It is not recommended that these options are used in a NoSec security 288 mode (Section 9 of [RFC7252]) as the source endpoint needs to be 289 trusted. Using OSCORE [RFC8613] does provide a security context and, 290 hence, a trust of the source endpoint. However, using a NoSec 291 security mode may still be inadequate for reasons discussed in 292 Section 11. 294 4. The Q-Block1 and Q-Block2 Options 296 4.1. Properties of Q-Block1 and Q-Block2 Options 298 The properties of the Q-Block1 and Q-Block2 Options are shown in 299 Table 1. The formatting of this table follows the one used in 300 Table 4 of [RFC7252] (Section 5.10). The C, U, N, and R columns 301 indicate the properties Critical, UnSafe, NoCacheKey, and Repeatable 302 defined in Section 5.4 of [RFC7252]. Only Critical and UnSafe 303 columns are marked for the Q-Block1 Option. Critical, UnSafe, and 304 Repeatable columns are marked for the Q-Block2 Option. As these 305 options are UnSafe, NoCacheKey has no meaning and so is marked with a 306 dash. 308 +--------+---+---+---+---+--------------+--------+--------+---------+ 309 | Number | C | U | N | R | Name | Format | Length | Default | 310 +========+===+===+===+===+==============+========+========+=========+ 311 | TBA1 | x | x | - | | Q-Block1 | uint | 0-3 | (none) | 312 | TBA2 | x | x | - | x | Q-Block2 | uint | 0-3 | (none) | 313 +--------+---+---+---+---+--------------+--------+--------+---------+ 315 Table 1: CoAP Q-Block1 and Q-Block2 Option Properties 317 The Q-Block1 and Q-Block2 Options can be present in both the request 318 and response messages. The Q-Block1 Option pertains to the request 319 payload and the Q-Block2 Option pertains to the response payload. 320 When the Content-Format Option is present together with the Q-Block1 321 or Q-Block2 Option, the option applies to the body not to the payload 322 (i.e., it must be the same for all payloads of the same body). 324 Q-Block1 Option is useful with the payload-bearing POST, PUT, FETCH, 325 PATCH, and iPATCH requests and their responses. 327 Q-Block2 Option is useful with GET, POST, PUT, FETCH, PATCH, and 328 iPATCH requests and their payload-bearing responses (2.01, 2.02, 329 2.03, 2.04, and 2.05) (Section 5.5 of [RFC7252]). 331 A CoAP endpoint (or proxy) MUST support either both or neither of the 332 Q-Block1 and Q-Block2 Options. 334 If Q-Block1 Option is present in a request or Q-Block2 Option in a 335 response (i.e., in that message to the payload of which it pertains), 336 it indicates a block-wise transfer and describes how this specific 337 block-wise payload forms part of the entire body being transferred. 338 If it is present in the opposite direction, it provides additional 339 control on how that payload will be formed or was processed. 341 To indicate support for Q-Block2 responses, the CoAP client MUST 342 include the Q-Block2 Option in a GET or similar request (FETCH, for 343 example), the Q-Block2 Option in a PUT or similar request, or the 344 Q-Block1 Option in a PUT or similar request so that the server knows 345 that the client supports this Q-Block functionality should it need to 346 send back a body that spans multiple payloads. Otherwise, the server 347 would use the Block2 Option (if supported) to send back a message 348 body that is too large to fit into a single IP packet [RFC7959]. 350 How a client decides whether it needs to include a Q-Block1 or 351 Q-Block2 Option can be driven by a local configuration knob, 352 triggered by an application (DOTS, for example), etc. Such 353 considerations are out of the scope of the document. 355 Implementation of the Q-Block1 and Q-Block2 Options is intended to be 356 optional. However, when it is present in a CoAP message, it MUST be 357 processed (or the message rejected). Therefore, Q-Block1 and 358 Q-Block2 Options are identified as Critical options. 360 With CoAP over UDP, the way a request message is rejected for 361 critical options depends on the message type. A Confirmable message 362 with an unrecognized critical option is rejected with a 4.02 (Bad 363 Option) response (Section 5.4.1 of [RFC7252]). A Non-confirmable 364 message with an unrecognized critical option is either rejected with 365 a Reset message or just silently ignored (Sections 5.4.1 and 4.3 of 366 [RFC7252]). To reliably get a rejection message, it is therefore 367 REQUIRED that clients use a Confirmable message for determining 368 support for Q-Block1 and Q-Block2 Options. 370 The Q-Block1 and Q-Block2 Options are unsafe to forward. That is, a 371 CoAP proxy that does not understand the Q-Block1 (or Q-Block2) Option 372 MUST reject the request or response that uses either option. 374 The Q-Block2 Option is repeatable when requesting retransmission of 375 missing blocks, but not otherwise. Except that case, any request 376 carrying multiple Q-Block1 (or Q-Block2) Options MUST be handled 377 following the procedure specified in Section 5.4.5 of [RFC7252]. 379 The Q-Block1 and Q-Block2 Options, like the Block1 and Block2 380 Options, both of class E and class U for OSCORE processing (Table 2). 381 The Q-Block1 (or Q-Block2) Option MAY be an Inner or Outer option 382 (Section 4.1 of [RFC8613]). The Inner and Outer values are therefore 383 independent of each other. The Inner option is encrypted and 384 integrity protected between clients and servers, and provides message 385 body identification in case of end-to-end fragmentation of requests. 386 The Outer option is visible to proxies and labels message bodies in 387 case of hop-by-hop fragmentation of requests. 389 +--------+-----------------+---+---+ 390 | Number | Name | E | U | 391 +========+=================+===+===+ 392 | TBA1 | Q-Block1 | x | x | 393 | TBA2 | Q-Block2 | x | x | 394 +--------+-----------------+---+---+ 395 Table 2: OSCORE Protection of Q-Block1 and Q-Block2 Options 397 Note that if Q-Block1 or Q-Block2 Options are included in a packet as 398 Inner options, Block1 or Block2 Options MUST NOT be included as Inner 399 options. Similarly there MUST NOT be a mix of Q-Block and Block for 400 the Outer options. Messages that do not adhere with this behavior 401 MUST be rejected with 4.02 (Bad Option). Q-Block and Block Options 402 can be mixed across Inner and Outer options as these are handled 403 independently of each other. 405 4.2. Structure of Q-Block1 and Q-Block2 Options 407 The structure of Q-Block1 and Q-Block2 Options follows the structure 408 defined in Section 2.2 of [RFC7959]. 410 There is no default value for the Q-Block1 and Q-Block2 Options. 411 Absence of one of these options is equivalent to an option value of 0 412 with respect to the value of block number (NUM) and more bit (M) that 413 could be given in the option, i.e., it indicates that the current 414 block is the first and only block of the transfer (block number is 415 set to 0, M is unset). However, in contrast to the explicit value 0, 416 which would indicate a size of the block (SZX) of 0, and thus a size 417 value of 16 bytes, there is no specific explicit size implied by the 418 absence of the option -- the size is left unspecified. (As for any 419 uint, the explicit value 0 is efficiently indicated by a zero-length 420 option; this, therefore, is different in semantics from the absence 421 of the option). 423 4.3. Using the Q-Block1 Option 425 The Q-Block1 Option is used when the client wants to send a large 426 amount of data to the server using the POST, PUT, FETCH, PATCH, or 427 iPATCH methods where the data and headers do not fit into a single 428 packet. 430 When Q-Block1 Option is used, the client MUST include a Request-Tag 431 Option [I-D.ietf-core-echo-request-tag]. The Request-Tag value MUST 432 be the same for all of the requests for the body of data that is 433 being transferred. The Request-Tag is opaque, the server still 434 treats it as opaque but the client MUST ensure that it is unique for 435 every different body of transmitted data. 437 Implementation Note: It is suggested that the client treats the 438 Request-Tag as an unsigned integer of 8 bytes in length. An 439 implementation may want to consider limiting this to 4 bytes to 440 reduce packet overhead size. The initial Request-Tag value should 441 be randomly generated and then subsequently incremented by the 442 client whenever a new body of data is being transmitted between 443 peers. 445 Section 4.6 discusses the use of Size1 Option. 447 For Confirmable transmission, the server continues to acknowledge 448 each packet, but a response is not required (whether separate or 449 piggybacked) until successful receipt of the body by the server. For 450 Non-confirmable transmission, no response is required until the 451 successful receipt of the body by the server or some of the payloads 452 have not arrived after a timeout and a retransmit missing payloads 453 response is needed. For reliable transports (e.g., [RFC8323]), a 454 response is not required until successful receipt of the body by the 455 server. 457 Each individual message that carries a block of the body is treated 458 as a new request (Section 6). 460 The client MUST send the payloads with the block numbers increasing, 461 starting from zero, until the body is complete (subject to any 462 congestion control (Section 7)). Any missing payloads requested by 463 the server must in addition be separately transmitted with increasing 464 block numbers. 466 The following Response Codes are used: 468 2.01 (Created) 470 This Response Code indicates successful receipt of the entire body 471 and that the resource was created. The token used MUST be one of 472 the tokens that were received in a request for this block-wise 473 exchange. However, it is desirable to provide the one used in the 474 last received request, since that will aid any troubleshooting. 475 The client should then release all of the tokens used for this 476 body. Note that the last received payload may not be the one with 477 the highest block number. 479 2.02 (Deleted) 481 This Response Code indicates successful receipt of the entire body 482 and that the resource was deleted when using POST (Section 5.8.2 483 [RFC7252]). The token used MUST be one of the tokens that were 484 received in a request for this block-wise exchange. However, it 485 is desirable to provide the one used in the last received request. 486 The client should then release all of the tokens used for this 487 body. 489 2.04 (Changed) 491 This Response Code indicates successful receipt of the entire body 492 and that the resource was updated. The token used MUST be one of 493 the tokens that were received in a request for this block-wise 494 exchange. However, it is desirable to provide the one used in the 495 last received request. The client should then release all of the 496 tokens used for this body. 498 2.05 (Content) 500 This Response Code indicates successful receipt of the entire 501 FETCH request body (Section 2 of [RFC8132]) and that the 502 appropriate representation of the resource is being returned. The 503 token used MUST be one of the tokens that were received in a 504 request for this block-wise exchange. However, it is desirable to 505 provide the one used in the last received request. 507 If the FETCH request includes the Observe Option, then the server 508 MUST use the same token as used for the initial response for 509 returning any Observe triggered responses so that the client can 510 match them up. 512 The client should then release all of the tokens used for this 513 body unless a resource is being observed. 515 2.31 (Continue) 517 This Response Code can be used to indicate that all of the blocks 518 up to and including the Q-Block1 Option block NUM (all having the 519 M bit set) have been successfully received. The token used MUST 520 be one of the tokens that were received in a request for this 521 block-wise exchange. However, it is desirable to provide the one 522 used in the last received request. 524 A response using this Response Code SHOULD NOT be generated for 525 every received Q-Block1 Option request (Section 7.2). It SHOULD 526 only be generated when all the payload requests are Non- 527 confirmable and a set of MAX_PAYLOADS payloads have been received 528 by the server. More details about the motivations for this 529 optimization are discussed in Section 7.2. 531 This Response Code SHOULD NOT be generated for CON. 533 4.00 (Bad Request) 535 This Response Code MUST be returned if the request does not 536 include a Request-Tag Option or a Size1 Option but does include a 537 Q-Block1 option. 539 4.02 (Bad Option) 541 This Response Code MUST be returned for a Confirmable request if 542 the server does not support the Q-Block Options. Note that a 543 reset message must be sent in case of Non-confirmable request. 545 4.08 (Request Entity Incomplete) 547 As a reminder, this Response Code returned without Content-Type 548 "application/missing-blocks+cbor-seq" (Section 12.3) is handled as 549 in Section 2.9.2 [RFC7959]. 551 This Response Code returned with Content-Type "application/ 552 missing-blocks+cbor-seq" indicates that some of the payloads are 553 missing and need to be resent. The client then retransmits the 554 missing payloads using the same Request-Tag, Size1 and Q-Block1 to 555 specify the block NUM, SZX, and M bit as appropriate. 557 The Request-Tag value to use is determined by taking the token in 558 the 4.08 (Request Entity Incomplete) response, locating the 559 matching client request, and then using its Request-Tag. 561 The token used MUST be one of the tokens that were received in a 562 request for this block-wise exchange. However, it is desirable to 563 provide the one used in the last received request. See Section 5 564 for further information. 566 If the server has not received all the blocks of a body, but one 567 or more NON payloads have been received, it SHOULD wait for up to 568 NON_RECEIVE_TIMEOUT (Section 7.2) before sending a 4.08 (Request 569 Entity Incomplete) response. 571 4.13 (Request Entity Too Large) 573 This Response Code can be returned under similar conditions to 574 those discussed in Section 2.9.3 of [RFC7959]. 576 This Response Code can be returned if there is insufficient space 577 to create a response PDU with a block size of 16 bytes (SZX = 0) 578 to send back all the response options as appropriate. In this 579 case, the Size1 Option is not included in the response. 581 Further considerations related to the transmission timings of 4.08 582 (Request Entity Incomplete) and 2.31 (Continue) Response Codes are 583 discussed in Section 7.2. 585 If a server receives payloads with different Request-Tags for the 586 same resource, it should continue to process all the bodies as it has 587 no way of determining which is the latest version, or which body, if 588 any, the client is terminating the transmission for. 590 If the client elects to stop the transmission of a complete body, and 591 absent any local policy, the client MUST "forget" all tracked tokens 592 associated with the body's Request-Tag so that a reset message is 593 generated for the invalid token in the 4.08 (Request Entity 594 Incomplete) response. The server on receipt of the reset message 595 SHOULD delete the partial body. 597 If the server receives a duplicate block with the same Request-Tag, 598 it MUST ignore the payload of the packet, but MUST still respond as 599 if the block was received for the first time. 601 A server SHOULD maintain a partial body (missing payloads) for up to 602 NON_PARTIAL_TIMEOUT (Section 7.2). 604 4.4. Using the Q-Block2 Option 606 In a request for any block number, the M bit unset indicates the 607 request is just for that block. If the M bit is set, this has 608 different meanings based on the NUM value: 610 NUM is zero: This is a request for the entire body. 612 'NUM modulo MAX_PAYLOADS' is zero, while NUM is not zero: This is 613 used to confirm that the current set of MAX_PAYLOADS payloads (the 614 latest one having block number NUM-1) has been successfully 615 received and that, upon receipt of this request, the server can 616 continue to send the next set of payloads (the first one having 617 block number NUM). This is the 'Continue' Q-Block-2 and 618 conceptually has the same usage (i.e., continue sending the next 619 set of data) as the use of 2.31 (Continue) for Q-Block1. 621 Any other value of NUM: This is a request for that block and for all 622 of the remaining blocks in the current MAX_PAYLOADS set. 624 If the request includes multiple Q-Block2 Options and these options 625 overlap (e.g., combination of M being set (this and later blocks) and 626 being unset (this individual block)) resulting in an individual block 627 being requested multiple times, the server MUST only send back one 628 instance of that block. This behavior is meant to prevent 629 amplification attacks. 631 The payloads sent back from the server as a response MUST all have 632 the same ETag (Section 5.10.6 of [RFC7252]) for the same body. The 633 server MUST NOT use the same ETag value for different representations 634 of a resource. 636 The ETag is opaque, the client still treats it as opaque but the 637 server MUST ensure that it is unique for every different body of 638 transmitted data. 640 Implementation Note: It is suggested that the server treats the 641 ETag as an unsigned integer of 8 bytes in length. An 642 implementation may want to consider limiting this to 4 bytes to 643 reduce packet overhead size. The initial ETag value should be 644 randomly generated and then subsequently incremented by the server 645 whenever a new body of data is being transmitted between peers. 647 Section 4.6 discusses the use of Size2 Option. 649 The client may elect to request any detected missing blocks or just 650 ignore the partial body. This decision is implementation specific. 652 The client SHOULD wait for up to NON_RECEIVE_TIMEOUT (Section 7.2) 653 after the last received payload for NON payloads before issuing a 654 GET, POST, PUT, FETCH, PATCH, or iPATCH request that contains one or 655 more Q-Block2 Options that define the missing blocks with the M bit 656 unset. The client MAY set the M bit to request this and later blocks 657 from this MAX_PAYLOADS set. Further considerations related to the 658 transmission timing for missing requests are discussed in 659 Section 7.2. 661 The missing block numbers requested by the client MUST have an 662 increasing block number in each additional Q-Block2 Option with no 663 duplicates. The server SHOULD respond with a 4.00 (Bad Request) to 664 requests not adhering to this behavior. Note that the ordering 665 constraint is meant to force the client to check for duplicates and 666 remove them. This also helps with troubleshooting. 668 For Confirmable responses, the client continues to acknowledge each 669 packet. Typically, the server acknowledges the initial request using 670 an ACK with the payload, and then sends the subsequent payloads as 671 CON responses. The server will detect failure to send a packet, but 672 the client can issue, after a MAX_TRANSMIT_SPAN delay, a separate 673 GET, POST, PUT, FETCH, PATCH, or iPATCH for any missing blocks as 674 needed. 676 If the client receives a duplicate block with the same ETag, it MUST 677 silently ignore the payload. 679 A client SHOULD maintain a partial body (missing payloads) for up to 680 NON_PARTIAL_TIMEOUT (Section 7.2) or as defined by the Max-Age Option 681 (or its default of 60 seconds (Section 5.6.1 of [RFC7252])), 682 whichever is the less. On release of the partial body, the client 683 should then release all of the tokens used for this body unless a 684 resource is being observed. 686 The ETag Option should not be used in the request for missing blocks 687 as the server could respond with a 2.03 (Valid) response with no 688 payload. It can be used in the request if the client wants to check 689 the freshness of the locally cached body response. 691 It is RECOMMENDED that the server maintains a cached copy of the body 692 when using the Q-Block2 Option to facilitate retransmission of any 693 missing payloads. 695 If the server detects part way through a body transfer that the 696 resource data has changed and the server is not maintaining a cached 697 copy of the old data, then the transmission is terminated. Any 698 subsequent missing block requests MUST be responded to using the 699 latest ETag and Size2 Option values with the updated data. 701 If the server responds during a body update with a different ETag 702 Option value (as the resource representation has changed), then the 703 client should treat the partial body with the old ETag as no longer 704 being fresh. 706 If the server transmits a new body of data (e.g., a triggered Observe 707 notification) with a new ETag to the same client as an additional 708 response, the client should remove any partially received body held 709 for a previous ETag for that resource as it is unlikely the missing 710 blocks can be retrieved. 712 If there is insufficient space to create a response PDU with a block 713 size of 16 bytes (SZX = 0) to send back all the response options as 714 appropriate, a 4.13 (Request Entity Too Large) is returned without 715 the Size1 Option. 717 4.5. Using Observe Option 719 For a request that uses Q-Block1, the Observe value [RFC7641] MUST be 720 the same for all the payloads of the same body. This includes any 721 missing payloads that are retransmitted. 723 For a response that uses Q-Block2, the Observe value MUST be the same 724 for all the payloads of the same body. This is different from Block2 725 usage where the Observe value is only present in the first block 726 (Section 3.4 of [RFC7959]). This includes payloads transmitted 727 following receipt of the 'Continue' Q-Block2 Option (Section 4.4) by 728 the server. If a missing payload is requested by a client, then both 729 the request and response MUST NOT include the Observe Option. 731 4.6. Using Size1 and Size2 Options 733 Section 4 of [RFC7959] defines two CoAP options: Size1 for indicating 734 the size of the representation transferred in requests and Size2 for 735 indicating the size of the representation transferred in responses. 737 The Size1 or Size2 option values MUST exactly represent the size of 738 the data on the body so that any missing data can easily be 739 determined. 741 The Size1 Option MUST be used with the Q-Block1 Option when used in a 742 request and MUST be present in all payloads of the request preserving 743 the same value. The Size2 Option MUST be used with the Q-Block2 744 Option when used in a response and MUST be present in all payloads of 745 the response preserving the same value. 747 4.7. Using Q-Block1 and Q-Block2 Options Together 749 The behavior is similar to the one defined in Section 3.3 of 750 [RFC7959] with Q-Block1 substituted for Block1 and Q-Block2 for 751 Block2. 753 4.8. Using Q-Block2 Option With Multicast 755 Servers MUST ignore multicast requests that contain the Q-Block2 756 Option. As a reminder, Block2 Option can be used as stated in 757 Section 2.8 of [RFC7959]. 759 5. The Use of 4.08 (Request Entity Incomplete) Response Code 761 4.08 (Request Entity Incomplete) Response Code has a new Content-Type 762 "application/missing-blocks+cbor-seq" used to indicate that the 763 server has not received all of the blocks of the request body that it 764 needs to proceed. Such messages must not be treated by the client as 765 a fatal error. 767 Likely causes are the client has not sent all blocks, some blocks 768 were dropped during transmission, or the client has sent them 769 sufficiently long ago that the server has already discarded them. 771 The data payload of the 4.08 (Request Entity Incomplete) response is 772 encoded as a CBOR Sequence [RFC8742]. It comprises of one or more 773 missing block numbers encoded as CBOR unsigned integers [RFC8949]. 774 The missing block numbers MUST be unique in each 4.08 (Request Entity 775 Incomplete) response when created by the server; the client MUST 776 ignore any duplicates in the same 4.08 (Request Entity Incomplete) 777 response. 779 The Content-Format Option (Section 5.10.3 of [RFC7252]) MUST be used 780 in the 4.08 (Request Entity Incomplete) response. It MUST be set to 781 "application/missing-blocks+cbor-seq" (Section 12.3). 783 The Concise Data Definition Language [RFC8610] (and see Section 4.1 784 [RFC8742]) for the data describing these missing blocks is as 785 follows: 787 ; A notional array, the elements of which are to be used 788 ; in a CBOR Sequence: 789 payload = [+ missing-block-number] 790 ; A unique block number not received: 791 missing-block-number = uint 793 Figure 1: Structure of the Missing Blocks Payload 795 The token to use for the response SHOULD be the token that was used 796 in the last block number received so far with the same Request-Tag 797 value. Note that the use of any received token with the same 798 Request-Tag would be acceptable, but providing the one used in the 799 last received payload will aid any troubleshooting. The client will 800 use the token to determine what was the previously sent request to 801 obtain the Request-Tag value to be used. 803 If the size of the 4.08 (Request Entity Incomplete) response packet 804 is larger than that defined by Section 4.6 [RFC7252], then the number 805 of missing blocks MUST be limited so that the response can fit into a 806 single packet. If this is the case, then the server can send 807 subsequent 4.08 (Request Entity Incomplete) responses containing the 808 missing other blocks on receipt of a new request providing a missing 809 payload with the same Request-Tag. 811 The missing blocks MUST be reported in ascending order without any 812 duplicates. The client SHOULD silently drop 4.08 (Request Entity 813 Incomplete) responses not adhering with this behavior. 815 Implementation Note: Consider limiting the number of missing 816 payloads to MAX_PAYLOADS to minimize congestion control being 817 needed. The CBOR sequence does not include any array wrapper. 819 The 4.08 (Request Entity Incomplete) with Content-Type "application/ 820 missing-blocks+cbor-seq" SHOULD NOT be used when using Confirmable 821 requests or a reliable connection [RFC8323] as the client will be 822 able to determine that there is a transmission failure of a 823 particular payload and hence that the server is missing that payload. 825 6. The Use of Tokens 827 Each new request generally uses a new Token (and sometimes must, see 828 Section 4 of [I-D.ietf-core-echo-request-tag]). Additional responses 829 to a request all use the token of the request they respond to. 831 Implementation Note: By using 8-byte tokens, it is possible to 832 easily minimize the number of tokens that have to be tracked by 833 clients, by keeping the bottom 32 bits the same for the same body 834 and the upper 32 bits containing the current body's request number 835 (incrementing every request, including every re-transmit). This 836 allows the client to be alleviated from keeping all the per- 837 request-state, e.g., in Section 3 of [RFC8974]. 839 7. Congestion Control for Unreliable Transports 841 The transmission of all the blocks of a single body over an 842 unreliable transport MUST either all be Confirmable or all be Non- 843 confirmable. This is meant to simplify the congestion control 844 procedure. 846 As a reminder, there is no need for CoAP-specific congestion control 847 for reliable transports [RFC8323]. 849 7.1. Confirmable (CON) 851 Congestion control for CON requests and responses is specified in 852 Section 4.7 of [RFC7252]. For faster transmission rates, NSTART will 853 need to be increased from 1. However, the other CON congestion 854 control parameters will need to be tuned to cover this change. This 855 tuning is out of scope of this document as it is expected that all 856 requests and responses using Q-Block1 and Q-Block2 will be Non- 857 confirmable (Section 3.2). 859 It is implementation specific as to whether there should be any 860 further requests for missing data as there will have been significant 861 transmission failure as individual payloads will have failed after 862 MAX_TRANSMIT_SPAN. 864 7.2. Non-confirmable (NON) 866 This document introduces new parameters MAX_PAYLOADS, NON_TIMEOUT, 867 NON_RECEIVE_TIMEOUT, NON_MAX_RETRANSMIT, NON_PROBING_WAIT, and 868 NON_PARTIAL_TIMEOUT primarily for use with NON (Table 3). 870 MAX_PAYLOADS should be configurable with a default value of 10. Both 871 CoAP endpoints SHOULD have the same value (otherwise there will be 872 transmission delays in one direction) and the value MAY be negotiated 873 between the endpoints to a common value by using a higher level 874 protocol (out of scope of this document). This is the maximum number 875 of payloads that can be transmitted at any one time. 877 Note: The default value of 10 is chosen for reasons similar to 878 those discussed in Section 5 of [RFC6928]. 880 NON_TIMEOUT is the maximum period of delay between sending sets of 881 MAX_PAYLOADS payloads for the same body. By default, NON_TIMEOUT has 882 the same value as ACK_TIMEOUT (Section 4.8 of [RFC7252]). 884 NON_RECEIVE_TIMEOUT is the initial maximum time to wait for a missing 885 payload before requesting retransmission for the first time. Every 886 time the missing payload is re-requested, the time to wait value 887 doubles. The time to wait is calculated as: 889 Time-to-Wait = NON_RECEIVE_TIMEOUT * (2 ** (Re-Request-Count - 1)) 891 NON_RECEIVE_TIMEOUT has a default value of twice NON_TIMEOUT. 892 NON_RECEIVE_TIMEOUT MUST always be greater than NON_TIMEOUT by at 893 least one second so that the sender of the payloads has the 894 opportunity to start sending the next set of payloads before the 895 receiver times out. 897 NON_MAX_RETRANSMIT is the maximum number of times a request for the 898 retransmission of missing payloads can occur without a response from 899 the remote peer. After this occurs, the local endpoint SHOULD 900 consider the body stale, remove any body, and release Tokens and 901 Request-Tag on the client (or the ETag on the server). By default, 902 NON_MAX_RETRANSMIT has the same value as MAX_RETRANSMIT (Section 4.8 903 of [RFC7252]). 905 NON_PROBING_WAIT is used to limit the potential wait needed 906 calculated when using PROBING_WAIT. NON_PROBING_WAIT has the same 907 value as computed for EXCHANGE_LIFETIME (Section 4.8.2 of [RFC7252]). 909 NON_PARTIAL_TIMEOUT is used for expiring partially received bodies. 910 NON_PARTIAL_TIMEOUT has the same value as computed for 911 EXCHANGE_LIFETIME (Section 4.8.2 of [RFC7252]). 913 +---------------------+---------------+ 914 | Parameter Name | Default Value | 915 +=====================+===============| 916 | MAX_PAYLOADS | 10 | 917 | NON_MAX_RETRANSMIT | 4 | 918 | NON_TIMEOUT | 2 s | 919 | NON_RECEIVE_TIMEOUT | 4 s | 920 | NON_PROBING_WAIT | 247 s | 921 | NON_PARTIAL_TIMEOUT | 247 s | 922 +---------------------+---------------+ 924 Table 3: Congestion Control Parameters 926 PROBING_RATE parameter in CoAP indicates the average data rate that 927 must not be exceeded by a CoAP endpoint in sending to a peer endpoint 928 that does not respond. The single body of blocks will be subjected 929 to PROBING_RATE (Section 4.7 of [RFC7252]), not the individual 930 packets. If the wait time between sending bodies that are not being 931 responded to based on PROBING_RATE exceeds NON_PROBING_WAIT, then the 932 gap time is limited to NON_PROBING_WAIT. 934 Note: For the particular DOTS application, PROBING_RATE and other 935 transmission parameters are negotiated between peers. Even when 936 not negotiated, the DOTS application uses customized defaults as 937 discussed in Section 4.5.2 of [RFC8782]. Note that MAX_PAYLOADS, 938 NON_MAX_RETRANSMIT, and NON_TIMEOUT can be negotiated between DOTS 939 peers as per [I-D.bosh-dots-quick-blocks]. 941 Each NON 4.08 (Request Entity Incomplete) response is subject to 942 PROBING_RATE. 944 Each NON GET or FETCH request using Q-Block2 Option is subject to 945 PROBING_RATE. 947 As the sending of many payloads of a single body may itself cause 948 congestion, it is RECOMMENDED that after transmission of every set of 949 MAX_PAYLOADS payloads of a single body, a delay is introduced of 950 NON_TIMEOUT before sending the next set of payloads to manage 951 potential congestion issues. 953 If the CoAP peer reports at least one payload has not arrived for 954 each body for at least a 24 hour period and it is known that there 955 are no other network issues over that period, then the value of 956 MAX_PAYLOADS can be reduced by 1 at a time (to a minimum of 1) and 957 the situation re-evaluated for another 24 hour period until there is 958 no report of missing payloads under normal operating conditions. The 959 newly derived value for MAX_PAYLOADS should be used for both ends of 960 this particular CoAP peer link. Note that the CoAP peer will not 961 know about the MAX_PAYLOADS change until it is reconfigured. As a 962 consequence of the two peers having different MAX_PAYLOADS values, a 963 peer may continue indicate that there are some missing payloads as 964 all of its MAX_PAYLOADS set may not have arrived. How the two peer 965 values for MAX_PAYLOADS are synchronized is out of the scope. 967 The sending of a set of missing blocks of a body is subject to 968 MAX_PAYLOADS set of payloads. 970 For Q-Block1 Option, if the server responds with a 2.31 (Continue) 971 Response Code for the latest payload sent, then the client can 972 continue to send the next set of payloads without any delay. If the 973 server responds with a 4.08 (Request Entity Incomplete) Response 974 Code, then the missing payloads SHOULD be retransmitted before going 975 into another NON_TIMEOUT delay prior to sending the next set of 976 payloads. 978 For the server receiving NON Q-Block1 requests, it SHOULD send back a 979 2.31 (Continue) Response Code on receipt of all of the MAX_PAYLOADS 980 payloads to prevent the client unnecessarily delaying. If not all of 981 the MAX_PAYLOADS payloads were received, the server SHOULD delay for 982 NON_RECEIVE_TIMEOUT (exponentially scaled based on the repeat request 983 count for a payload) before sending the 4.08 (Request Entity 984 Incomplete) Response Code for the missing payload(s). If this is a 985 repeat for the 2.31 (Continue) response, the server SHOULD send a 986 4.08 (Request Entity Incomplete) response detailing the missing 987 payloads after the block number that would have been indicated in the 988 2.31 (Continue). If the repeat request count for a missing payload 989 exceeds NON_MAX_RETRANSMIT, the server SHOULD discard the partial 990 body and stop requesting the missing payloads. 992 It is likely that the client will start transmitting the next set of 993 MAX_PAYLOADS payloads before the server times out on waiting for the 994 last of the previous MAX_PAYLOADS payloads. On receipt of the first 995 payload from the new set of MAX_PAYLOADS payloads, the server SHOULD 996 send a 4.08 (Request Entity Incomplete) Response Code indicating any 997 missing payloads from any previous MAX_PAYLOADS payloads. Upon 998 receipt of the 4.08 (Request Entity Incomplete) Response Code, the 999 client SHOULD send the missing payloads before continuing to send the 1000 remainder of the MAX_PAYLOADS payloads and then go into another 1001 NON_TIMEOUT delay prior to sending the next set of payloads. 1003 For the client receiving NON Q-Block2 responses, it SHOULD send a 1004 'Continue' Q-Block2 request (Section 4.4) for the next set of 1005 payloads on receipt of all of the MAX_PAYLOADS payloads to prevent 1006 the server unnecessarily delaying. Otherwise the client SHOULD delay 1007 for NON_RECEIVE_TIMEOUT (exponentially scaled based on the repeat 1008 request count for a payload), before sending the request for the 1009 missing payload(s). If the repeat request count for a missing 1010 payload exceeds NON_MAX_RETRANSMIT, the client SHOULD discard the 1011 partial body and stop requesting the missing payloads. 1013 The server SHOULD recognize the 'Continue' Q-Block2 request as a 1014 continue request and just continue the transmission of the body 1015 (including Observe Option, if appropriate for an unsolicited 1016 response) rather than as a request for the remaining missing blocks. 1018 It is likely that the server will start transmitting the next set of 1019 MAX_PAYLOADS payloads before the client times out on waiting for the 1020 last of the previous MAX_PAYLOADS payloads. Upon receipt of the 1021 first payload from the new set of MAX_PAYLOADS payloads, the client 1022 SHOULD send a request indicating any missing payloads from any 1023 previous set of MAX_PAYLOADS payloads. Upon receipt of such request, 1024 the server SHOULD send the missing payloads before continuing to send 1025 the remainder of the MAX_PAYLOADS payloads and then go into another 1026 NON_TIMEOUT delay prior to sending the next set of payloads. 1028 The client does not need to acknowledge the receipt of the entire 1029 body. 1031 Note: If there is asymmetric traffic loss causing responses to 1032 never get received, a delay of NON_TIMEOUT after every 1033 transmission of MAX_PAYLOADS blocks will be observed. The 1034 endpoint receiving the body is still likely to receive the entire 1035 body. 1037 8. Caching Considerations 1039 Caching block based information is not straight forward in a proxy. 1040 For Q-Block1 and Q-Block2 Options, for simplicity it is expected that 1041 the proxy will reassemble the body (using any appropriate recovery 1042 options for packet loss) before passing on the body to the 1043 appropriate CoAP endpoint. This does not preclude an implementation 1044 doing a more complex per payload caching, but how to do this is out 1045 of the scope of this document. The onward transmission of the body 1046 does not require the use of the Q-Block1 or Q-Block2 Options as these 1047 options may not be supported in that link. This means that the proxy 1048 must fully support the Q-Block1 and Q-Block2 Options. 1050 How the body is cached in the CoAP client (for Q-Block1 1051 transmissions) or the CoAP server (for Q-Block2 transmissions) is 1052 implementation specific. 1054 As the entire body is being cached in the proxy, the Q-Block1 and 1055 Q-Block2 Options are removed as part of the block assembly and thus 1056 do not reach the cache. 1058 For Q-Block2 responses, the ETag Option value is associated with the 1059 data (and onward transmitted to the CoAP client), but is not part of 1060 the cache key. 1062 For requests with Q-Block1 Option, the Request-Tag Option is 1063 associated with the build up of the body from successive payloads, 1064 but is not part of the cache key. For the onward transmission of the 1065 body using CoAP, a new Request-Tag SHOULD be generated and used. 1066 Ideally this new Request-Tag should replace the client's request 1067 Request-Tag. 1069 It is possible that two or more CoAP clients are concurrently 1070 updating the same resource through a common proxy to the same CoAP 1071 server using Q-Block1 (or Block1) Option. If this is the case, the 1072 first client to complete building the body causes that body to start 1073 transmitting to the CoAP server with an appropriate Request-Tag 1074 value. When the next client completes building the body, any 1075 existing partial body transmission to the CoAP server is terminated 1076 and the new body representation transmission starts with a new 1077 Request-Tag value. Note that it cannot be assumed that the proxy 1078 will always receive a complete body from a client. 1080 A proxy that supports Q-Block2 Option MUST be prepared to receive a 1081 GET or similar request indicating one or more missing blocks. The 1082 proxy will serve from its cache the missing blocks that are available 1083 in its cache in the same way a server would send all the appropriate 1084 Q-Block2 responses. If the cache key matching body is not available 1085 in the cache, the proxy MUST request the entire body from the CoAP 1086 server using the information in the cache key. 1088 How long a CoAP endpoint (or proxy) keeps the body in its cache is 1089 implementation specific (e.g., it may be based on Max-Age). 1091 9. HTTP-Mapping Considerations 1093 As a reminder, the basic normative requirements on HTTP/CoAP mappings 1094 are defined in Section 10 of [RFC7252]. The implementation 1095 guidelines for HTTP/CoAP mappings are elaborated in [RFC8075]. 1097 The rules defined in Section 5 of [RFC7959] are to be followed. 1099 10. Examples with Non-confirmable Messages 1101 This section provides some sample flows to illustrate the use of 1102 Q-Block1 and Q-Block2 Options with NON. Examples with CON are 1103 provided in Appendix A. 1105 The examples in the following subsections assume MAX_PAYLOADS is set 1106 to 10 and NON_MAX_RETRANSMIT is set to 4. 1108 Figure 2 lists the conventions that are used in the following 1109 subsections. 1111 T: Token value 1112 O: Observe Option value 1113 M: Message ID 1114 RT: Request-Tag 1115 ET: ETag 1116 QB1: Q-Block1 Option values NUM/More/SZX 1117 QB2: Q-Block2 Option values NUM/More/SZX 1118 \: Trimming long lines 1119 [[]]: Comments 1120 -->X: Message loss (request) 1121 X<--: Message loss (response) 1122 ...: Passage of time 1123 Payload N: Corresponds to the CoAP message that conveys 1124 a block number (N-1) of a given block-wise exchange. 1126 Figure 2: Notations Used in the Figures 1128 10.1. Q-Block1 Option 1130 10.1.1. A Simple Example 1132 Figure 3 depicts an example of a NON PUT request conveying Q-Block1 1133 Option. All the blocks are received by the server. 1135 CoAP CoAP 1136 Client Server 1137 | | 1138 +--------->| NON PUT /path M:0x81 T:0xc0 RT=9 QB1:0/1/1024 1139 +--------->| NON PUT /path M:0x82 T:0xc1 RT=9 QB1:1/1/1024 1140 +--------->| NON PUT /path M:0x83 T:0xc2 RT=9 QB1:2/1/1024 1141 +--------->| NON PUT /path M:0x84 T:0xc3 RT=9 QB1:3/0/1024 1142 |<---------+ NON 2.04 M:0xf1 T:0xc3 1143 | ... | 1145 Figure 3: Example of NON Request with Q-Block1 Option (Without Loss) 1147 10.1.2. Handling MAX_PAYLOADS Limits 1149 Figure 4 depicts an example of a NON PUT request conveying Q-Block1 1150 Option. The number of payloads exceeds MAX_PAYLOADS. All the blocks 1151 are received by the server. 1153 CoAP CoAP 1154 Client Server 1155 | | 1156 +--------->| NON PUT /path M:0x01 T:0xf1 RT=10 QB1:0/1/1024 1157 +--------->| NON PUT /path M:0x02 T:0xf2 RT=10 QB1:1/1/1024 1158 +--------->| [[Payloads 3 - 9 not detailed]] 1159 +--------->| NON PUT /path M:0x0a T:0xfa RT=10 QB1:9/1/1024 1160 [[MAX_PAYLOADS has been reached]] 1161 | [[MAX_PAYLOADS blocks receipt acknowledged by server]] 1162 |<---------+ NON 2.31 M:0x81 T:0xfa 1163 +--------->| NON PUT /path M:0x0b T:0xfb RT=10 QB1:10/0/1024 1164 |<---------+ NON 2.04 M:0x82 T:0xfb 1165 | ... | 1167 Figure 4: Example of MAX_PAYLOADS NON Request with Q-Block1 Option 1168 (Without Loss) 1170 10.1.3. Handling MAX_PAYLOADS with Recovery 1172 Consider now a scenario where a new body of data is to be sent by the 1173 client, but some blocks are dropped in transmission as illustrated in 1174 Figure 5. 1176 CoAP CoAP 1177 Client Server 1178 | | 1179 +--------->| NON PUT /path M:0x11 T:0xe1 RT=11 QB1:0/1/1024 1180 +--->X | NON PUT /path M:0x12 T:0xe2 RT=11 QB1:1/1/1024 1181 +--------->| [[Payloads 3 - 8 not detailed]] 1182 +--------->| NON PUT /path M:0x19 T:0xe9 RT=11 QB1:8/1/1024 1183 +--->X | NON PUT /path M:0x1a T:0xea RT=11 QB1:9/1/1024 1184 [[MAX_PAYLOADS has been reached]] 1185 | ... | 1186 [[NON_TIMEOUT (client) delay expires]] 1187 | [[Client starts sending next set of payloads]] 1188 +--->X | NON PUT /path M:0x1b T:0xeb RT=11 QB1:10/1/1024 1189 +--------->| NON PUT /path M:0x1c T:0xec RT=11 QB1:11/1/1024 1190 | | 1192 Figure 5: Example of MAX_PAYLOADS NON Request with Q-Block1 Option 1193 (With Loss) 1195 On seeing a payload from the next set of payloads, the server 1196 realizes that some blocks are missing from the previous MAX_PAYLOADS 1197 payloads and asks for the missing blocks in one go (Figure 6). It 1198 does so by indicating which blocks from the previous MAX_PAYLOADS 1199 payloads have not been received in the data portion of the response. 1200 The token used in the response should be the token that was used in 1201 the last received payload. The client can then derive the Request- 1202 Tag by matching the token with the sent request. 1204 CoAP CoAP 1205 Client Server 1206 | | 1207 |<---------+ NON 4.08 M:0x91 T:0xec [Missing 1,9] 1208 | [[Client responds with missing payloads]] 1209 +--------->| NON PUT /path M:0x1d T:0xed RT=11 QB1:1/1/1024 1210 +--------->| NON PUT /path M:0x1e T:0xee RT=11 QB1:9/1/1024 1211 | [[Client continues sending next set of payloads]] 1212 +--------->| NON PUT /path M:0x1f T:0xef RT=11 QB1:12/0/1024 1213 | ... | 1214 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1215 | [[The server realizes a block is still missing and asks 1216 | for the missing one]] 1217 |<---------+ NON 4.08 M:0x92 T:0xef [Missing 10] 1218 +--------->| NON PUT /path M:0x20 T:0xf0 RT=11 QB1:10/1/1024 1219 |<---------+ NON 2.04 M:0x93 T:0xf0 1220 | ... | 1222 Figure 6: Example of NON Request with Q-Block1 Option (Blocks 1223 Recovery) 1225 10.1.4. Handling Recovery with Failure 1227 Figure 7 depicts an example of a NON PUT request conveying Q-Block1 1228 Option where recovery takes place, but eventually fails. 1230 CoAP CoAP 1231 Client Server 1232 | | 1233 +--------->| NON PUT /path M:0x91 T:0xd0 RT=12 QB1:0/1/1024 1234 +--->X | NON PUT /path M:0x92 T:0xd1 RT=12 QB1:1/1/1024 1235 +--------->| NON PUT /path M:0x93 T:0xd2 RT=12 QB1:2/0/1024 1236 | ... | 1237 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1238 | [[The server realizes a block is missing and asks 1239 | for the missing one. Retry #1]] 1240 |<---------+ NON 4.08 M:0x01 T:0xd2 [Missing 1] 1241 | ... | 1242 [[2 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1243 | [[The server realizes a block is still missing and asks 1244 | for the missing one. Retry #2]] 1245 |<---------+ NON 4.08 M:0x02 T:0xd2 [Missing 1] 1246 | ... | 1247 [[4 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1248 | [[The server realizes a block is still missing and asks 1249 | for the missing one. Retry #3]] 1250 |<---------+ NON 4.08 M:0x03 T:0xd2 [Missing 1] 1251 | ... | 1252 [[8 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1253 | [[The server realizes a block is still missing and asks 1254 | for the missing one. Retry #4]] 1255 |<---------+ NON 4.08 M:0x04 T:0xd2 [Missing 1] 1256 | ... | 1257 [[16 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1258 | [[NON_MAX_RETRANSMIT exceeded. Server stops requesting 1259 | for missing blocks and releases partial body]] 1260 | ... | 1262 Figure 7: Example of NON Request with Q-Block1 Option (With Eventual 1263 Failure) 1265 10.2. Q-Block2 Option 1267 These examples include the Observe Option to demonstrate how that 1268 option is used. Note that the Observe Option is not required for 1269 Q-Block2; the observe detail can thus be ignored. 1271 10.2.1. A Simple Example 1273 Figure 8 illustrates the example of Q-Block2 Option. The client 1274 sends a NON GET carrying Observe and Q-Block2 Options. The Q-Block2 1275 Option indicates a block size hint (1024 bytes). This request is 1276 replied to by the server using four (4) blocks that are transmitted 1277 to the client without any loss. Each of these blocks carries a 1278 Q-Block2 Option. The same process is repeated when an Observe is 1279 triggered, but no loss is experienced by any of the notification 1280 blocks. 1282 CoAP CoAP 1283 Client Server 1284 | | 1285 +--------->| NON GET /path M:0x01 T:0xc0 O:0 QB2:0/1/1024 1286 |<---------+ NON 2.05 M:0xf1 T:0xc0 O:1220 ET=19 QB2:0/1/1024 1287 |<---------+ NON 2.05 M:0xf2 T:0xc0 O:1220 ET=19 QB2:1/1/1024 1288 |<---------+ NON 2.05 M:0xf3 T:0xc0 O:1220 ET=19 QB2:2/1/1024 1289 |<---------+ NON 2.05 M:0xf4 T:0xc0 O:1220 ET=19 QB2:3/0/1024 1290 | ... | 1291 | [[Observe triggered]] 1292 |<---------+ NON 2.05 M:0xf5 T:0xc0 O:1221 ET=20 QB2:0/1/1024 1293 |<---------+ NON 2.05 M:0xf6 T:0xc0 O:1221 ET=20 QB2:1/1/1024 1294 |<---------+ NON 2.05 M:0xf7 T:0xc0 O:1221 ET=20 QB2:2/1/1024 1295 |<---------+ NON 2.05 M:0xf8 T:0xc0 O:1221 ET=20 QB2:3/0/1024 1296 | ... | 1298 Figure 8: Example of NON Notifications with Q-Block2 Option (Without 1299 Loss) 1301 10.2.2. Handling MAX_PAYLOADS Limits 1303 Figure 9 illustrates the same as Figure 8 but this time has eleven 1304 (11) payloads which exceeds MAX_PAYLOADS. There is no loss 1305 experienced. 1307 CoAP CoAP 1308 Client Server 1309 | | 1310 +--------->| NON GET /path M:0x01 T:0xf0 O:0 QB2:0/1/1024 1311 |<---------+ NON 2.05 M:0x81 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1312 |<---------+ NON 2.05 M:0x82 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1313 |<---------+ [[Payloads 3 - 9 not detailed]] 1314 |<---------+ NON 2.05 M:0x8a T:0xf0 O:1234 ET=21 QB2:9/1/1024 1315 [[MAX_PAYLOADS has been reached]] 1316 | [[MAX_PAYLOADS blocks acknowledged by client using 1317 | 'Continue' Q-Block2]] 1318 +--------->| NON GET /path M:0x02 T:0xf1 QB2:10/1/1024 1319 |<---------+ NON 2.05 M:0x8b T:0xf0 O:1234 ET=21 QB2:10/0/1024 1320 | ... | 1321 | [[Observe triggered]] 1322 |<---------+ NON 2.05 M:0x91 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1323 |<---------+ NON 2.05 M:0x92 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1324 |<---------+ [[Payloads 3 - 9 not detailed]] 1325 |<---------+ NON 2.05 M:0x9a T:0xf0 O:1235 ET=22 QB2:9/1/1024 1326 [[MAX_PAYLOADS has been reached]] 1327 | [[MAX_PAYLOADS blocks acknowledged by client using 1328 | 'Continue' Q-Block2]] 1329 +--------->| NON GET /path M:0x03 T:0xf2 QB2:10/1/1024 1330 |<---------+ NON 2.05 M:0x9b T:0xf0 O:1235 ET=22 QB2:10/0/1024 1331 [[Body has been received]] 1332 | ... | 1334 Figure 9: Example of NON Notifications with Q-Block2 Option (Without 1335 Loss) 1337 10.2.3. Handling MAX_PAYLOADS with Recovery 1339 Figure 10 shows the example of an Observe that is triggered but for 1340 which some notification blocks are lost. The client detects the 1341 missing blocks and requests their retransmission. It does so by 1342 indicating the blocks that are missing as one or more Q-Block2 1343 Options. 1345 CoAP CoAP 1346 Client Server 1347 | ... | 1348 | [[Observe triggered]] 1349 |<---------+ NON 2.05 M:0xa1 T:0xf0 O:1236 ET=23 QB2:0/1/1024 1350 | X<---+ NON 2.05 M:0xa2 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1351 |<---------+ [[Payloads 3 - 9 not detailed]] 1352 | X<---+ NON 2.05 M:0xaa T:0xf0 O:1236 ET=23 QB2:9/1/1024 1353 [[MAX_PAYLOADS has been reached]] 1354 | ... | 1355 [[NON_TIMEOUT (server) delay expires]] 1356 | [[Server sends next set of payloads]] 1357 |<---------+ NON 2.05 M:0xab T:0xf0 O:1236 ET=23 QB2:10/0/1024 1358 | ... | 1359 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1360 | [[Client realizes blocks are missing and asks for the 1361 | missing ones in one go]] 1362 +--------->| NON GET /path M:0x04 T:0xf3 QB2:1/0/1024\ 1363 | | QB2:9/0/1024 1364 | X<---+ NON 2.05 M:0xac T:0xf3 ET=23 QB2:1/1/1024 1365 |<---------+ NON 2.05 M:0xad T:0xf3 ET=23 QB2:9/1/1024 1366 | ... | 1367 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1368 | [[Client realizes block is still missing and asks for 1369 | missing block]] 1370 +--------->| NON GET /path M:0x05 T:0xf4 QB2:1/0/1024 1371 |<---------+ NON 2.05 M:0xae T:0xf4 ET=23 QB2:1/1/1024 1372 [[Body has been received]] 1373 | ... | 1375 Figure 10: Example of NON Notifications with Q-Block2 Option (Blocks 1376 Recovery) 1378 10.2.4. Handling Recovery using M-bit Set 1380 Figure 11 shows the example of an Observe that is triggered but only 1381 the first two notification blocks reach the client. In order to 1382 retrieve the missing blocks, the client sends a request with a single 1383 Q-Block2 Option with the M bit set. 1385 CoAP CoAP 1386 Client Server 1387 | ... | 1388 | [[Observe triggered]] 1389 |<---------+ NON 2.05 M:0xb1 T:0xf0 O:1237 ET=24 QB2:0/1/1024 1390 |<---------+ NON 2.05 M:0xb2 T:0xf0 O:1237 ET=24 QB2:1/1/1024 1391 | X<---+ NON 2.05 M:0xb3 T:0xf0 O:1237 ET=24 QB2:2/1/1024 1392 | X<---+ [[Payloads 4 - 9 not detailed]] 1393 | X<---+ NON 2.05 M:0xb9 T:0xf0 O:1237 ET=24 QB2:9/1/1024 1394 [[MAX_PAYLOADS has been reached]] 1395 | ... | 1396 [[NON_TIMEOUT (server) delay expires]] 1397 | [[Server sends next set of payloads]] 1398 | X<---+ NON 2.05 M:0xba T:0xf0 O:1237 ET=24 QB2:10/0/1024 1399 | ... | 1400 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1401 | [[Client realizes blocks are missing and asks for the 1402 | missing ones in one go by setting the M bit]] 1403 +--------->| NON GET /path M:0x06 T:0xf5 QB2:2/1/1024 1404 |<---------+ NON 2.05 M:0xbb T:0xf5 ET=24 QB2:2/1/1024 1405 |<---------+ [[Payloads 3 - 9 not detailed]] 1406 |<---------+ NON 2.05 M:0xc2 T:0xf5 ET=24 QB2:9/1/1024 1407 [[MAX_PAYLOADS has been reached]] 1408 | [[MAX_PAYLOADS acknowledged by client using 'Continue' 1409 | Q-Block2]] 1410 +--------->| NON GET /path M:0x87 T:0xf6 QB2:10/1/1024 1411 |<---------+ NON 2.05 M:0xc3 T:0xf0 O:1237 ET=24 QB2:10/0/1024 1412 [[Body has been received]] 1413 | ... | 1415 Figure 11: Example of NON Notifications with Q-Block2 Option (Blocks 1416 Recovery with M bit Set) 1418 10.3. Q-Block1 and Q-Block2 Options 1420 10.3.1. A Simple Example 1422 Figure 12 illustrates the example of a FETCH using both Q-Block1 and 1423 Q-Block2 Options along with an Observe Option. No loss is 1424 experienced. 1426 CoAP CoAP 1427 Client Server 1428 | | 1429 +--------->| NON FETCH /path M:0x10 T:0x90 O:0 RT=30 QB1:0/1/1024 1430 +--------->| NON FETCH /path M:0x11 T:0x91 O:0 RT=30 QB1:1/1/1024 1431 +--------->| NON FETCH /path M:0x12 T:0x93 O:0 RT=30 QB1:2/0/1024 1432 |<---------+ NON 2.05 M:0x60 T:0x93 O:1320 ET=90 QB2:0/1/1024 1433 |<---------+ NON 2.05 M:0x61 T:0x93 O:1320 ET=90 QB2:1/1/1024 1434 |<---------+ NON 2.05 M:0x62 T:0x93 O:1320 ET=90 QB2:2/1/1024 1435 |<---------+ NON 2.05 M:0x63 T:0x93 O:1320 ET=90 QB2:3/0/1024 1436 | ... | 1437 | [[Observe triggered]] 1438 |<---------+ NON 2.05 M:0x64 T:0x93 O:1321 ET=91 QB2:0/1/1024 1439 |<---------+ NON 2.05 M:0x65 T:0x93 O:1321 ET=91 QB2:1/1/1024 1440 |<---------+ NON 2.05 M:0x66 T:0x93 O:1321 ET=91 QB2:2/1/1024 1441 |<---------+ NON 2.05 M:0x67 T:0x93 O:1321 ET=91 QB2:3/0/1024 1442 | ... | 1444 Figure 12: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1445 (Without Loss) 1447 10.3.2. Handling MAX_PAYLOADS Limits 1449 Figure 13 illustrates the same as Figure 12 but this time has eleven 1450 (11) payloads in both directions which exceeds MAX_PAYLOADS. There 1451 is no loss experienced. 1453 CoAP CoAP 1454 Client Server 1455 | | 1456 +--------->| NON FETCH /path M:0x30 T:0xa0 O:0 RT=10 QB1:0/1/1024 1457 +--------->| NON FETCH /path M:0x31 T:0xa1 O:0 RT=10 QB1:1/1/1024 1458 +--------->| [[Payloads 3 - 9 not detailed]] 1459 +--------->| NON FETCH /path M:0x39 T:0xa9 O:0 RT=10 QB1:9/1/1024 1460 [[MAX_PAYLOADS has been reached]] 1461 | [[MAX_PAYLOADS blocks receipt acknowledged by server]] 1462 |<---------+ NON 2.31 M:0x80 T:0xa9 1463 +--------->| NON FETCH /path M:0x3a T:0xaa O:0 RT=10 QB1:10/0/1024 1464 |<---------+ NON 2.05 M:0x81 T:0xaa O:1334 ET=21 QB2:0/1/1024 1465 |<---------+ NON 2.05 M:0x82 T:0xaa O:1334 ET=21 QB2:1/1/1024 1466 |<---------+ [[Payloads 3 - 9 not detailed]] 1467 |<---------+ NON 2.05 M:0x8a T:0xaa O:1334 ET=21 QB2:9/1/1024 1468 [[MAX_PAYLOADS has been reached]] 1469 | [[MAX_PAYLOADS blocks acknowledged by client using 1470 | 'Continue' Q-Block2]] 1471 +--------->| NON FETCH /path M:0x3b T:0xab QB2:10/1/1024 1472 |<---------+ NON 2.05 M:0x8b T:0xaa O:1334 ET=21 QB2:10/0/1024 1473 | ... | 1474 | [[Observe triggered]] 1475 |<---------+ NON 2.05 M:0x8c T:0xaa O:1335 ET=22 QB2:0/1/1024 1476 |<---------+ NON 2.05 M:0x8d T:0xaa O:1335 ET=22 QB2:1/1/1024 1477 |<---------+ [[Payloads 3 - 9 not detailed]] 1478 |<---------+ NON 2.05 M:0x95 T:0xaa O:1335 ET=22 QB2:9/1/1024 1479 [[MAX_PAYLOADS has been reached]] 1480 | [[MAX_PAYLOADS blocks acknowledged by client using 1481 | 'Continue' Q-Block2]] 1482 +--------->| NON FETCH /path M:0x3c T:0xac QB2:10/1/1024 1483 |<---------+ NON 2.05 M:0x96 T:0xaa O:1335 ET=22 QB2:10/0/1024 1484 [[Body has been received]] 1485 | ... | 1487 Figure 13: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1488 (Without Loss) 1490 10.3.3. Handling Recovery 1492 Consider now a scenario where some blocks are lost in transmission as 1493 illustrated in Figure 14. 1495 CoAP CoAP 1496 Client Server 1497 | | 1498 +--------->| NON FETCH /path M:0x50 T:0xc0 O:0 RT=31 QB1:0/1/1024 1499 +--->X | NON FETCH /path M:0x51 T:0xc1 O:0 RT=31 QB1:1/1/1024 1500 +--->X | NON FETCH /path M:0x52 T:0xc2 O:0 RT=31 QB1:2/1/1024 1501 +--------->| NON FETCH /path M:0x53 T:0xc3 O:0 RT=31 QB1:3/0/1024 1502 | ... | 1503 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1505 Figure 14: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1506 (With Loss) 1508 The server realizes that some blocks are missing and asks for the 1509 missing blocks in one go (Figure 15). It does so by indicating which 1510 blocks have not been received in the data portion of the response. 1511 The token used in the response is the token that was used in the last 1512 received payload. The client can then derive the Request-Tag by 1513 matching the token with the sent request. 1515 CoAP CoAP 1516 Client Server 1517 | | 1518 |<---------+ NON 4.08 M:0xa0 T:0xc3 [Missing 1,2] 1519 | [[Client responds with missing payloads]] 1520 +--------->| NON FETCH /path M:0x54 T:0xc4 O:0 RT=31 QB1:1/1/1024 1521 +--------->| NON FETCH /path M:0x55 T:0xc5 O:0 RT=31 QB1:2/1/1024 1522 | [[Server received FETCH body, 1523 | starts transmitting response body]] 1524 |<---------+ NON 2.05 M:0xa1 T:0xc3 O:1236 ET=23 QB2:0/1/1024 1525 | X<---+ NON 2.05 M:0xa2 T:0xc3 O:1236 ET=23 QB2:1/1/1024 1526 |<---------+ NON 2.05 M:0xa3 T:0xc3 O:1236 ET=23 QB2:2/1/1024 1527 | X<---+ NON 2.05 M:0xa4 T:0xc3 O:1236 ET=23 QB2:3/0/1024 1528 | ... | 1529 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1530 | | 1532 Figure 15: Example of NON Request with Q-Block1 Option (Server 1533 Recovery) 1535 The client realizes that not all the payloads of the response have 1536 been returned. The client then asks for the missing blocks in one go 1537 (Figure 16). Note that, following Section 2.7 of [RFC7959], the 1538 FETCH request does not include the Q-Block1 or any payload. 1540 CoAP CoAP 1541 Client Server 1542 | | 1543 +--------->| NON FETCH /path M:0x56 T:0xc6 RT=31 QB2:1/0/1024\ 1544 | | QB2:3/0/1024 1545 | [[Server receives FETCH request for missing payloads, 1546 | starts transmitting missing blocks]] 1547 | X<---+ NON 2.05 M:0xa5 T:0xc6 ET=23 QB2:1/1/1024 1548 |<---------+ NON 2.05 M:0xa6 T:0xc6 ET=23 QB2:3/0/1024 1549 | ... | 1550 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1551 | [[Client realizes block is still missing and asks for 1552 | missing block]] 1553 +--------->| NON FETCH /path M:0x57 T:0xc7 RT=31 QB2:1/0/1024 1554 | [[Server receives FETCH request for missing payload, 1555 | starts transmitting missing block]] 1556 |<---------+ NON 2.05 M:0xa7 T:0xc7 ET=23 QB2:1/1/1024 1557 [[Body has been received]] 1558 | ... | 1559 | [[Observe triggered]] 1560 |<---------+ NON 2.05 M:0xa8 T:0xc3 O:1337 ET=24 QB2:0/1/1024 1561 | X<---+ NON 2.05 M:0xa9 T:0xc3 O:1337 ET=24 QB2:1/1/1024 1562 |<---------+ NON 2.05 M:0xaa T:0xc3 O:1337 ET=24 QB2:2/0/1024 1563 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1564 | [[Client realizes block is still missing and asks for 1565 | missing block]] 1566 +--------->| NON FETCH /path M:0x58 T:0xc8 RT=31 QB2:1/0/1024 1567 | [[Server receives FETCH request for missing payload, 1568 | starts transmitting missing block]] 1569 |<---------+ NON 2.05 M:0xa7 T:0xc8 ET=24 QB2:1/1/1024 1570 [[Body has been received]] 1571 | ... | 1573 Figure 16: Example of NON Request with Q-Block1 Option (Client 1574 Recovery) 1576 11. Security Considerations 1578 Security considerations discussed in Section 7 of [RFC7959] should be 1579 taken into account. 1581 Security considerations discussed in Sections 11.3 and 11.4 of 1582 [RFC7252] should be taken into account. 1584 OSCORE provides end-to-end protection of all information that is not 1585 required for proxy operations and requires that a security context is 1586 set up (Section 3.1 of [RFC8613]). It can be trusted that the source 1587 endpoint is legitimate even if NoSec security mode is used. However, 1588 an intermediary node can modify the unprotected outer Q-Block1 and/or 1589 Q-Block2 Options to cause a Q-Block transfer to fail or keep 1590 requesting all the blocks by setting the M bit and, thus, causing 1591 attack amplification. As discussed in Section 12.1 of [RFC8613], 1592 applications need to consider that certain message fields and 1593 messages types are not protected end-to-end and may be spoofed or 1594 manipulated. It is NOT RECOMMENDED that the NoSec security mode is 1595 used if the Q-Block1 and Q-Block2 Options are to be used. 1597 Security considerations related to the use of Request-Tag are 1598 discussed in Section 5 of [I-D.ietf-core-echo-request-tag]. 1600 12. IANA Considerations 1602 RFC Editor Note: Please replace [RFCXXXX] with the RFC number to be 1603 assigned to this document. 1605 12.1. CoAP Option Numbers Registry 1607 IANA is requested to add the following entries to the "CoAP Option 1608 Numbers" sub-registry [Options] defined in [RFC7252] within the 1609 "Constrained RESTful Environments (CoRE) Parameters" registry: 1611 +--------+------------------+-----------+ 1612 | Number | Name | Reference | 1613 +========+==================+===========+ 1614 | TBA1 | Q-Block1 | [RFCXXXX] | 1615 | TBA2 | Q-Block2 | [RFCXXXX] | 1616 +--------+------------------+-----------+ 1618 Table 4: CoAP Q-Block1 and Q-Block2 Option Numbers 1620 This document suggests 19 (TBA1) and 31 (TBA2) as values to be 1621 assigned for the new option numbers. 1623 12.2. Media Type Registration 1625 This document requests IANA to register the "application/missing- 1626 blocks+cbor-seq" media type in the "Media Types" registry 1627 [IANA-MediaTypes]. This registration follows the procedures 1628 specified in [RFC6838]: 1630 Type name: application 1632 Subtype name: missing-blocks+cbor-seq 1634 Required parameters: N/A 1636 Optional parameters: N/A 1638 Encoding considerations: Must be encoded as a CBOR 1639 sequence [RFC8742], as defined in Section 4 of [RFCXXXX]. 1641 Security considerations: See Section 10 of [RFCXXXX]. 1643 Interoperability considerations: N/A 1645 Published specification: [RFCXXXX] 1647 Applications that use this media type: Data serialization and 1648 deserialization. In particular, the type is used by applications 1649 relying upon block-wise transfers, allowing a server to specify 1650 non-received blocks and request for their retransmission, as 1651 defined in Section 4 of [RFCXXXX]. 1653 Fragment identifier considerations: N/A 1655 Additional information: N/A 1657 Person & email address to contact for further information: IETF, 1658 iesg@ietf.org 1660 Intended usage: COMMON 1662 Restrictions on usage: none 1664 Author: See Authors' Addresses section. 1666 Change controller: IESG 1668 Provisional registration? No 1670 12.3. CoAP Content-Formats Registry 1672 This document requests IANA to register the following CoAP Content- 1673 Format for the "application/missing-blocks+cbor-seq" media type in 1674 the "CoAP Content-Formats" registry [Format], defined in [RFC7252], 1675 within the "Constrained RESTful Environments (CoRE) Parameters" 1676 registry: 1678 o Media Type: application/missing-blocks+cbor-seq 1679 o Encoding: - 1680 o Id: TBA3 1681 o Reference: [RFCXXXX] 1683 This document suggests 272 (TBA3) as a value to be assigned for the 1684 new content format number. 1686 13. References 1688 13.1. Normative References 1690 [I-D.ietf-core-echo-request-tag] 1691 Amsuess, C., Mattsson, J., and G. Selander, "CoAP: Echo, 1692 Request-Tag, and Token Processing", draft-ietf-core-echo- 1693 request-tag-11 (work in progress), November 2020. 1695 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1696 Requirement Levels", BCP 14, RFC 2119, 1697 DOI 10.17487/RFC2119, March 1997, 1698 . 1700 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1701 Specifications and Registration Procedures", BCP 13, 1702 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1703 . 1705 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1706 Application Protocol (CoAP)", RFC 7252, 1707 DOI 10.17487/RFC7252, June 2014, 1708 . 1710 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1711 Application Protocol (CoAP)", RFC 7641, 1712 DOI 10.17487/RFC7641, September 2015, 1713 . 1715 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1716 the Constrained Application Protocol (CoAP)", RFC 7959, 1717 DOI 10.17487/RFC7959, August 2016, 1718 . 1720 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1721 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1722 the Constrained Application Protocol (CoAP)", RFC 8075, 1723 DOI 10.17487/RFC8075, February 2017, 1724 . 1726 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1727 FETCH Methods for the Constrained Application Protocol 1728 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1729 . 1731 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1732 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1733 May 2017, . 1735 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1736 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1737 Application Protocol) over TCP, TLS, and WebSockets", 1738 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1739 . 1741 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1742 "Object Security for Constrained RESTful Environments 1743 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1744 . 1746 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 1747 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 1748 . 1750 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1751 Representation (CBOR)", STD 94, RFC 8949, 1752 DOI 10.17487/RFC8949, December 2020, 1753 . 1755 13.2. Informative References 1757 [Format] "CoAP Content-Formats", . 1760 [I-D.bosh-dots-quick-blocks] 1761 Boucadair, M. and J. Shallow, "Distributed Denial-of- 1762 Service Open Threat Signaling (DOTS) Signal Channel 1763 Configuration Attributes for Faster Block Transmission", 1764 draft-bosh-dots-quick-blocks-01 (work in progress), 1765 January 2021. 1767 [I-D.ietf-dots-telemetry] 1768 Boucadair, M., Reddy.K, T., Doron, E., chenmeiling, c., 1769 and J. Shallow, "Distributed Denial-of-Service Open Threat 1770 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-15 1771 (work in progress), December 2020. 1773 [IANA-MediaTypes] 1774 IANA, "Media Types", 1775 . 1777 [Options] "CoAP Option Numbers", . 1780 [RFC6928] Chu, J., Dukkipati, N., Cheng, Y., and M. Mathis, 1781 "Increasing TCP's Initial Window", RFC 6928, 1782 DOI 10.17487/RFC6928, April 2013, 1783 . 1785 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 1786 Bose, "Constrained Application Protocol (CoAP) Option for 1787 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 1788 August 2016, . 1790 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1791 Definition Language (CDDL): A Notational Convention to 1792 Express Concise Binary Object Representation (CBOR) and 1793 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1794 June 2019, . 1796 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 1797 Mortensen, A., and N. Teague, "Distributed Denial-of- 1798 Service Open Threat Signaling (DOTS) Signal Channel 1799 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 1800 . 1802 [RFC8974] Hartke, K. and M. Richardson, "Extended Tokens and 1803 Stateless Clients in the Constrained Application Protocol 1804 (CoAP)", RFC 8974, DOI 10.17487/RFC8974, January 2021, 1805 . 1807 Appendix A. Examples with Confirmable Messages 1809 The following examples assume NSTART has been increased to 3. 1811 The notations provided in Figure 2 are used in the following 1812 subsections. 1814 A.1. Q-Block1 Option 1816 Let's now consider the use of Q-Block1 Option with a CON request as 1817 shown in Figure 17. All the blocks are acknowledged (ACK). 1819 CoAP CoAP 1820 Client Server 1821 | | 1822 +--------->| CON PUT /path M:0x01 T:0xf0 RT=10 QB1:0/1/1024 1823 +--------->| CON PUT /path M:0x02 T:0xf1 RT=10 QB1:1/1/1024 1824 +--------->| CON PUT /path M:0x03 T:0xf2 RT=10 QB1:2/1/1024 1825 [[NSTART(3) limit reached]] 1826 |<---------+ ACK 0.00 M:0x01 1827 +--------->| CON PUT /path M:0x04 T:0xf3 RT=10 QB1:3/0/1024 1828 |<---------+ ACK 0.00 M:0x02 1829 |<---------+ ACK 0.00 M:0x03 1830 |<---------+ ACK 2.04 M:0x04 1831 | | 1833 Figure 17: Example of CON Request with Q-Block1 Option (Without Loss) 1835 Now, suppose that a new body of data is to be sent but with some 1836 blocks dropped in transmission as illustrated in Figure 18. The 1837 client will retry sending blocks for which no ACK was received. 1839 CoAP CoAP 1840 Client Server 1841 | | 1842 +--------->| CON PUT /path M:0x05 T:0xf4 RT=11 QB1:0/1/1024 1843 +--->X | CON PUT /path M:0x06 T:0xf5 RT=11 QB1:1/1/1024 1844 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1845 [[NSTART(3) limit reached]] 1846 |<---------+ ACK 0.00 M:0x05 1847 +--------->| CON PUT /path M:0x08 T:0xf7 RT=11 QB1:3/1/1024 1848 |<---------+ ACK 0.00 M:0x08 1849 | ... | 1850 [[ACK_TIMEOUT (client) for M:0x06 delay expires]] 1851 | [[Client retransmits packet]] 1852 +--------->| CON PUT /path M:0x06 T:0xf5 RT=11 QB1:1/1/1024 1853 [[ACK_TIMEOUT (client) for M:0x07 delay expires]] 1854 | [[Client retransmits packet]] 1855 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1856 |<---------+ ACK 0.00 M:0x06 1857 | ... | 1858 [[ACK_TIMEOUT exponential backoff (client) delay expires]] 1859 | [[Client retransmits packet]] 1860 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1861 | ... | 1862 [[Either body transmission failure (acknowledge retry timeout) 1863 or successfully transmitted.]] 1865 Figure 18: Example of CON Request with Q-Block1 Option (Blocks 1866 Recovery) 1868 It is up to the implementation as to whether the application process 1869 stops trying to send this particular body of data on reaching 1870 MAX_RETRANSMIT for any payload, or separately tries to initiate the 1871 new transmission of the payloads that have not been acknowledged 1872 under these adverse traffic conditions. 1874 If there is likely to be the possibility of network transient losses, 1875 then the use of NON should be considered. 1877 A.2. Q-Block2 Option 1879 An example of the use of Q-Block2 Option with Confirmable messages is 1880 shown in Figure 19. 1882 Client Server 1883 | | 1884 +--------->| CON GET /path M:0x01 T:0xf0 O:0 QB2:0/1/1024 1885 |<---------+ ACK 2.05 M:0x01 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1886 |<---------+ CON 2.05 M:0xe1 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1887 |<---------+ CON 2.05 M:0xe2 T:0xf0 O:1234 ET=21 QB2:2/1/1024 1888 |<---------+ CON 2.05 M:0xe3 T:0xf0 O:1234 ET=21 QB2:3/0/1024 1889 |--------->+ ACK 0.00 M:0xe1 1890 |--------->+ ACK 0.00 M:0xe2 1891 |--------->+ ACK 0.00 M:0xe3 1892 | ... | 1893 | [[Observe triggered]] 1894 |<---------+ CON 2.05 M:0xe4 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1895 |<---------+ CON 2.05 M:0xe5 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1896 |<---------+ CON 2.05 M:0xe6 T:0xf0 O:1235 ET=22 QB2:2/1/1024 1897 [[NSTART(3) limit reached]] 1898 |--------->+ ACK 0.00 M:0xe4 1899 |<---------+ CON 2.05 M:0xe7 T:0xf0 O:1235 ET=22 QB2:3/0/1024 1900 |--------->+ ACK 0.00 M:0xe5 1901 |--------->+ ACK 0.00 M:0xe6 1902 |--------->+ ACK 0.00 M:0xe7 1903 | ... | 1904 | [[Observe triggered]] 1905 |<---------+ CON 2.05 M:0xe8 T:0xf0 O:1236 ET=23 QB2:0/1/1024 1906 | X<---+ CON 2.05 M:0xe9 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1907 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1908 [[NSTART(3) limit reached]] 1909 |--------->+ ACK 0.00 M:0xe8 1910 |<---------+ CON 2.05 M:0xeb T:0xf0 O:1236 ET=23 QB2:3/0/1024 1911 |--------->+ ACK 0.00 M:0xeb 1912 | ... | 1913 [[ACK_TIMEOUT (server) for M:0xe9 delay expires]] 1914 | [[Server retransmits packet]] 1915 |<---------+ CON 2.05 M:0xe9 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1916 [[ACK_TIMEOUT (server) for M:0xea delay expires]] 1917 | [[Server retransmits packet]] 1918 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1919 |--------->+ ACK 0.00 M:0xe9 1920 | ... | 1921 [[ACK_TIMEOUT exponential backoff (server) delay expires]] 1922 | [[Server retransmits packet]] 1923 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1924 | ... | 1925 [[Either body transmission failure (acknowledge retry timeout) 1926 or successfully transmitted.]] 1928 Figure 19: Example of CON Notifications with Q-Block2 Option 1930 It is up to the implementation as to whether the application process 1931 stops trying to send this particular body of data on reaching 1932 MAX_RETRANSMIT for any payload, or separately tries to initiate the 1933 new transmission of the payloads that have not been acknowledged 1934 under these adverse traffic conditions. 1936 If there is likely to be the possibility of network transient losses, 1937 then the use of NON should be considered. 1939 Appendix B. Examples with Reliable Transports 1941 The notations provided in Figure 2 are used in the following 1942 subsections. 1944 B.1. Q-Block1 Option 1946 Let's now consider the use of Q-Block1 Option with a reliable 1947 transport as shown in Figure 20. There is no acknowledgment of 1948 packets at the CoAP layer, just the final result. 1950 CoAP CoAP 1951 Client Server 1952 | | 1953 +--------->| PUT /path T:0xf0 RT=10 QB1:0/1/1024 1954 +--------->| PUT /path T:0xf1 RT=10 QB1:1/1/1024 1955 +--------->| PUT /path T:0xf2 RT=10 QB1:2/1/1024 1956 +--------->| PUT /path T:0xf3 RT=10 QB1:3/0/1024 1957 |<---------+ 2.04 1958 | | 1960 Figure 20: Example of Reliable Request with Q-Block1 Option 1962 If there is likely to be the possibility of network transient losses, 1963 then the use of unreliable transport with NON should be considered. 1965 B.2. Q-Block2 Option 1967 An example of the use of Q-Block2 Option with a reliable transport is 1968 shown in Figure 21. 1970 Client Server 1971 | | 1972 +--------->| GET /path T:0xf0 O:0 QB2:0/1/1024 1973 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1974 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1975 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:2/1/1024 1976 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:3/0/1024 1977 | ... | 1978 | [[Observe triggered]] 1979 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1980 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1981 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:2/1/1024 1982 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:3/0/1024 1983 | ... | 1985 Figure 21: Example of Notifications with Q-Block2 Option 1987 If there is likely to be the possibility of network transient losses, 1988 then the use of unreliable transport with NON should be considered. 1990 Acknowledgements 1992 Thanks to Achim Kraus, Jim Schaad, and Michael Richardson for their 1993 comments. 1995 Special thanks to Christian Amsuess, Carsten Bormann, and Marco 1996 Tiloca for their suggestions and several reviews, which improved this 1997 specification significantly. Thanks to Francesca Palombini for the 1998 AD review. 2000 Thanks to Pete Resnick for the Gen-ART review. 2002 Some text from [RFC7959] is reused for readers convenience. 2004 Authors' Addresses 2006 Mohamed Boucadair 2007 Orange 2008 Rennes 35000 2009 France 2011 Email: mohamed.boucadair@orange.com 2013 Jon Shallow 2014 United Kingdom 2016 Email: supjps-ietf@jpshallow.com