idnits 2.17.1 draft-ietf-core-new-block-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2021) is 1114 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 1467, but not defined -- Looks like a reference, but probably isn't: '9' on line 1156 == Missing Reference: 'Missing 10' is mentioned on line 1166, but not defined -- Looks like a reference, but probably isn't: '2' on line 1467 == Missing Reference: 'RFCXXXX' is mentioned on line 1601, 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 M. Boucadair 3 Internet-Draft Orange 4 Intended status: Standards Track J. Shallow 5 Expires: September 12, 2021 March 11, 2021 7 Constrained Application Protocol (CoAP) Block-Wise Transfer Options for 8 Faster Transmission 9 draft-ietf-core-new-block-08 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, not 17 a replacement for them, but do enable faster transmission rates for 18 large amounts of data with less packet interchanges as well as 19 supporting faster recovery should any of the blocks get lost in 20 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 September 12, 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 1.1. Alternative CoAP Block-Wise Transfer Options . . . . . . 3 58 1.2. CoAP Response Code (4.08) Usage . . . . . . . . . . . . . 5 59 1.3. Applicability Scope . . . . . . . . . . . . . . . . . . . 5 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 3. The Q-Block1 and Q-Block2 Options . . . . . . . . . . . . . . 7 62 3.1. Properties of Q-Block1 and Q-Block2 Options . . . . . . . 7 63 3.2. Structure of Q-Block1 and Q-Block2 Options . . . . . . . 9 64 3.3. Using the Q-Block1 Option . . . . . . . . . . . . . . . . 9 65 3.4. Using the Q-Block2 Option . . . . . . . . . . . . . . . . 12 66 3.5. Using Observe Option . . . . . . . . . . . . . . . . . . 15 67 3.6. Using Size1 and Size2 Options . . . . . . . . . . . . . . 15 68 3.7. Using Q-Block1 and Q-Block2 Options Together . . . . . . 15 69 3.8. Using Q-Block2 Option With Multicast . . . . . . . . . . 15 70 4. The Use of 4.08 (Request Entity Incomplete) Response Code . . 16 71 5. The Use of Tokens . . . . . . . . . . . . . . . . . . . . . . 17 72 6. Congestion Control for Unreliable Transports . . . . . . . . 17 73 6.1. Confirmable (CON) . . . . . . . . . . . . . . . . . . . . 17 74 6.2. Non-confirmable (NON) . . . . . . . . . . . . . . . . . . 18 75 7. Caching Considerations . . . . . . . . . . . . . . . . . . . 21 76 8. HTTP-Mapping Considerations . . . . . . . . . . . . . . . . . 23 77 9. Examples with Non-confirmable Messages . . . . . . . . . . . 23 78 9.1. Q-Block1 Option . . . . . . . . . . . . . . . . . . . . . 23 79 9.1.1. A Simple Example . . . . . . . . . . . . . . . . . . 23 80 9.1.2. Handling MAX_PAYLOADS Limits . . . . . . . . . . . . 24 81 9.1.3. Handling MAX_PAYLOADS with Recovery . . . . . . . . . 24 82 9.1.4. Handling Recovery with Failure . . . . . . . . . . . 26 83 9.2. Q-Block2 Option . . . . . . . . . . . . . . . . . . . . . 26 84 9.2.1. A Simple Example . . . . . . . . . . . . . . . . . . 27 85 9.2.2. Handling MAX_PAYLOADS Limits . . . . . . . . . . . . 27 86 9.2.3. Handling MAX_PAYLOADS with Recovery . . . . . . . . . 28 87 9.2.4. Handling Recovery using M-bit Set . . . . . . . . . . 29 88 9.3. Q-Block1 and Q-Block2 Options . . . . . . . . . . . . . . 30 89 9.3.1. A Simple Example . . . . . . . . . . . . . . . . . . 30 90 9.3.2. Handling MAX_PAYLOADS Limits . . . . . . . . . . . . 31 91 9.3.3. Handling Recovery . . . . . . . . . . . . . . . . . . 32 92 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 93 10.1. New CoAP Options . . . . . . . . . . . . . . . . . . . . 34 94 10.2. New Media Type . . . . . . . . . . . . . . . . . . . . . 35 95 10.3. New Content Format . . . . . . . . . . . . . . . . . . . 36 96 11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 97 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 98 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 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 . . . . . . . . . . . . . . . . . . . . . 41 104 Appendix B. Examples with Reliable Transports . . . . . . . . . 43 105 B.1. Q-Block1 Option . . . . . . . . . . . . . . . . . . . . . 43 106 B.2. Q-Block2 Option . . . . . . . . . . . . . . . . . . . . . 43 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 109 1. Introduction 111 The Constrained Application Protocol (CoAP) [RFC7252], although 112 inspired by HTTP, was designed to use UDP instead of TCP. The 113 message layer of CoAP over UDP includes support for reliable 114 delivery, simple congestion control, and flow control. [RFC7959] 115 introduced the CoAP Block1 and Block2 Options to handle data records 116 that cannot fit in a single IP packet, so not having to rely on IP 117 fragmentation and was further updated by [RFC8323] for use over TCP, 118 TLS, and WebSockets. 120 The CoAP Block1 and Block2 Options work well in environments where 121 there are no or minimal packet losses. These options operate 122 synchronously where each individual block has to be requested and can 123 only ask for (or send) the next block when the request for the 124 previous block has completed. Packet, and hence block transmission 125 rate, is controlled by Round Trip Times (RTTs). 127 There is a requirement for these blocks of data to be transmitted at 128 higher rates under network conditions where there may be asymmetrical 129 transient packet loss (i.e., responses may get dropped). An example 130 is when a network is subject to a Distributed Denial of Service 131 (DDoS) attack and there is a need for DDoS mitigation agents relying 132 upon CoAP to communicate with each other (e.g., 133 [I-D.ietf-dots-telemetry]). As a reminder, [RFC7959] recommends the 134 use of Confirmable (CON) responses to handle potential packet loss. 135 However, such a recommendation does not work with a flooded pipe DDoS 136 situation. 138 1.1. Alternative CoAP Block-Wise Transfer Options 140 This document introduces the CoAP Q-Block1 and Q-Block2 Options. 141 These options are similar in operation to the CoAP Block1 and Block2 142 Options, respectively. They are not a replacement for them, but have 143 the following benefits: 145 o They can operate in environments where packet loss is highly 146 asymmetrical. 148 o They enable faster transmissions of sets of blocks of data with 149 less packet interchanges. 151 o They support faster recovery should any of the blocks get lost in 152 transmission. 154 o They support sending an entire body using Non-confirmable (NON) 155 without requiring a response from the peer. 157 There are the following disadvantages over using CoAP Block1 and 158 Block2 Options: 160 o Loss of lock-stepping so payloads are not always received in the 161 correct (block ascending) order. 163 o Additional congestion control measures need to be put in place for 164 NON (Section 6.2). 166 o To reduce the transmission times for CON transmission of large 167 bodies, NSTART needs to be increased from 1, but this affects 168 congestion control where other parameters need to be tuned 169 (Section 4.7 of [RFC7252]). Such tuning is out of scope of this 170 document. 172 o Mixing of NON and CON during requests/responses using Q-Block is 173 not supported. 175 o The Q-Block Options do not support stateless operation/random 176 access. 178 o Proxying of Q-Block is limited to caching full representations. 180 o There is no multicast support. 182 Using NON messages, the faster transmissions occur as all the blocks 183 can be transmitted serially (as are IP fragmented packets) without 184 having to wait for a response or next request from the remote CoAP 185 peer. Recovery of missing blocks is faster in that multiple missing 186 blocks can be requested in a single CoAP packet. Even if there is 187 asymmetrical packet loss, a body can still be sent and received by 188 the peer whether the body comprises of a single or multiple payloads 189 assuming no recovery is required. 191 A CoAP endpoint can acknowledge all or a subset of the blocks. 192 Concretely, the receiving CoAP endpoint informs the CoAP sender 193 endpoint either successful receipt or reports on all blocks in the 194 body that have not yet been received. The CoAP sender endpoint will 195 then retransmit only the blocks that have been lost in transmission. 197 Note that similar performance benefits can be applied to Confirmable 198 messages if the value of NSTART is increased from 1 (Section 4.7 of 199 [RFC7252]). However, the use of Confirmable messages will not work 200 if there is asymmetrical packet loss. Some examples with Confirmable 201 messages are provided in Appendix A. 203 There is little, if any, benefit of using these options with CoAP 204 running over a reliable connection [RFC8323]. In this case, there is 205 no differentiation between Confirmable and NON as they are not used. 206 Some examples using a reliable transport are provided in Appendix B. 208 Q-Block1 and Q-Block2 Options can be used instead of Block1 and 209 Block2 Options when the different transmission properties are 210 required. If the new option is not supported by a peer, then 211 transmissions can fall back to using Block1 and Block2 Options. 213 The deviations from Block1 and Block2 Options are specified in 214 Section 3. Pointers to appropriate [RFC7959] sections are provided. 216 The specification refers to the base CoAP methods defined in 217 Section 5.8 of [RFC7252] and the new CoAP methods, FETCH, PATCH, and 218 iPATCH introduced in [RFC8132]. 220 Q-Block1 and Q-Block2 Options are designed to work in particular with 221 Non-confirmable requests and responses. 223 The No-Response Option was considered but was abandoned as it does 224 not apply to Q-Block2 responses. A unified solution is defined in 225 the document. 227 1.2. CoAP Response Code (4.08) Usage 229 This document adds a media type for the 4.08 (Request Entity 230 Incomplete) response defining an additional message format for 231 reporting on payloads using the Q-Block1 Option that are not received 232 by the server. 234 See Section 4 for more details. 236 1.3. Applicability Scope 238 The block-wise transfer specified in [RFC7959] covers the general 239 case, but falls short in situations where packet loss is highly 240 asymmetrical. The mechanism specified in this document provides 241 roughly similar features to the Block1/Block2 Options. It provides 242 additional properties that are tailored towards the intended use case 243 of Non-Confirmable transmission. Concretely, this mechanism 244 primarily targets applications such as DDoS Open Threat Signaling 245 (DOTS) that can't use Confirmable (CON) responses to handle potential 246 packet loss and that support application-specific mechanisms to 247 assess whether the remote peer is able to handle the messages sent by 248 a CoAP endpoint (e.g., DOTS heartbeats in Section 4.7 of [RFC8782]). 250 The mechanism includes guards to prevent a CoAP agent from 251 overloading the network by adopting an aggressive sending rate. 252 These guards MUST be followed in addition to the existing CoAP 253 congestion control as specified in Section 4.7 of [RFC7252]. See 254 Section 6 for more details. 256 This mechanism is not intended for general CoAP usage, and any use 257 outside the intended use case should be carefully weighed against the 258 loss of interoperability with generic CoAP applications. It is hoped 259 that the experience gained with this mechanism can feed future 260 extensions of the block-wise mechanism that will both be generally 261 applicable and serve this particular use case. 263 It is not recommended that these options are used in a NoSec security 264 mode (Section 9 of [RFC7252]) as the source endpoint needs to be 265 trusted. Using OSCORE [RFC8613] does provide a security context and, 266 hence, a trust of the source endpoint. However, using a NoSec 267 security mode may still be inadequate for reasons discussed in 268 Section 11. 270 2. Terminology 272 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 273 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 274 "OPTIONAL" in this document are to be interpreted as described in BCP 275 14 [RFC2119][RFC8174] when, and only when, they appear in all 276 capitals, as shown here. 278 Readers should be familiar with the terms and concepts defined in 279 [RFC7252]. 281 The terms "payload" and "body" are defined in [RFC7959]. The term 282 "payload" is thus used for the content of a single CoAP message 283 (i.e., a single block being transferred), while the term "body" is 284 used for the entire resource representation that is being transferred 285 in a block-wise fashion. 287 3. The Q-Block1 and Q-Block2 Options 289 3.1. Properties of Q-Block1 and Q-Block2 Options 291 The properties of Q-Block1 and Q-Block2 Options are shown in Table 1. 292 The formatting of this table follows the one used in Table 4 of 293 [RFC7252] (Section 5.10). The C, U, N, and R columns indicate the 294 properties Critical, UnSafe, NoCacheKey, and Repeatable defined in 295 Section 5.4 of [RFC7252]. Only Critical and UnSafe columns are 296 marked for the Q-Block1 Option. Critical, UnSafe, and Repeatable 297 columns are marked for the Q-Block2 Option. As these options are 298 UnSafe, NoCacheKey has no meaning and so is marked with a dash. 300 +--------+---+---+---+---+--------------+--------+--------+---------+ 301 | Number | C | U | N | R | Name | Format | Length | Default | 302 +========+===+===+===+===+==============+========+========+=========+ 303 | TBA1 | x | x | - | | Q-Block1 | uint | 0-3 | (none) | 304 | TBA2 | x | x | - | x | Q-Block2 | uint | 0-3 | (none) | 305 +--------+---+---+---+---+--------------+--------+--------+---------+ 307 Table 1: CoAP Q-Block1 and Q-Block2 Option Properties 309 The Q-Block1 and Q-Block2 Options can be present in both the request 310 and response messages. The Q-Block1 Option pertains to the request 311 payload and the Q-Block2 Option pertains to the response payload. 312 The Content-Format Option applies to the body, not to the payload 313 (i.e., it must be the same for all payloads of the same body). 315 Q-Block1 Option is useful with the payload-bearing POST, PUT, FETCH, 316 PATCH, and iPATCH requests and their responses. 318 Q-Block2 Option is useful with GET, POST, PUT, FETCH, PATCH, and 319 iPATCH requests and their payload-bearing responses (2.01, 2.02, 320 2.03, 2.04, and 2.05) (Section 5.5 of [RFC7252]). 322 A CoAP endpoint (or proxy) MUST support either both or neither of the 323 Q-Block1 and Q-Block2 Options. 325 If Q-Block1 Option is present in a request or Q-Block2 Option in a 326 response (i.e., in that message to the payload of which it pertains), 327 it indicates a block-wise transfer and describes how this specific 328 block-wise payload forms part of the entire body being transferred. 329 If it is present in the opposite direction, it provides additional 330 control on how that payload will be formed or was processed. 332 To indicate support for Q-Block2 responses, the CoAP client MUST 333 include the Q-Block2 Option in a GET or similar request, the Q-Block2 334 Option in a PUT or similar request, or the Q-Block1 Option in a PUT 335 or similar so that the server knows that the client supports this 336 Q-Block2 functionality should it need to send back a body that spans 337 multiple payloads. Otherwise, the server would use the Block2 Option 338 (if supported) to send back a message body that is too large to fit 339 into a single IP packet [RFC7959]. 341 Implementation of the Q-Block1 and Q-Block2 Options is intended to be 342 optional. However, when it is present in a CoAP message, it MUST be 343 processed (or the message rejected). Therefore, Q-Block1 and 344 Q-Block2 Options are identified as Critical options. 346 With CoAP over UDP, the way a request message is rejected for 347 critical options depends on the message type. A Confirmable message 348 with an unrecognized critical option is rejected with a 4.02 (Bad 349 Option) response (Section 5.4.1 of [RFC7252]). A Non-confirmable 350 message with an unrecognized critical option is either rejected with 351 a Reset message or just silently ignored (Sections 5.4.1 and 4.3 of 352 [RFC7252]). To reliably get a rejection message, it is therefore 353 REQUIRED that clients use a Confirmable message for determining 354 support for Q-Block1 and Q-Block2 Options. 356 The Q-Block1 and Q-Block2 Options are unsafe to forward. That is, a 357 CoAP proxy that does not understand the Q-Block1 (or Q-Block2) Option 358 MUST reject the request or response that uses either option. 360 The Q-Block2 Option is repeatable when requesting retransmission of 361 missing blocks, but not otherwise. Except that case, any request 362 carrying multiple Q-Block1 (or Q-Block2) Options MUST be handled 363 following the procedure specified in Section 5.4.5 of [RFC7252]. 365 The Q-Block1 and Q-Block2 Options, like the Block1 and Block2 366 Options, are both a class E and a class U in terms of OSCORE 367 processing (Table 2). The Q-Block1 (or Q-Block2) Option MAY be an 368 Inner or Outer option (Section 4.1 of [RFC8613]). The Inner and 369 Outer values are therefore independent of each other. The Inner 370 option is encrypted and integrity protected between clients and 371 servers, and provides message body identification in case of end-to- 372 end fragmentation of requests. The Outer option is visible to 373 proxies and labels message bodies in case of hop-by-hop fragmentation 374 of requests. 376 +--------+-----------------+---+---+ 377 | Number | Name | E | U | 378 +========+=================+===+===+ 379 | TBA1 | Q-Block1 | x | x | 380 | TBA2 | Q-Block2 | x | x | 381 +--------+-----------------+---+---+ 382 Table 2: OSCORE Protection of Q-Block1 and Q-Block2 Options 384 Note that if Q-Block1 or Q-Block2 Options are included in a packet as 385 Inner options, Block1 or Block2 Options MUST NOT be included as Inner 386 options. Similarly there MUST NOT be a mix of Q-Block and Block for 387 the Outer options. Q-Block and Block Options can be mixed across 388 Inner and Outer options as these are handled independently of each 389 other. 391 3.2. Structure of Q-Block1 and Q-Block2 Options 393 The structure of Q-Block1 and Q-Block2 Options follows the structure 394 defined in Section 2.2 of [RFC7959]. 396 There is no default value for the Q-Block1 and Q-Block2 Options. 397 Absence of one of these options is equivalent to an option value of 0 398 with respect to the value of block number (NUM) and more bit (M) that 399 could be given in the option, i.e., it indicates that the current 400 block is the first and only block of the transfer (block number is 401 set to 0, M is unset). However, in contrast to the explicit value 0, 402 which would indicate a size of the block (SZX) of 0, and thus a size 403 value of 16 bytes, there is no specific explicit size implied by the 404 absence of the option -- the size is left unspecified. (As for any 405 uint, the explicit value 0 is efficiently indicated by a zero-length 406 option; this, therefore, is different in semantics from the absence 407 of the option). 409 3.3. Using the Q-Block1 Option 411 The Q-Block1 Option is used when the client wants to send a large 412 amount of data to the server using the POST, PUT, FETCH, PATCH, or 413 iPATCH methods where the data and headers do not fit into a single 414 packet. 416 When Q-Block1 Option is used, the client MUST include a Request-Tag 417 Option [I-D.ietf-core-echo-request-tag]. The Request-Tag value MUST 418 be the same for all of the requests for the body of data that is 419 being transferred. It is also used to identify a particular payload 420 of a body that needs to be retransmitted. The Request-Tag is opaque, 421 the server still treats it as opaque but the client SHOULD ensure 422 that it is unique for every different body of transmitted data. 424 Implementation Note: It is suggested that the client treats the 425 Request-Tag as an unsigned integer of 8 bytes in length. An 426 implementation may want to consider limiting this to 4 bytes to 427 reduce packet overhead size. The initial Request-Tag value should 428 be randomly generated and then subsequently incremented by the 429 client whenever a new body of data is being transmitted between 430 peers. 432 Section 3.6 discusses the use of Size1 Option. 434 For Confirmable transmission, the server continues to acknowledge 435 each packet, but a response is not required (whether separate or 436 piggybacked) until successful receipt of the body by the server. For 437 Non-confirmable transmission, no response is required until the 438 successful receipt of the body by the server or some of the payloads 439 have not arrived after a timeout and a retransmit missing payloads 440 response is needed. For reliable transports (e.g., [RFC8323]), a 441 response is not required until successful receipt of the body by the 442 server. 444 Each individual payload of the body is treated as a new request 445 (Section 5). 447 The client MUST send the payloads with the block numbers increasing, 448 starting from zero, until the body is complete (subject to any 449 congestion control (Section 6)). Any missing payloads requested by 450 the server must in addition be separately transmitted with increasing 451 block numbers. 453 The following Response Codes are used: 455 2.01 (Created) 457 This Response Code indicates successful receipt of the entire body 458 and the resource was created. The token used SHOULD be from the 459 last received payload. The client should then release all of the 460 tokens used for this body. 462 2.02 (Deleted) 464 This Response Code indicates successful receipt of the entire body 465 and the resource was deleted when using POST (Section 5.8.2 466 [RFC7252]). The token used SHOULD be from the last received 467 payload. The client should then release all of the tokens used 468 for this body. 470 2.04 (Changed) 472 This Response Code indicates successful receipt of the entire body 473 and the resource was updated. The token used SHOULD be from the 474 last received payload. The client should then release all of the 475 tokens used for this body. 477 2.05 (Content) 478 This Response Code indicates successful receipt of the entire 479 FETCH request body (Section 2 of [RFC8132]) and the appropriate 480 representation of the resource is being returned. The token used 481 in the response SHOULD be from the last received payload. If the 482 FETCH request includes the Observe Option, then the server MUST 483 use the same token for returning any Observe triggered responses 484 so that the client can match them up. The client should then 485 release all of the tokens used for this body unless a resource is 486 being observed. 488 2.31 (Continue) 490 This Response Code can be used to indicate that all of the blocks 491 up to and including the Q-Block1 Option block NUM (all having the 492 M bit set) in the response have been successfully received. The 493 token used SHOULD be from the last received payload. 495 A response using this Response Code SHOULD NOT be generated for 496 every received Q-Block1 Option request. It SHOULD only be 497 generated when all the payload requests are Non-confirmable and 498 MAX_PAYLOADS (Section 6.2) payloads have been received by the 499 server. 501 It SHOULD NOT be generated for CON. 503 4.00 (Bad Request) 505 This Response Code MUST be returned if the request does not 506 include both a Request-Tag Option and a Size1 Option but does 507 include a Q-Block1 option. 509 4.02 (Bad Option) 511 Either this Response Code (in case of Confirmable request) or a 512 reset message (in case of Non-confirmable request) MUST be 513 returned if the server does not support the Q-Block Options. 515 4.08 (Request Entity Incomplete) 517 This Response Code returned without Content-Type "application/ 518 missing-blocks+cbor-seq" (Section 10.3) is handled as in 519 Section 2.9.2 [RFC7959]. 521 This Response Code returned with Content-Type "application/ 522 missing-blocks+cbor-seq" indicates that some of the payloads are 523 missing and need to be resent. The client then retransmits the 524 missing payloads using the same Request-Tag, Size1 and Q-Block1 to 525 specify the block NUM, SZX, and M bit as appropriate. 527 The Request-Tag value to use is determined by taking the token in 528 the 4.08 (Request Entity Incomplete) response, locating the 529 matching client request, and then using its Request-Tag. 531 The token used in the response SHOULD be from the last received 532 payload. See Section 4 for further information. 534 4.13 (Request Entity Too Large) 536 This Response Code can be returned under similar conditions to 537 those discussed in Section 2.9.3 of [RFC7959]. 539 This Response Code can be returned if there is insufficient space 540 to create a response PDU with a block size of 16 bytes (SZX = 0) 541 to send back all the response options as appropriate. In this 542 case, the Size1 Option is not included in the response. 544 If the server has not received all the payloads of a body, but one or 545 more NON payloads have been received, it SHOULD wait for up to 546 NON_RECEIVE_TIMEOUT (Section 6.2) before sending a 4.08 (Request 547 Entity Incomplete) response. Further considerations related to the 548 transmission timings of 4.08 (Request Entity Incomplete) and 2.31 549 (Continue) Response Codes are discussed in Section 6.2. 551 If a server receives payloads with different Request-Tags for the 552 same resource, it should continue to process all the bodies as it has 553 no way of determining which is the latest version, or which body, if 554 any, the client is terminating the transmission for. 556 If the client elects to stop the transmission of a complete body, it 557 SHOULD "forget" all tracked tokens associated with the body's 558 Request-Tag so that a reset message is generated for the invalid 559 token in the 4.08 (Request Entity Incomplete) response. The server 560 on receipt of the reset message SHOULD delete the partial body. 562 If the server receives a duplicate block with the same Request-Tag, 563 it SHOULD ignore the payload of the packet, but MUST still respond as 564 if the block was received for the first time. 566 A server SHOULD only maintain a partial body (missing payloads) for 567 up to NON_PARTIAL_TIMEOUT (Section 6.2). 569 3.4. Using the Q-Block2 Option 571 In a request for any block number, the M bit unset indicates the 572 request is just for that block. If the M bit is set, this has 573 different meanings based on the NUM value: 575 NUM is zero: This is a request for the entire body. 577 'NUM modulo MAX_PAYLOADS' is zero, while NUM is not zero: This is 578 used to confirm that the current set of MAX_PAYLOADS payloads (the 579 latest one having block number NUM-1) has been successfully 580 received and that, upon receipt of this request, the server can 581 continue to send the next set of payloads (the first one having 582 block number NUM). This is the 'Continue' Q-Block-2 and 583 conceptually has the same usage (i.e., continue sending the next 584 set of data) as the use of 2.31 (Continue) for Q-Block1. 586 Any other value of NUM: This is a request for that block and for all 587 of the remaining blocks in the current MAX_PAYLOADS set. 589 If the request includes multiple Q-Block2 Options and these options 590 overlap (e.g., combination of M being set (this and later blocks) and 591 being unset (this individual block)) resulting in an individual block 592 being requested multiple times, the server MUST only send back one 593 instance of that block. This behavior is meant to prevent 594 amplification attacks. 596 The payloads sent back from the server as a response MUST all have 597 the same ETag (Section 5.10.6 of [RFC7252]) for the same body. The 598 server MUST NOT use the same ETag value for different representations 599 of a resource. 601 The ETag is opaque, the client still treats it as opaque but the 602 server SHOULD ensure that it is unique for every different body of 603 transmitted data. 605 Implementation Note: It is suggested that the server treats the 606 ETag as an unsigned integer of 8 bytes in length. An 607 implementation may want to consider limiting this to 4 bytes to 608 reduce packet overhead size. The initial ETag value should be 609 randomly generated and then subsequently incremented by the server 610 whenever a new body of data is being transmitted between peers. 612 Section 3.6 discusses the use of Size2 Option. 614 The client may elect to request any detected missing blocks or just 615 ignore the partial body. This decision is implementation specific. 617 The client SHOULD wait for up to NON_RECEIVE_TIMEOUT (Section 6.2) 618 after the last received payload for NON payloads before issuing a 619 GET, POST, PUT, FETCH, PATCH, or iPATCH request that contains one or 620 more Q-Block2 Options that define the missing blocks with the M bit 621 unset. It is permissible to set the M bit to request this and 622 missing blocks from this MAX_PAYLOADS set. Further considerations 623 related to the transmission timing for missing requests are discussed 624 in Section 6.2. 626 The requested missing block numbers MUST have an increasing block 627 number in each additional Q-Block2 Option with no duplicates. The 628 server SHOULD respond with a 4.00 (Bad Request) to requests not 629 adhering to this behavior. 631 For Confirmable responses, the client continues to acknowledge each 632 packet. The server acknowledges the initial request using an ACK 633 with the payload, and then sends the subsequent payloads as CON 634 responses. The server will detect failure to send a packet, but the 635 client can issue, after a MAX_TRANSMIT_SPAN delay, a separate GET, 636 POST, PUT, FETCH, PATCH, or iPATCH for any missing blocks as needed. 638 If the client receives a duplicate block with the same ETag, it 639 SHOULD silently ignore the packet. 641 A client SHOULD only maintain a partial body (missing payloads) for 642 up to NON_PARTIAL_TIMEOUT (Section 6.2) or as defined by the Max-Age 643 Option (or its default of 60 seconds (Section 5.6.1 of [RFC7252])), 644 whichever is the less. 646 The ETag Option should not be used in the request for missing blocks 647 as the server could respond with a 2.03 (Valid Response) with no 648 payload. It can be used in the request if the client wants to check 649 the freshness of the locally cached body response. 651 It is RECOMMENDED that the server maintains a cached copy of the body 652 when using the Q-Block2 Option to facilitate retransmission of any 653 missing payloads. 655 If the server detects part way through a body transfer that the 656 resource data has changed and the server is not maintaining a cached 657 copy of the old data, then the transmission is terminated. Any 658 subsequent missing block requests MUST be responded to using the 659 latest ETag and Size2 Option values with the updated data. 661 If the server responds during a body update with a different ETag 662 Option value (as the resource representation has changed), then the 663 client should treat the partial body with the old ETag as no longer 664 being fresh. 666 If the server transmits a new body of data (e.g., a triggered 667 Observe) with a new ETag to the same client as an additional 668 response, the client should remove any partially received body held 669 for a previous ETag for that resource as it is unlikely the missing 670 blocks can be retrieved. 672 If there is insufficient space to create a response PDU with a block 673 size of 16 bytes (SZX = 0) to send back all the response options as 674 appropriate, a 4.13 (Request Entity Too Large) is returned without 675 the Size1 Option. 677 3.5. Using Observe Option 679 For a request that uses Q-Block1, the Observe value [RFC7641] MUST be 680 the same for all the payloads of the same body. This includes any 681 missing payloads that are retransmitted. 683 For a response that uses Q-Block2, the Observe value MUST be the same 684 for all the payloads of the same body. This includes payloads 685 transmitted following receipt of the 'Continue' Q-Block2 Option 686 (Section 3.4) by the server. If a missing payload is requested, then 687 both the request and response MUST NOT include the Observe Option. 689 3.6. Using Size1 and Size2 Options 691 Section 4 of [RFC7959] defines two CoAP options: Size1 for indicating 692 the size of the representation transferred in requests and Size2 for 693 indicating the size of the representation transferred in responses. 695 The Size1 or Size2 option values MUST exactly represent the size of 696 the data on the body so that any missing data can easily be 697 determined. 699 The Size1 Option MUST be used with the Q-Block1 Option when used in a 700 request and MUST be present in all payloads of the request preserving 701 the same value. The Size2 Option MUST be used with the Q-Block2 702 Option when used in a response and MUST be present in all payloads of 703 the response preserving the same value. 705 3.7. Using Q-Block1 and Q-Block2 Options Together 707 The behavior is similar to the one defined in Section 3.3 of 708 [RFC7959] with Q-Block1 substituted for Block1 and Q-Block2 for 709 Block2. 711 3.8. Using Q-Block2 Option With Multicast 713 Servers MUST ignore multicast requests that contain the Q-Block2 714 Option. As a reminder, Block2 Option can be used as stated in 715 Section 2.8 of [RFC7959]. 717 4. The Use of 4.08 (Request Entity Incomplete) Response Code 719 4.08 (Request Entity Incomplete) Response Code has a new Content-Type 720 "application/missing-blocks+cbor-seq" used to indicate that the 721 server has not received all of the blocks of the request body that it 722 needs to proceed. 724 Likely causes are the client has not sent all blocks, some blocks 725 were dropped during transmission, or the client has sent them 726 sufficiently long ago that the server has already discarded them. 728 The data payload of the 4.08 (Request Entity Incomplete) response is 729 encoded as a CBOR Sequence [RFC8742]. It comprises of one or more 730 CBOR encoded [RFC8949] missing block numbers. The missing block 731 numbers MUST be unique in each 4.08 (Request Entity Incomplete) 732 response when created by the server; the client SHOULD drop any 733 duplicates in the same 4.08 (Request Entity Incomplete) response. 735 The Content-Format Option (Section 5.10.3 of [RFC7252]) MUST be used 736 in the 4.08 (Request Entity Incomplete) response. It MUST be set to 737 "application/missing-blocks+cbor-seq" (Section 10.3). 739 The Concise Data Definition Language [RFC8610] (and see Section 4.1 740 [RFC8742]) for the data describing these missing blocks is as 741 follows: 743 ; A notional array, the elements of which are to be used 744 ; in a CBOR Sequence: 745 payload = [+ missing-block-number] 746 ; A unique block number not received: 747 missing-block-number = uint 749 Figure 1: Structure of the Missing Blocks Payload 751 The token to use for the response SHOULD be the token that was used 752 in the last block number received so far with the same Request-Tag 753 value. Note that the use of any received token with the same 754 Request-Tag would work, but providing the one used in the last 755 received payload will aid any troubleshooting. The client will use 756 the token to determine what was the previously sent request to obtain 757 the Request-Tag value to be used. 759 If the size of the 4.08 (Request Entity Incomplete) response packet 760 is larger than that defined by Section 4.6 [RFC7252], then the number 761 of missing blocks MUST be limited so that the response can fit into a 762 single packet. If this is the case, then the server can send 763 subsequent 4.08 (Request Entity Incomplete) responses containing the 764 missing other blocks on receipt of a new request providing a missing 765 payload with the same Request-Tag. 767 The missing blocks MUST be reported in ascending order without any 768 duplicates. The client SHOULD silently drop 4.08 (Request Entity 769 Incomplete) responses not adhering with this behavior. 771 Implementation Note: Consider limiting the number of missing 772 payloads to MAX_PAYLOADS to minimize congestion control being 773 needed. The CBOR sequence does not include any array wrapper. 775 The 4.08 (Request Entity Incomplete) with Content-Type "application/ 776 missing-blocks+cbor-seq" SHOULD NOT be used when using Confirmable 777 requests or a reliable connection [RFC8323] as the client will be 778 able to determine that there is a transmission failure of a 779 particular payload and hence that the server is missing that payload. 781 5. The Use of Tokens 783 Each new request generally uses a new Token (and sometimes must, see 784 Section 4 of [I-D.ietf-core-echo-request-tag]). Additional responses 785 to a request all use the token of the request they respond to. 787 Implementation Note: To minimize on the number of tokens that have 788 to be tracked by clients, it is suggested that the bottom 32 bits 789 is kept the same for the same body and the upper 32 bits contains 790 the current body's request number (incrementing every request, 791 including every re-transmit). This allows the client to be 792 alleviated from keeping all the per-request-state, e.g., in 793 Section 3 of [RFC8974]. 795 6. Congestion Control for Unreliable Transports 797 The transmission of the payloads of a body over an unreliable 798 transport SHOULD either all be Confirmable or all be Non-confirmable. 799 This is meant to simplify the congestion control procedure. 801 As a reminder, there is no need for CoAP-specific congestion control 802 for reliable transports [RFC8323]. 804 6.1. Confirmable (CON) 806 Congestion control for CON requests and responses is specified in 807 Section 4.7 of [RFC7252]. For faster transmission rates, NSTART will 808 need to be increased from 1. However, the other CON congestion 809 control parameters will need to be tuned to cover this change. This 810 tuning is out of scope of this document as it is expected that all 811 requests and responses using Q-Block1 and Q-Block2 will be Non- 812 confirmable. 814 It is implementation specific as to whether there should be any 815 further requests for missing data as there will have been significant 816 transmission failure as individual payloads will have failed after 817 MAX_TRANSMIT_SPAN. 819 6.2. Non-confirmable (NON) 821 This document introduces new parameters MAX_PAYLOADS, NON_TIMEOUT, 822 NON_RECEIVE_TIMEOUT, NON_MAX_RETRANSMIT, NON_PROBING_WAIT, and 823 NON_PARTIAL_TIMEOUT primarily for use with NON (Table 3). 825 MAX_PAYLOADS should be configurable with a default value of 10. Both 826 CoAP endpoints SHOULD have the same value (otherwise there will be 827 transmission delays in one direction) and the value MAY be negotiated 828 between the endpoints to a common value by using a higher level 829 protocol (out of scope of this document). This is the maximum number 830 of payloads that can be transmitted at any one time. 832 Note: The default value of 10 is chosen for reasons similar to 833 those discussed in Section 5 of [RFC6928]. 835 NON_TIMEOUT is the maximum period of delay between sending sets of 836 MAX_PAYLOADS payloads for the same body. By default, NON_TIMEOUT has 837 the same value as ACK_TIMEOUT (Section 4.8 of [RFC7252]). 839 NON_RECEIVE_TIMEOUT is the initial maximum time to wait for a missing 840 payload before requesting retransmission for the first time. Every 841 time the missing payload is re-requested, the time to wait value 842 doubles. The time to wait is calculated as: 844 Time-to-Wait = NON_RECEIVE_TIMEOUT * (2 ** (Re-Request-Count - 1)) 846 NON_RECEIVE_TIMEOUT has a default value of twice NON_TIMEOUT. 847 NON_RECEIVE_TIMEOUT MUST always be greater than NON_TIMEOUT by at 848 least one second so that the sender of the payloads has the 849 opportunity to start sending the next set of payloads before the 850 receiver times out. 852 NON_MAX_RETRANSMIT is the maximum number of times a request for the 853 retransmission of missing payloads can occur without a response from 854 the remote peer. After this occurs, the local endpoint SHOULD 855 consider the body stale and remove all references to it. By default, 856 NON_MAX_RETRANSMIT has the same value as MAX_RETRANSMIT (Section 4.8 857 of [RFC7252]). 859 NON_PROBING_WAIT is used to limit the potential wait needed 860 calculated when using PROBING_WAIT. NON_PROBING_WAIT has the same 861 value as computed for EXCHANGE_LIFETIME (Section 4.8.2 of [RFC7252]). 863 NON_PARTIAL_TIMEOUT is used for expiring partially received bodies. 864 NON_PARTIAL_TIMEOUT has the same value as computed for 865 EXCHANGE_LIFETIME (Section 4.8.2 of [RFC7252]). 867 +---------------------+---------------+ 868 | Parameter Name | Default Value | 869 +=====================+===============| 870 | MAX_PAYLOADS | 10 | 871 | NON_MAX_RETRANSMIT | 4 | 872 | NON_TIMEOUT | 2 s | 873 | NON_RECEIVE_TIMEOUT | 4 s | 874 | NON_PROBING_WAIT | 247 s | 875 | NON_PARTIAL_TIMEOUT | 247 s | 876 +---------------------+---------------+ 878 Table 3: Congestion Control Parameters 880 PROBING_RATE parameter in CoAP indicates the average data rate that 881 must not be exceeded by a CoAP endpoint in sending to a peer endpoint 882 that does not respond. The single body of blocks will be subjected 883 to PROBING_RATE (Section 4.7 of [RFC7252]), not the individual 884 packets. If the wait time between sending bodies that are not being 885 responded to based on PROBING_RATE exceeds NON_PROBING_WAIT, then the 886 gap time is limited to NON_PROBING_WAIT. 888 Note: For the particular DOTS application, PROBING_RATE and other 889 transmission parameters are negotiated between peers. Even when 890 not negotiated, the DOTS application uses customized defaults as 891 discussed in Section 4.5.2 of [RFC8782]. Note that MAX_PAYLOADS, 892 NON_MAX_RETRANSMIT, and NON_TIMEOUT can be negotiated between DOTS 893 peers as per [I-D.bosh-dots-quick-blocks]. 895 Each NON 4.08 (Request Entity Incomplete) response is subject to 896 PROBING_RATE. 898 Each NON GET or FETCH request using Q-Block2 Option is subject to 899 PROBING_RATE. 901 As the sending of many payloads of a single body may itself cause 902 congestion, it is RECOMMENDED that after transmission of every set of 903 MAX_PAYLOADS payloads of a single body, a delay is introduced of 904 NON_TIMEOUT before sending the next set of payloads to manage 905 potential congestion issues. 907 If the CoAP peer reports at least one payload has not arrived for 908 each body for at least a 24 hour period and it is known that there 909 are no other network issues over that period, then the value of 910 MAX_PAYLOADS can be reduced by 1 at a time (to a minimum of 1) and 911 the situation re-evaluated for another 24 hour period until there is 912 no report of missing payloads under normal operating conditions. The 913 newly derived value for MAX_PAYLOADS should be used for both ends of 914 this particular CoAP peer link. Note that the CoAP peer will not 915 know about the MAX_PAYLOADS change until it is reconfigured. As a 916 consequence of the two peers having different MAX_PAYLOADS values, a 917 peer may continue indicate that there are some missing payloads as 918 all of its MAX_PAYLOADS set may not have arrived. How the two peer 919 values for MAX_PAYLOADS are synchronized is out of the scope. 921 The sending of a set of missing payloads of a body is subject to 922 MAX_PAYLOADS set of payloads. 924 For Q-Block1 Option, if the server responds with a 2.31 (Continue) 925 Response Code for the latest payload sent, then the client can 926 continue to send the next set of payloads without any delay. If the 927 server responds with a 4.08 (Request Entity Incomplete) Response 928 Code, then the missing payloads SHOULD be retransmitted before going 929 into another NON_TIMEOUT delay prior to sending the next set of 930 payloads. 932 For the server receiving NON Q-Block1 requests, it SHOULD send back a 933 2.31 (Continue) Response Code on receipt of all of the MAX_PAYLOADS 934 payloads to prevent the client unnecessarily delaying. Otherwise the 935 server SHOULD delay for NON_RECEIVE_TIMEOUT (exponentially scaled 936 based on the repeat request count for a payload), before sending the 937 4.08 (Request Entity Incomplete) Response Code for the missing 938 payload(s). If this is a repeat for the 2.31 (Continue) response, 939 the server SHOULD send a 4.08 (Request Entity Incomplete) response 940 detailing the missing payloads after the block number that would have 941 been indicated in the 2.31 (Continue). If the repeat request count 942 for a missing payload exceeds NON_MAX_RETRANSMIT, the server SHOULD 943 discard the partial body and stop requesting the missing payloads. 945 It is likely that the client will start transmitting the next set of 946 MAX_PAYLOADS payloads before the server times out on waiting for the 947 last of the previous MAX_PAYLOADS payloads. On receipt of the first 948 received payload from the new set of MAX_PAYLOADS payloads, the 949 server SHOULD send a 4.08 (Request Entity Incomplete) Response Code 950 indicating any missing payloads from any previous MAX_PAYLOADS 951 payloads. Upon receipt of the 4.08 (Request Entity Incomplete) 952 Response Code, the client SHOULD send the missing payloads before 953 continuing to send the remainder of the MAX_PAYLOADS payloads and 954 then go into another NON_TIMEOUT delay prior to sending the next set 955 of payloads. 957 For the client receiving NON Q-Block2 responses, it SHOULD send a 958 'Continue' Q-Block2 request (Section 3.4) for the next set of 959 payloads on receipt of all of the MAX_PAYLOADS payloads to prevent 960 the server unnecessarily delaying. Otherwise the client SHOULD delay 961 for NON_RECEIVE_TIMEOUT (exponentially scaled based on the repeat 962 request count for a payload), before sending the request for the 963 missing payload(s). If the repeat request count for a missing 964 payload exceeds NON_MAX_RETRANSMIT, the client SHOULD discard the 965 partial body and stop requesting the missing payloads. 967 The server SHOULD recognize the 'Continue' Q-Block2 request as a 968 continue request and just continue the transmission of the body 969 (including Observe Option, if appropriate for an unsolicited 970 response) rather than as a request for the remaining missing blocks. 972 It is likely that the server will start transmitting the next set of 973 MAX_PAYLOADS payloads before the client times out on waiting for the 974 last of the previous MAX_PAYLOADS payloads. Upon receipt of the 975 first payload from the new set of MAX_PAYLOADS payloads, the client 976 SHOULD send a request indicating any missing payloads from any 977 previous set of MAX_PAYLOADS payloads. Upon receipt of such request, 978 the server SHOULD send the missing payloads before continuing to send 979 the remainder of the MAX_PAYLOADS payloads and then go into another 980 NON_TIMEOUT delay prior to sending the next set of payloads. 982 The client does not need to acknowledge the receipt of the entire 983 body. 985 Note: If there is asymmetric traffic loss causing responses to 986 never get received, a delay of NON_TIMEOUT after every 987 transmission of MAX_PAYLOADS blocks will be observed. The 988 endpoint receiving the body is still likely to receive the entire 989 body. 991 7. Caching Considerations 993 Caching block based information is not straight forward in a proxy. 994 For Q-Block1 and Q-Block2 Options, for simplicity it is expected that 995 the proxy will reassemble the body (using any appropriate recovery 996 options for packet loss) before passing on the body to the 997 appropriate CoAP endpoint. This does not preclude an implementation 998 doing a more complex per payload caching, but how to do this is out 999 of the scope of this document. The onward transmission of the body 1000 does not require the use of the Q-Block1 or Q-Block2 Options as these 1001 options may not be supported in that link. This means that the proxy 1002 must fully support the Q-Block1 and Q-Block2 Options. 1004 How the body is cached in the CoAP client (for Q-Block1 1005 transmissions) or the CoAP server (for Q-Block2 transmissions) is 1006 implementation specific. 1008 As the entire body is being cached in the proxy, the Q-Block1 and 1009 Q-Block2 Options are removed as part of the block assembly and thus 1010 do not reach the cache. 1012 For Q-Block2 responses, the ETag Option value is associated with the 1013 data (and onward transmitted to the CoAP client), but is not part of 1014 the cache key. 1016 For requests with Q-Block1 Option, the Request-Tag Option is 1017 associated with the build up of the body from successive payloads, 1018 but is not part of the cache key. For the onward transmission of the 1019 body using CoAP, a new Request-Tag SHOULD be generated and used. 1020 Ideally this new Request-Tag should replace the client's request 1021 Request-Tag. 1023 It is possible that two or more CoAP clients are concurrently 1024 updating the same resource through a common proxy to the same CoAP 1025 server using Q-Block1 (or Block1) Option. If this is the case, the 1026 first client to complete building the body causes that body to start 1027 transmitting to the CoAP server with an appropriate Request-Tag 1028 value. When the next client completes building the body, any 1029 existing partial body transmission to the CoAP server is terminated 1030 and the new body representation transmission starts with a new 1031 Request-Tag value. Note that it cannot be assumed that the proxy 1032 will always receive a complete body from a client. 1034 A proxy that supports Q-Block2 Option MUST be prepared to receive a 1035 GET or similar request indicating one or more missing blocks. The 1036 proxy will serve from its cache the missing blocks that are available 1037 in its cache in the same way a server would send all the appropriate 1038 Q-Block2s. If the cache key matching body is not available in the 1039 cache, the proxy MUST request the entire body from the CoAP server 1040 using the information in the cache key. 1042 How long a CoAP endpoint (or proxy) keeps the body in its cache is 1043 implementation specific (e.g., it may be based on Max-Age). 1045 8. HTTP-Mapping Considerations 1047 As a reminder, the basic normative requirements on HTTP/CoAP mappings 1048 are defined in Section 10 of [RFC7252]. The implementation 1049 guidelines for HTTP/CoAP mappings are elaborated in [RFC8075]. 1051 The rules defined in Section 5 of [RFC7959] are to be followed. 1053 9. Examples with Non-confirmable Messages 1055 This section provides some sample flows to illustrate the use of 1056 Q-Block1 and Q-Block2 Options with NON. Examples with CON are 1057 provided in Appendix A. 1059 Figure 2 lists the conventions that are used in the following 1060 subsections. 1062 T: Token value 1063 O: Observe Option value 1064 M: Message ID 1065 RT: Request-Tag 1066 ET: ETag 1067 QB1: Q-Block1 Option values NUM/More/SZX 1068 QB2: Q-Block2 Option values NUM/More/SZX 1069 \: Trimming long lines 1070 [[]]: Comments 1071 -->X: Message loss (request) 1072 X<--: Message loss (response) 1073 ...: Passage of time 1075 Figure 2: Notations Used in the Figures 1077 9.1. Q-Block1 Option 1079 9.1.1. A Simple Example 1081 Figure 3 depicts an example of a NON PUT request conveying Q-Block1 1082 Option. All the blocks are received by the server. 1084 CoAP CoAP 1085 Client Server 1086 | | 1087 +--------->| NON PUT /path M:0x81 T:0xc0 RT=9 QB1:0/1/1024 1088 +--------->| NON PUT /path M:0x82 T:0xc1 RT=9 QB1:1/1/1024 1089 +--------->| NON PUT /path M:0x83 T:0xc2 RT=9 QB1:2/1/1024 1090 +--------->| NON PUT /path M:0x84 T:0xc3 RT=9 QB1:3/0/1024 1091 |<---------+ NON 2.04 M:0xf1 T:0xc3 1092 | ... | 1094 Figure 3: Example of NON Request with Q-Block1 Option (Without Loss) 1096 9.1.2. Handling MAX_PAYLOADS Limits 1098 Figure 4 depicts an example of a NON PUT request conveying Q-Block1 1099 Option. The number of payloads exceeds MAX_PAYLOADS. All the blocks 1100 are received by the server. 1102 CoAP CoAP 1103 Client Server 1104 | | 1105 +--------->| NON PUT /path M:0x01 T:0xf1 RT=10 QB1:0/1/1024 1106 +--------->| NON PUT /path M:0x02 T:0xf2 RT=10 QB1:1/1/1024 1107 +--------->| [[Payloads 3 - 9 not detailed]] 1108 +--------->| NON PUT /path M:0x0a T:0xfa RT=10 QB1:9/1/1024 1109 [[MAX_PAYLOADS has been reached]] 1110 | [[MAX_PAYLOADS blocks receipt acknowledged by server]] 1111 |<---------+ NON 2.31 M:0x81 T:0xfa 1112 +--------->| NON PUT /path M:0x0b T:0xfb RT=10 QB1:10/0/1024 1113 |<---------+ NON 2.04 M:0x82 T:0xfb 1114 | ... | 1116 Figure 4: Example of MAX_PAYLOADS NON Request with Q-Block1 Option 1117 (Without Loss) 1119 9.1.3. Handling MAX_PAYLOADS with Recovery 1121 Consider now a scenario where a new body of data is to be sent by the 1122 client, but some blocks are dropped in transmission as illustrated in 1123 Figure 5. 1125 CoAP CoAP 1126 Client Server 1127 | | 1128 +--------->| NON PUT /path M:0x11 T:0xe1 RT=11 QB1:0/1/1024 1129 +--->X | NON PUT /path M:0x12 T:0xe2 RT=11 QB1:1/1/1024 1130 +--------->| [[Payloads 3 - 8 not detailed]] 1131 +--------->| NON PUT /path M:0x19 T:0xe9 RT=11 QB1:8/1/1024 1132 +--->X | NON PUT /path M:0x1a T:0xea RT=11 QB1:9/1/1024 1133 [[MAX_PAYLOADS has been reached]] 1134 | ... | 1135 [[NON_TIMEOUT (client) delay expires]] 1136 | [[Client starts sending next set of payloads]] 1137 +--->X | NON PUT /path M:0x1b T:0xeb RT=11 QB1:10/1/1024 1138 +--------->| NON PUT /path M:0x1c T:0xec RT=11 QB1:11/1/1024 1139 | | 1141 Figure 5: Example of MAX_PAYLOADS NON Request with Q-Block1 Option 1142 (With Loss) 1144 On seeing a payload from the next set of payloads, the server 1145 realizes that some blocks are missing from the previous MAX_PAYLOADS 1146 payloads and asks for the missing blocks in one go (Figure 6). It 1147 does so by indicating which blocks from the previous MAX_PAYLOADS 1148 payloads have not been received in the data portion of the response. 1149 The token used in the response should be the token that was used in 1150 the last block number received payload. The client can then derive 1151 the Request-Tag by matching the token with the sent request. 1153 CoAP CoAP 1154 Client Server 1155 | | 1156 |<---------+ NON 4.08 M:0x91 T:0xec [Missing 1,9] 1157 | [[Client responds with missing payloads]] 1158 +--------->| NON PUT /path M:0x1d T:0xed RT=11 QB1:1/1/1024 1159 +--------->| NON PUT /path M:0x1e T:0xee RT=11 QB1:9/1/1024 1160 | [[Client continues sending next set of payloads]] 1161 +--------->| NON PUT /path M:0x1f T:0xef RT=11 QB1:12/0/1024 1162 | ... | 1163 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1164 | [[The server realizes a block is still missing and asks 1165 | for the missing one]] 1166 |<---------+ NON 4.08 M:0x92 T:0xef [Missing 10] 1167 +--------->| NON PUT /path M:0x20 T:0xf0 RT=11 QB1:10/1/1024 1168 |<---------+ NON 2.04 M:0x93 T:0xf0 1169 | ... | 1171 Figure 6: Example of NON Request with Q-Block1 Option (Blocks 1172 Recovery) 1174 9.1.4. Handling Recovery with Failure 1176 Figure 7 depicts an example of a NON PUT request conveying Q-Block1 1177 Option where recovery takes place, but eventually fails. 1179 CoAP CoAP 1180 Client Server 1181 | | 1182 +--------->| NON PUT /path M:0x91 T:0xd0 RT=12 QB1:0/1/1024 1183 +--->X | NON PUT /path M:0x92 T:0xd1 RT=12 QB1:1/1/1024 1184 +--------->| NON PUT /path M:0x93 T:0xd2 RT=12 QB1:2/0/1024 1185 | ... | 1186 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1187 | [[The server realizes a block is missing and asks 1188 | for the missing one. Retry #1]] 1189 |<---------+ NON 4.08 M:0x01 T:0xd2 [Missing 1] 1190 | ... | 1191 [[2 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1192 | [[The server realizes a block is still missing and asks 1193 | for the missing one. Retry #2]] 1194 |<---------+ NON 4.08 M:0x02 T:0xd2 [Missing 1] 1195 | ... | 1196 [[4 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1197 | [[The server realizes a block is still missing and asks 1198 | for the missing one. Retry #3]] 1199 |<---------+ NON 4.08 M:0x03 T:0xd2 [Missing 1] 1200 | ... | 1201 [[8 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1202 | [[The server realizes a block is still missing and asks 1203 | for the missing one. Retry #4]] 1204 |<---------+ NON 4.08 M:0x04 T:0xd2 [Missing 1] 1205 | ... | 1206 [[16 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1207 | [[NON_MAX_RETRANSMIT exceeded. Server stops requesting 1208 | for missing blocks and releases partial body]] 1209 | ... | 1211 Figure 7: Example of NON Request with Q-Block1 Option (With Eventual 1212 Failure) 1214 9.2. Q-Block2 Option 1216 These examples include the Observe Option to demonstrate how that 1217 option is used. Note that the Observe Option is not required for 1218 Q-Block2; the observe detail can thus be ignored. 1220 9.2.1. A Simple Example 1222 Figure 8 illustrates the example of Q-Block2 Option. The client 1223 sends a NON GET carrying Observe and Q-Block2 Options. The Q-Block2 1224 Option indicates a block size hint (1024 bytes). This request is 1225 replied to by the server using four (4) blocks that are transmitted 1226 to the client without any loss. Each of these blocks carries a 1227 Q-Block2 Option. The same process is repeated when an Observe is 1228 triggered, but no loss is experienced by any of the notification 1229 blocks. 1231 CoAP CoAP 1232 Client Server 1233 | | 1234 +--------->| NON GET /path M:0x01 T:0xc0 O:0 QB2:0/1/1024 1235 |<---------+ NON 2.05 M:0xf1 T:0xc0 O:1220 ET=19 QB2:0/1/1024 1236 |<---------+ NON 2.05 M:0xf2 T:0xc0 O:1220 ET=19 QB2:1/1/1024 1237 |<---------+ NON 2.05 M:0xf3 T:0xc0 O:1220 ET=19 QB2:2/1/1024 1238 |<---------+ NON 2.05 M:0xf4 T:0xc0 O:1220 ET=19 QB2:3/0/1024 1239 | ... | 1240 | [[Observe triggered]] 1241 |<---------+ NON 2.05 M:0xf5 T:0xc0 O:1221 ET=20 QB2:0/1/1024 1242 |<---------+ NON 2.05 M:0xf6 T:0xc0 O:1221 ET=20 QB2:1/1/1024 1243 |<---------+ NON 2.05 M:0xf7 T:0xc0 O:1221 ET=20 QB2:2/1/1024 1244 |<---------+ NON 2.05 M:0xf8 T:0xc0 O:1221 ET=20 QB2:3/0/1024 1245 | ... | 1247 Figure 8: Example of NON Notifications with Q-Block2 Option (Without 1248 Loss) 1250 9.2.2. Handling MAX_PAYLOADS Limits 1252 Figure 9 illustrates the same as Figure 8 but this time has eleven 1253 (11) payloads which exceeds MAX_PAYLOADS. There is no loss 1254 experienced. 1256 CoAP CoAP 1257 Client Server 1258 | | 1259 +--------->| NON GET /path M:0x01 T:0xf0 O:0 QB2:0/1/1024 1260 |<---------+ NON 2.05 M:0x81 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1261 |<---------+ NON 2.05 M:0x82 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1262 |<---------+ [[Payloads 3 - 9 not detailed]] 1263 |<---------+ NON 2.05 M:0x8a T:0xf0 O:1234 ET=21 QB2:9/1/1024 1264 [[MAX_PAYLOADS has been reached]] 1265 | [[MAX_PAYLOADS blocks acknowledged by client using 1266 | 'Continue' Q-Block2]] 1267 +--------->| NON GET /path M:0x02 T:0xf1 QB2:10/1/1024 1268 |<---------+ NON 2.05 M:0x8b T:0xf0 O:1234 ET=21 QB2:10/0/1024 1269 | ... | 1270 | [[Observe triggered]] 1271 |<---------+ NON 2.05 M:0x91 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1272 |<---------+ NON 2.05 M:0x92 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1273 |<---------+ [[Payloads 3 - 9 not detailed]] 1274 |<---------+ NON 2.05 M:0x9a T:0xf0 O:1235 ET=22 QB2:9/1/1024 1275 [[MAX_PAYLOADS has been reached]] 1276 | [[MAX_PAYLOADS blocks acknowledged by client using 1277 | 'Continue' Q-Block2]] 1278 +--------->| NON GET /path M:0x03 T:0xf2 QB2:10/1/1024 1279 |<---------+ NON 2.05 M:0x9b T:0xf0 O:1235 ET=22 QB2:10/0/1024 1280 [[Body has been received]] 1281 | ... | 1283 Figure 9: Example of NON Notifications with Q-Block2 Option (Without 1284 Loss) 1286 9.2.3. Handling MAX_PAYLOADS with Recovery 1288 Figure 10 shows the example of an Observe that is triggered but for 1289 which some notification blocks are lost. The client detects the 1290 missing blocks and requests their retransmission. It does so by 1291 indicating the blocks that are missing as one or more Q-Block2 1292 Options. 1294 CoAP CoAP 1295 Client Server 1296 | ... | 1297 | [[Observe triggered]] 1298 |<---------+ NON 2.05 M:0xa1 T:0xf0 O:1236 ET=23 QB2:0/1/1024 1299 | X<---+ NON 2.05 M:0xa2 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1300 |<---------+ [[Payloads 3 - 8 not detailed]] 1301 | X<---+ NON 2.05 M:0xaa T:0xf0 O:1236 ET=23 QB2:9/1/1024 1302 [[MAX_PAYLOADS has been reached]] 1303 | ... | 1304 [[NON_TIMEOUT (server) delay expires]] 1305 | [[Server sends next set of payloads]] 1306 |<---------+ NON 2.05 M:0xab T:0xf0 O:1236 ET=23 QB2:10/0/1024 1307 | ... | 1308 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1309 | [[Client realizes blocks are missing and asks for the 1310 | missing ones in one go]] 1311 +--------->| NON GET /path M:0x04 T:0xf3 QB2:1/0/1024\ 1312 | | QB2:9/0/1024 1313 | X<---+ NON 2.05 M:0xac T:0xf3 ET=23 QB2:1/1/1024 1314 |<---------+ NON 2.05 M:0xad T:0xf3 ET=23 QB2:9/1/1024 1315 | ... | 1316 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1317 | [[Client realizes block is still missing and asks for 1318 | missing block]] 1319 +--------->| NON GET /path M:0x05 T:0xf4 QB2:1/0/1024 1320 |<---------+ NON 2.05 M:0xae T:0xf4 ET=23 QB2:1/1/1024 1321 [[Body has been received]] 1322 | ... | 1324 Figure 10: Example of NON Notifications with Q-Block2 Option (Blocks 1325 Recovery) 1327 9.2.4. Handling Recovery using M-bit Set 1329 Figure 11 shows the example of an Observe that is triggered but only 1330 the first two notification blocks reach the client. In order to 1331 retrieve the missing blocks, the client sends a request with a single 1332 Q-Block2 Option with the M bit set. 1334 CoAP CoAP 1335 Client Server 1336 | ... | 1337 | [[Observe triggered]] 1338 |<---------+ NON 2.05 M:0xb1 T:0xf0 O:1237 ET=24 QB2:0/1/1024 1339 |<---------+ NON 2.05 M:0xb2 T:0xf0 O:1237 ET=24 QB2:1/1/1024 1340 | X<---+ NON 2.05 M:0xb3 T:0xf0 O:1237 ET=24 QB2:2/1/1024 1341 | X<---+ [[Payloads 4 - 9 not detailed]] 1342 | X<---+ NON 2.05 M:0xb9 T:0xf0 O:1237 ET=24 QB2:9/1/1024 1343 [[MAX_PAYLOADS has been reached]] 1344 | ... | 1345 [[NON_TIMEOUT (server) delay expires]] 1346 | [[Server sends next set of payloads]] 1347 | X<---+ NON 2.05 M:0xba T:0xf0 O:1237 ET=24 QB2:10/0/1024 1348 | ... | 1349 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1350 | [[Client realizes blocks are missing and asks for the 1351 | missing ones in one go by setting the M bit]] 1352 +--------->| NON GET /path M:0x06 T:0xf5 QB2:2/1/1024 1353 |<---------+ NON 2.05 M:0xbb T:0xf5 ET=24 QB2:2/1/1024 1354 |<---------+ [[Payloads 3 - 9 not detailed]] 1355 |<---------+ NON 2.05 M:0xc2 T:0xf5 ET=24 QB2:9/1/1024 1356 [[MAX_PAYLOADS has been reached]] 1357 | [[MAX_PAYLOADS acknowledged by client using 'Continue' 1358 | Q-Block2]] 1359 +--------->| NON GET /path M:0x87 T:0xf6 QB2:10/1/1024 1360 |<---------+ NON 2.05 M:0xc3 T:0xf0 O:1237 ET=24 QB2:10/0/1024 1361 [[Body has been received]] 1362 | ... | 1364 Figure 11: Example of NON Notifications with Q-Block2 Option (Blocks 1365 Recovery with M bit Set) 1367 9.3. Q-Block1 and Q-Block2 Options 1369 9.3.1. A Simple Example 1371 Figure 12 illustrates the example of a FETCH using both Q-Block1 and 1372 Q-Block2 Options along with an Observe Option. No loss is 1373 experienced. 1375 CoAP CoAP 1376 Client Server 1377 | | 1378 +--------->| NON FETCH /path M:0x10 T:0x90 O:0 RT=30 QB1:0/1/1024 1379 +--------->| NON FETCH /path M:0x11 T:0x91 O:0 RT=30 QB1:1/1/1024 1380 +--------->| NON FETCH /path M:0x12 T:0x93 O:0 RT=30 QB1:2/0/1024 1381 |<---------+ NON 2.05 M:0x60 T:0x93 O:1320 ET=90 QB2:0/1/1024 1382 |<---------+ NON 2.05 M:0x61 T:0x93 O:1320 ET=90 QB2:1/1/1024 1383 |<---------+ NON 2.05 M:0x62 T:0x93 O:1320 ET=90 QB2:2/1/1024 1384 |<---------+ NON 2.05 M:0x63 T:0x93 O:1320 ET=90 QB2:3/0/1024 1385 | ... | 1386 | [[Observe triggered]] 1387 |<---------+ NON 2.05 M:0x64 T:0x93 O:1321 ET=91 QB2:0/1/1024 1388 |<---------+ NON 2.05 M:0x65 T:0x93 O:1321 ET=91 QB2:1/1/1024 1389 |<---------+ NON 2.05 M:0x66 T:0x93 O:1321 ET=91 QB2:2/1/1024 1390 |<---------+ NON 2.05 M:0x67 T:0x93 O:1321 ET=91 QB2:3/0/1024 1391 | ... | 1393 Figure 12: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1394 (Without Loss) 1396 9.3.2. Handling MAX_PAYLOADS Limits 1398 Figure 13 illustrates the same as Figure 12 but this time has eleven 1399 (11) payloads in both directions which exceeds MAX_PAYLOADS. There 1400 is no loss experienced. 1402 CoAP CoAP 1403 Client Server 1404 | | 1405 +--------->| NON FETCH /path M:0x30 T:0xa0 O:0 RT=10 QB1:0/1/1024 1406 +--------->| NON FETCH /path M:0x31 T:0xa1 O:0 RT=10 QB1:1/1/1024 1407 +--------->| [[Payloads 3 - 9 not detailed]] 1408 +--------->| NON FETCH /path M:0x39 T:0xa9 O:0 RT=10 QB1:9/1/1024 1409 [[MAX_PAYLOADS has been reached]] 1410 | [[MAX_PAYLOADS blocks receipt acknowledged by server]] 1411 |<---------+ NON 2.31 M:0x80 T:0xa9 1412 +--------->| NON FETCH /path M:0x3a T:0xaa O:0 RT=10 QB1:10/0/1024 1413 |<---------+ NON 2.05 M:0x81 T:0xaa O:1334 ET=21 QB2:0/1/1024 1414 |<---------+ NON 2.05 M:0x82 T:0xaa O:1334 ET=21 QB2:1/1/1024 1415 |<---------+ [[Payloads 3 - 9 not detailed]] 1416 |<---------+ NON 2.05 M:0x8a T:0xaa O:1334 ET=21 QB2:9/1/1024 1417 [[MAX_PAYLOADS has been reached]] 1418 | [[MAX_PAYLOADS blocks acknowledged by client using 1419 | 'Continue' Q-Block2]] 1420 +--------->| NON FETCH /path M:0x3b T:0xab QB2:10/1/1024 1421 |<---------+ NON 2.05 M:0x8b T:0xaa O:1334 ET=21 QB2:10/0/1024 1422 | ... | 1423 | [[Observe triggered]] 1424 |<---------+ NON 2.05 M:0x8c T:0xaa O:1335 ET=22 QB2:0/1/1024 1425 |<---------+ NON 2.05 M:0x8d T:0xaa O:1335 ET=22 QB2:1/1/1024 1426 |<---------+ [[Payloads 3 - 9 not detailed]] 1427 |<---------+ NON 2.05 M:0x95 T:0xaa O:1335 ET=22 QB2:9/1/1024 1428 [[MAX_PAYLOADS has been reached]] 1429 | [[MAX_PAYLOADS blocks acknowledged by client using 1430 | 'Continue' Q-Block2]] 1431 +--------->| NON FETCH /path M:0x3c T:0xac QB2:10/1/1024 1432 |<---------+ NON 2.05 M:0x96 T:0xaa O:1335 ET=22 QB2:10/0/1024 1433 [[Body has been received]] 1434 | ... | 1436 Figure 13: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1437 (Without Loss) 1439 9.3.3. Handling Recovery 1441 Consider now a scenario where there are some blocks are lost in 1442 transmission as illustrated in Figure 14. 1444 CoAP CoAP 1445 Client Server 1446 | | 1447 +--------->| NON FETCH /path M:0x50 T:0xc0 O:0 RT=31 QB1:0/1/1024 1448 +--->X | NON FETCH /path M:0x51 T:0xc1 O:0 RT=31 QB1:1/1/1024 1449 +--->X | NON FETCH /path M:0x52 T:0xc2 O:0 RT=31 QB1:2/1/1024 1450 +--------->| NON FETCH /path M:0x53 T:0xc3 O:0 RT=31 QB1:3/0/1024 1451 | ... | 1452 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1454 Figure 14: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1455 (With Loss) 1457 The server realizes that some blocks are missing and asks for the 1458 missing blocks in one go (Figure 15). It does so by indicating which 1459 blocks have not been received in the data portion of the response. 1460 The token used in the response is be the token that was used in the 1461 last block number received payload. The client can then derive the 1462 Request-Tag by matching the token with the sent request. 1464 CoAP CoAP 1465 Client Server 1466 | | 1467 |<---------+ NON 4.08 M:0xa0 T:0xc3 [Missing 1,2] 1468 | [[Client responds with missing payloads]] 1469 +--------->| NON FETCH /path M:0x54 T:0xc4 O:0 RT=31 QB1:1/1/1024 1470 +--------->| NON FETCH /path M:0x55 T:0xc5 O:0 RT=31 QB1:2/1/1024 1471 | [[Server received FETCH body, 1472 | starts transmitting response body]] 1473 |<---------+ NON 2.05 M:0xa1 T:0xc3 O:1236 ET=23 QB2:0/1/1024 1474 | X<---+ NON 2.05 M:0xa2 T:0xc3 O:1236 ET=23 QB2:1/1/1024 1475 |<---------+ NON 2.05 M:0xa3 T:0xc3 O:1236 ET=23 QB2:2/1/1024 1476 | X<---+ NON 2.05 M:0xa4 T:0xc3 O:1236 ET=23 QB2:3/0/1024 1477 | ... | 1478 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1479 | | 1481 Figure 15: Example of NON Request with Q-Block1 Option (Server 1482 Recovery) 1484 The client realizes that not all the payloads of the response have 1485 been returned. The client then asks for the missing blocks in one go 1486 (Figure 16). Note that, following Section 2.7 of [RFC7959], the 1487 FETCH request does not include the Q-Block1 or any payload. 1489 CoAP CoAP 1490 Client Server 1491 | | 1492 +--------->| NON FETCH /path M:0x56 T:0xc6 RT=31 QB2:1/0/1024\ 1493 | | QB2:3/0/1024 1494 | [[Server receives FETCH request for missing payloads, 1495 | starts transmitting missing blocks]] 1496 | X<---+ NON 2.05 M:0xa5 T:0xc6 ET=23 QB2:1/1/1024 1497 |<---------+ NON 2.05 M:0xa6 T:0xc6 ET=23 QB2:3/0/1024 1498 | ... | 1499 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1500 | [[Client realizes block is still missing and asks for 1501 | missing block]] 1502 +--------->| NON FETCH /path M:0x57 T:0xc7 RT=31 QB2:1/0/1024 1503 | [[Server receives FETCH request for missing payload, 1504 | starts transmitting missing block]] 1505 |<---------+ NON 2.05 M:0xa7 T:0xc7 ET=23 QB2:1/1/1024 1506 [[Body has been received]] 1507 | ... | 1508 | [[Observe triggered]] 1509 |<---------+ NON 2.05 M:0xa8 T:0xc3 O:1337 ET=24 QB2:0/1/1024 1510 | X<---+ NON 2.05 M:0xa9 T:0xc3 O:1337 ET=24 QB2:1/1/1024 1511 |<---------+ NON 2.05 M:0xaa T:0xc3 O:1337 ET=24 QB2:2/0/1024 1512 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1513 | [[Client realizes block is still missing and asks for 1514 | missing block]] 1515 +--------->| NON FETCH /path M:0x58 T:0xc8 RT=31 QB2:1/0/1024 1516 | [[Server receives FETCH request for missing payload, 1517 | starts transmitting missing block]] 1518 |<---------+ NON 2.05 M:0xa7 T:0xc8 ET=23 QB2:1/1/1024 1519 [[Body has been received]] 1520 | ... | 1522 Figure 16: Example of NON Request with Q-Block1 Option (Client 1523 Recovery) 1525 10. IANA Considerations 1527 10.1. New CoAP Options 1529 IANA is requested to add the following entries to the "CoAP Option 1530 Numbers" sub-registry [Options]: 1532 +--------+------------------+-----------+ 1533 | Number | Name | Reference | 1534 +========+==================+===========+ 1535 | TBA1 | Q-Block1 | [RFCXXXX] | 1536 | TBA2 | Q-Block2 | [RFCXXXX] | 1537 +--------+------------------+-----------+ 1539 Table 4: CoAP Q-Block1 and Q-Block2 Option Numbers 1541 This document suggests 19 (TBA1) and 51 (TBA2) as values to be 1542 assigned for the new option numbers. 1544 10.2. New Media Type 1546 This document requests IANA to register the "application/missing- 1547 blocks+cbor-seq" media type in the "Media Types" registry 1548 [IANA-MediaTypes]: 1550 Type name: application 1552 Subtype name: missing-blocks+cbor-seq 1554 Required parameters: N/A 1556 Optional parameters: N/A 1558 Encoding considerations: binary 1560 Security considerations: See the Security Considerations Section of 1561 [This_Document]. 1563 Interoperability considerations: N/A 1565 Published specification: [This_Document] 1567 Applications that use this media type: Data serialization and 1568 deserialization. 1570 Fragment identifier considerations: N/A 1572 Additional information: 1574 Deprecated alias names for this type: N/A 1575 Magic number(s): N/A 1576 File extension(s): N/A 1577 Macintosh file type code(s): N/A 1579 Person & email address to contact for further information: IETF, 1580 iesg@ietf.org 1582 Intended usage: COMMON 1584 Restrictions on usage: none 1586 Author: See Authors' Addresses section. 1588 Change controller: IESG 1590 Provisional registration? No 1592 10.3. New Content Format 1594 This document requests IANA to register the CoAP Content-Format ID 1595 for the "application/missing-blocks+cbor-seq" media type in the "CoAP 1596 Content-Formats" registry [Format]: 1598 o Media Type: application/missing-blocks+cbor-seq 1599 o Encoding: - 1600 o Id: TBA3 1601 o Reference: [RFCXXXX] 1603 This document suggests 272 (TBA3) as a value to be assigned for the 1604 new content format number. 1606 11. Security Considerations 1608 Security considerations discussed in Section 7 of [RFC7959] should be 1609 taken into account. 1611 Security considerations discussed in Sections 11.3 and 11.4 of 1612 [RFC7252] should be taken into account. 1614 OSCORE provides end-to-end protection of all information that is not 1615 required for proxy operations and requires that a security context is 1616 set up (Section 3.1 of [RFC8613]). It can be trusted that the source 1617 endpoint is legitimate even if NoSec security mode is used. However, 1618 an intermediary node can modify the unprotected outer Q-Block1 and/or 1619 Q-Block2 Options to cause a Q-Block transfer to fail or keep 1620 requesting all the blocks by setting the M bit and, thus, causing 1621 attack amplification. As discussed in Section 12.1 of [RFC8613], 1622 applications need to consider that certain message fields and 1623 messages types are not protected end-to-end and may be spoofed or 1624 manipulated. It is NOT RECOMMENDED that the NoSec security mode is 1625 used if the Q-Block1 and Q-Block2 Options are to be used. 1627 Security considerations related to the use of Request-Tag are 1628 discussed in Section 5 of [I-D.ietf-core-echo-request-tag]. 1630 12. Acknowledgements 1632 Thanks to Achim Kraus, Jim Schaad, and Michael Richardson for their 1633 comments. 1635 Special thanks to Christian Amsuess, Carsten Bormann, and Marco 1636 Tiloca for their suggestions and several reviews, which improved this 1637 specification significantly. 1639 Some text from [RFC7959] is reused for readers convenience. 1641 13. References 1642 13.1. Normative References 1644 [I-D.ietf-core-echo-request-tag] 1645 Amsuess, C., Mattsson, J., and G. Selander, "CoAP: Echo, 1646 Request-Tag, and Token Processing", draft-ietf-core-echo- 1647 request-tag-11 (work in progress), November 2020. 1649 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1650 Requirement Levels", BCP 14, RFC 2119, 1651 DOI 10.17487/RFC2119, March 1997, 1652 . 1654 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1655 Application Protocol (CoAP)", RFC 7252, 1656 DOI 10.17487/RFC7252, June 2014, 1657 . 1659 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1660 Application Protocol (CoAP)", RFC 7641, 1661 DOI 10.17487/RFC7641, September 2015, 1662 . 1664 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1665 the Constrained Application Protocol (CoAP)", RFC 7959, 1666 DOI 10.17487/RFC7959, August 2016, 1667 . 1669 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1670 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1671 the Constrained Application Protocol (CoAP)", RFC 8075, 1672 DOI 10.17487/RFC8075, February 2017, 1673 . 1675 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1676 FETCH Methods for the Constrained Application Protocol 1677 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1678 . 1680 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1681 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1682 May 2017, . 1684 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1685 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1686 Application Protocol) over TCP, TLS, and WebSockets", 1687 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1688 . 1690 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1691 "Object Security for Constrained RESTful Environments 1692 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1693 . 1695 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 1696 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 1697 . 1699 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1700 Representation (CBOR)", STD 94, RFC 8949, 1701 DOI 10.17487/RFC8949, December 2020, 1702 . 1704 13.2. Informative References 1706 [Format] "CoAP Content-Formats", . 1709 [I-D.bosh-dots-quick-blocks] 1710 Boucadair, M. and J. Shallow, "Distributed Denial-of- 1711 Service Open Threat Signaling (DOTS) Signal Channel 1712 Configuration Attributes for Faster Block Transmission", 1713 draft-bosh-dots-quick-blocks-01 (work in progress), 1714 January 2021. 1716 [I-D.ietf-dots-telemetry] 1717 Boucadair, M., Reddy.K, T., Doron, E., chenmeiling, c., 1718 and J. Shallow, "Distributed Denial-of-Service Open Threat 1719 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-15 1720 (work in progress), December 2020. 1722 [IANA-MediaTypes] 1723 IANA, "Media Types", 1724 . 1726 [Options] "CoAP Option Numbers", . 1729 [RFC6928] Chu, J., Dukkipati, N., Cheng, Y., and M. Mathis, 1730 "Increasing TCP's Initial Window", RFC 6928, 1731 DOI 10.17487/RFC6928, April 2013, 1732 . 1734 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1735 Definition Language (CDDL): A Notational Convention to 1736 Express Concise Binary Object Representation (CBOR) and 1737 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1738 June 2019, . 1740 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 1741 Mortensen, A., and N. Teague, "Distributed Denial-of- 1742 Service Open Threat Signaling (DOTS) Signal Channel 1743 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 1744 . 1746 [RFC8974] Hartke, K. and M. Richardson, "Extended Tokens and 1747 Stateless Clients in the Constrained Application Protocol 1748 (CoAP)", RFC 8974, DOI 10.17487/RFC8974, January 2021, 1749 . 1751 Appendix A. Examples with Confirmable Messages 1753 These examples assume NSTART has been increased to 3. 1755 The notations provided in Figure 2 are used in the following 1756 subsections. 1758 A.1. Q-Block1 Option 1760 Let's now consider the use Q-Block1 Option with a CON request as 1761 shown in Figure 17. All the blocks are acknowledged (ACK). 1763 CoAP CoAP 1764 Client Server 1765 | | 1766 +--------->| CON PUT /path M:0x01 T:0xf0 RT=10 QB1:0/1/1024 1767 +--------->| CON PUT /path M:0x02 T:0xf1 RT=10 QB1:1/1/1024 1768 +--------->| CON PUT /path M:0x03 T:0xf2 RT=10 QB1:2/1/1024 1769 [[NSTART(3) limit reached]] 1770 |<---------+ ACK 0.00 M:0x01 1771 +--------->| CON PUT /path M:0x04 T:0xf3 RT=10 QB1:3/0/1024 1772 |<---------+ ACK 0.00 M:0x02 1773 |<---------+ ACK 0.00 M:0x03 1774 |<---------+ ACK 2.04 M:0x04 1775 | | 1777 Figure 17: Example of CON Request with Q-Block1 Option (Without Loss) 1779 Now, suppose that a new body of data is to be sent but with some 1780 blocks dropped in transmission as illustrated in Figure 18. The 1781 client will retry sending blocks for which no ACK was received. 1783 CoAP CoAP 1784 Client Server 1785 | | 1786 +--------->| CON PUT /path M:0x05 T:0xf4 RT=11 QB1:0/1/1024 1787 +--->X | CON PUT /path M:0x06 T:0xf5 RT=11 QB1:1/1/1024 1788 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1789 [[NSTART(3) limit reached]] 1790 |<---------+ ACK 0.00 M:0x05 1791 +--------->| CON PUT /path M:0x08 T:0xf7 RT=11 QB1:3/1/1024 1792 |<---------+ ACK 0.00 M:0x08 1793 | ... | 1794 [[ACK_TIMEOUT (client) for M:0x06 delay expires]] 1795 | [[Client retransmits packet]] 1796 +--------->| CON PUT /path M:0x06 T:0xf5 RT=11 QB1:1/1/1024 1797 [[ACK_TIMEOUT (client) for M:0x07 delay expires]] 1798 | [[Client retransmits packet]] 1799 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1800 |<---------+ ACK 0.00 M:0x06 1801 | ... | 1802 [[ACK_TIMEOUT exponential backoff (client) delay expires]] 1803 | [[Client retransmits packet]] 1804 +--->? | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1805 | ... | 1806 [[Either body transmission failure (acknowledge retry timeout) 1807 or successfully transmitted.]] 1809 Figure 18: Example of CON Request with Q-Block1 Option (Blocks 1810 Recovery) 1812 It is up to the implementation as to whether the application process 1813 stops trying to send this particular body of data on reaching 1814 MAX_RETRANSMIT for any payload, or separately tries to initiate the 1815 new transmission of the payloads that have not been acknowledged 1816 under these adverse traffic conditions. 1818 If there is likely to be the possibility of network transient losses, 1819 then the use of NON should be considered. 1821 A.2. Q-Block2 Option 1823 An example of the use of Q-Block2 Option with Confirmable messages is 1824 shown in Figure 19. 1826 Client Server 1827 | | 1828 +--------->| CON GET /path M:0x01 T:0xf0 O:0 QB2:0/1/1024 1829 |<---------+ ACK 2.05 M:0x01 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1830 |<---------+ CON 2.05 M:0xe1 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1831 |<---------+ CON 2.05 M:0xe2 T:0xf0 O:1234 ET=21 QB2:2/1/1024 1832 |<---------+ CON 2.05 M:0xe3 T:0xf0 O:1234 ET=21 QB2:3/0/1024 1833 |--------->+ ACK 0.00 M:0xe1 1834 |--------->+ ACK 0.00 M:0xe2 1835 |--------->+ ACK 0.00 M:0xe3 1836 | ... | 1837 | [[Observe triggered]] 1838 |<---------+ CON 2.05 M:0xe4 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1839 |<---------+ CON 2.05 M:0xe5 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1840 |<---------+ CON 2.05 M:0xe6 T:0xf0 O:1235 ET=22 QB2:2/1/1024 1841 [[NSTART(3) limit reached]] 1842 |--------->+ ACK 0.00 M:0xe4 1843 |<---------+ CON 2.05 M:0xe7 T:0xf0 O:1235 ET=22 QB2:3/0/1024 1844 |--------->+ ACK 0.00 M:0xe5 1845 |--------->+ ACK 0.00 M:0xe6 1846 |--------->+ ACK 0.00 M:0xe7 1847 | ... | 1848 | [[Observe triggered]] 1849 |<---------+ CON 2.05 M:0xe8 T:0xf0 O:1236 ET=23 QB2:0/1/1024 1850 | X<---+ CON 2.05 M:0xe9 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1851 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1852 [[NSTART(3) limit reached]] 1853 |--------->+ ACK 0.00 M:0xe8 1854 |<---------+ CON 2.05 M:0xeb T:0xf0 O:1236 ET=23 QB2:3/0/1024 1855 |--------->+ ACK 0.00 M:0xeb 1856 | ... | 1857 [[ACK_TIMEOUT (server) for M:0xe9 delay expires]] 1858 | [[Server retransmits packet]] 1859 |<---------+ CON 2.05 M:0xe9 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1860 [[ACK_TIMEOUT (server) for M:0xea delay expires]] 1861 | [[Server retransmits packet]] 1862 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1863 |--------->+ ACK 0.00 M:0xe9 1864 | ... | 1865 [[ACK_TIMEOUT exponential backoff (server) delay expires]] 1866 | [[Server retransmits packet]] 1867 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1868 | ... | 1869 [[Either body transmission failure (acknowledge retry timeout) 1870 or successfully transmitted.]] 1872 Figure 19: Example of CON Notifications with Q-Block2 Option 1874 It is up to the implementation as to whether the application process 1875 stops trying to send this particular body of data on reaching 1876 MAX_RETRANSMIT for any payload, or separately tries to initiate the 1877 new transmission of the payloads that have not been acknowledged 1878 under these adverse traffic conditions. 1880 If there is likely to be the possibility of network transient losses, 1881 then the use of NON should be considered. 1883 Appendix B. Examples with Reliable Transports 1885 The notations provided in Figure 2 are used in the following 1886 subsections. 1888 B.1. Q-Block1 Option 1890 Let's now consider the use of Q-Block1 Option with a reliable 1891 transport as shown in Figure 20. There is no acknowledgment of 1892 packets at the CoAP layer, just the final result. 1894 CoAP CoAP 1895 Client Server 1896 | | 1897 +--------->| PUT /path T:0xf0 RT=10 QB1:0/1/1024 1898 +--------->| PUT /path T:0xf1 RT=10 QB1:1/1/1024 1899 +--------->| PUT /path T:0xf2 RT=10 QB1:2/1/1024 1900 +--------->| PUT /path T:0xf3 RT=10 QB1:3/0/1024 1901 |<---------+ 2.04 1902 | | 1904 Figure 20: Example of Reliable Request with Q-Block1 Option 1906 If there is likely to be the possibility of network transient losses, 1907 then the use of unreliable transport with NON should be considered. 1909 B.2. Q-Block2 Option 1911 An example of the use of Q-Block2 Option with a reliable transport is 1912 shown in Figure 21. 1914 Client Server 1915 | | 1916 +--------->| GET /path T:0xf0 O:0 QB2:0/1/1024 1917 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1918 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1919 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:2/1/1024 1920 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:3/0/1024 1921 | ... | 1922 | [[Observe triggered]] 1923 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1924 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1925 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:2/1/1024 1926 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:3/0/1024 1927 | ... | 1929 Figure 21: Example of Notifications with Q-Block2 Option 1931 If there is likely to be the possibility of network transient losses, 1932 then the use of unreliable transport with NON should be considered. 1934 Authors' Addresses 1936 Mohamed Boucadair 1937 Orange 1938 Rennes 35000 1939 France 1941 Email: mohamed.boucadair@orange.com 1943 Jon Shallow 1944 United Kingdom 1946 Email: supjps-ietf@jpshallow.com