idnits 2.17.1 draft-ietf-core-new-block-09.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 16, 2021) is 1136 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 1482, but not defined -- Looks like a reference, but probably isn't: '9' on line 1171 == Missing Reference: 'Missing 10' is mentioned on line 1181, but not defined -- Looks like a reference, but probably isn't: '2' on line 1482 == Missing Reference: 'RFCXXXX' is mentioned on line 1645, 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: September 17, 2021 March 16, 2021 7 Constrained Application Protocol (CoAP) Block-Wise Transfer Options for 8 Faster Transmission 9 draft-ietf-core-new-block-09 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 September 17, 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 . . . . . . . . . . . . . . . . 13 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 . . . . . . 16 69 3.8. Using Q-Block2 Option With Multicast . . . . . . . . . . 16 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) . . . . . . . . . . . . . . . . . . . . 18 74 6.2. Non-confirmable (NON) . . . . . . . . . . . . . . . . . . 18 75 7. Caching Considerations . . . . . . . . . . . . . . . . . . . 22 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. Security Considerations . . . . . . . . . . . . . . . . . . . 34 93 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 94 11.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 35 95 11.2. Media Type Registration . . . . . . . . . . . . . . . . 35 96 11.3. CoAP Content-Formats Registry . . . . . . . . . . . . . 36 98 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 99 12.1. Normative References . . . . . . . . . . . . . . . . . . 37 100 12.2. Informative References . . . . . . . . . . . . . . . . . 38 101 Appendix A. Examples with Confirmable Messages . . . . . . . . . 39 102 A.1. Q-Block1 Option . . . . . . . . . . . . . . . . . . . . . 39 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 44 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 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 1.1. Alternative CoAP Block-Wise Transfer Options 142 This document introduces the CoAP Q-Block1 and Q-Block2 Options. 143 These options are similar in operation to the CoAP Block1 and Block2 144 Options, respectively. They are not a replacement for them, but have 145 the following benefits: 147 o They can operate in environments where packet loss is highly 148 asymmetrical. 150 o They enable faster transmissions of sets of blocks of data with 151 less packet interchanges. 153 o They support faster recovery should any of the blocks get lost in 154 transmission. 156 o They support sending an entire body using Non-confirmable (NON) 157 messages without requiring a response from the peer. 159 There are the following disadvantages over using CoAP Block1 and 160 Block2 Options: 162 o Loss of lock-stepping so payloads are not always received in the 163 correct (block ascending) order. 165 o Additional congestion control measures need to be put in place for 166 NON messages (Section 6.2). 168 o To reduce the transmission times for CON transmission of large 169 bodies, NSTART needs to be increased from 1, but this affects 170 congestion control where other parameters need to be tuned 171 (Section 4.7 of [RFC7252]). Such tuning is out of scope of this 172 document. 174 o Mixing of NON and CON during requests/responses using Q-Block is 175 not supported. 177 o The Q-Block Options do not support stateless operation/random 178 access. 180 o Proxying of Q-Block is limited to caching full representations. 182 o There is no multicast support. 184 Q-Block1 and Q-Block2 Options are designed to work in particular with 185 NON requests and responses. 187 Using NON messages, the faster transmissions occur as all the blocks 188 can be transmitted serially (as are IP fragmented packets) without 189 having to wait for a response or next request from the remote CoAP 190 peer. Recovery of missing blocks is faster in that multiple missing 191 blocks can be requested in a single CoAP message. Even if there is 192 asymmetrical packet loss, a body can still be sent and received by 193 the peer whether the body comprises of a single or multiple payloads 194 assuming no recovery is required. 196 A CoAP endpoint can acknowledge all or a subset of the blocks. 197 Concretely, the receiving CoAP endpoint either informs the CoAP 198 sender endpoint of successful reception or reports on all blocks in 199 the body that have not yet been received. The CoAP sender endpoint 200 will then retransmit only the blocks that have been lost in 201 transmission. 203 Note that similar performance benefits can be applied to Confirmable 204 messages if the value of NSTART is increased from 1 (Section 4.7 of 205 [RFC7252]). However, the use of Confirmable messages will not work 206 if there is asymmetrical packet loss. Some examples with Confirmable 207 messages are provided in Appendix A. 209 There is little, if any, benefit of using these options with CoAP 210 running over a reliable connection [RFC8323]. In this case, there is 211 no differentiation between CON and NON as they are not used. Some 212 examples using a reliable transport are provided in Appendix B. 214 Q-Block1 and Q-Block2 Options can be used instead of Block1 and 215 Block2 Options when the different transmission properties are 216 required. If the new options are not supported by a peer, then 217 transmissions can fall back to using Block1 and Block2 Options. 219 The deviations from Block1 and Block2 Options are specified in 220 Section 3. Pointers to appropriate [RFC7959] sections are provided. 222 The specification refers to the base CoAP methods defined in 223 Section 5.8 of [RFC7252] and the new CoAP methods, FETCH, PATCH, and 224 iPATCH introduced in [RFC8132]. 226 The No-Response Option was considered but was abandoned as it does 227 not apply to Q-Block2 responses. A unified solution is defined in 228 the document. 230 1.2. CoAP Response Code (4.08) Usage 232 This document adds a media type for the 4.08 (Request Entity 233 Incomplete) response defining an additional message format for 234 reporting on payloads using the Q-Block1 Option that are not received 235 by the server. 237 See Section 4 for more details. 239 1.3. Applicability Scope 241 The block-wise transfer specified in [RFC7959] covers the general 242 case, but falls short in situations where packet loss is highly 243 asymmetrical. The mechanism specified in this document provides 244 roughly similar features to the Block1/Block2 Options. It provides 245 additional properties that are tailored towards the intended use case 246 of Non-Confirmable transmission. Concretely, this mechanism 247 primarily targets applications such as DDoS Open Threat Signaling 248 (DOTS) that cannot use CON responses to handle potential packet loss 249 and that support application-specific mechanisms to assess whether 250 the remote peer is able to handle the messages sent by a CoAP 251 endpoint (e.g., DOTS heartbeats in Section 4.7 of [RFC8782]). 253 The mechanism includes guards to prevent a CoAP agent from 254 overloading the network by adopting an aggressive sending rate. 255 These guards MUST be followed in addition to the existing CoAP 256 congestion control as specified in Section 4.7 of [RFC7252]. See 257 Section 6 for more details. 259 This mechanism is not intended for general CoAP usage, and any use 260 outside the intended use case should be carefully weighed against the 261 loss of interoperability with generic CoAP applications. It is hoped 262 that the experience gained with this mechanism can feed future 263 extensions of the block-wise mechanism that will both be generally 264 applicable and serve this particular use case. 266 It is not recommended that these options are used in a NoSec security 267 mode (Section 9 of [RFC7252]) as the source endpoint needs to be 268 trusted. Using OSCORE [RFC8613] does provide a security context and, 269 hence, a trust of the source endpoint. However, using a NoSec 270 security mode may still be inadequate for reasons discussed in 271 Section 10. 273 2. Terminology 275 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 276 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 277 "OPTIONAL" in this document are to be interpreted as described in BCP 278 14 [RFC2119][RFC8174] when, and only when, they appear in all 279 capitals, as shown here. 281 Readers should be familiar with the terms and concepts defined in 282 [RFC7252], [RFC7959], and [RFC8132]. 284 The terms "payload" and "body" are defined in [RFC7959]. The term 285 "payload" is thus used for the content of a single CoAP message 286 (i.e., a single block being transferred), while the term "body" is 287 used for the entire resource representation that is being transferred 288 in a block-wise fashion. 290 3. The Q-Block1 and Q-Block2 Options 292 3.1. Properties of Q-Block1 and Q-Block2 Options 294 The properties of the Q-Block1 and Q-Block2 Options are shown in 295 Table 1. The formatting of this table follows the one used in 296 Table 4 of [RFC7252] (Section 5.10). The C, U, N, and R columns 297 indicate the properties Critical, UnSafe, NoCacheKey, and Repeatable 298 defined in Section 5.4 of [RFC7252]. Only Critical and UnSafe 299 columns are marked for the Q-Block1 Option. Critical, UnSafe, and 300 Repeatable columns are marked for the Q-Block2 Option. As these 301 options are UnSafe, NoCacheKey has no meaning and so is marked with a 302 dash. 304 +--------+---+---+---+---+--------------+--------+--------+---------+ 305 | Number | C | U | N | R | Name | Format | Length | Default | 306 +========+===+===+===+===+==============+========+========+=========+ 307 | TBA1 | x | x | - | | Q-Block1 | uint | 0-3 | (none) | 308 | TBA2 | x | x | - | x | Q-Block2 | uint | 0-3 | (none) | 309 +--------+---+---+---+---+--------------+--------+--------+---------+ 311 Table 1: CoAP Q-Block1 and Q-Block2 Option Properties 313 The Q-Block1 and Q-Block2 Options can be present in both the request 314 and response messages. The Q-Block1 Option pertains to the request 315 payload and the Q-Block2 Option pertains to the response payload. 316 The Content-Format Option applies to the body, not to the payload 317 (i.e., it must be the same for all payloads of the same body). 319 Q-Block1 Option is useful with the payload-bearing POST, PUT, FETCH, 320 PATCH, and iPATCH requests and their responses. 322 Q-Block2 Option is useful with GET, POST, PUT, FETCH, PATCH, and 323 iPATCH requests and their payload-bearing responses (2.01, 2.02, 324 2.03, 2.04, and 2.05) (Section 5.5 of [RFC7252]). 326 A CoAP endpoint (or proxy) MUST support either both or neither of the 327 Q-Block1 and Q-Block2 Options. 329 If Q-Block1 Option is present in a request or Q-Block2 Option in a 330 response (i.e., in that message to the payload of which it pertains), 331 it indicates a block-wise transfer and describes how this specific 332 block-wise payload forms part of the entire body being transferred. 333 If it is present in the opposite direction, it provides additional 334 control on how that payload will be formed or was processed. 336 To indicate support for Q-Block2 responses, the CoAP client MUST 337 include the Q-Block2 Option in a GET or similar request, the Q-Block2 338 Option in a PUT or similar request, or the Q-Block1 Option in a PUT 339 or similar request so that the server knows that the client supports 340 this Q-Block2 functionality should it need to send back a body that 341 spans multiple payloads. Otherwise, the server would use the Block2 342 Option (if supported) to send back a message body that is too large 343 to fit into a single IP packet [RFC7959]. 345 Implementation of the Q-Block1 and Q-Block2 Options is intended to be 346 optional. However, when it is present in a CoAP message, it MUST be 347 processed (or the message rejected). Therefore, Q-Block1 and 348 Q-Block2 Options are identified as Critical options. 350 With CoAP over UDP, the way a request message is rejected for 351 critical options depends on the message type. A Confirmable message 352 with an unrecognized critical option is rejected with a 4.02 (Bad 353 Option) response (Section 5.4.1 of [RFC7252]). A Non-confirmable 354 message with an unrecognized critical option is either rejected with 355 a Reset message or just silently ignored (Sections 5.4.1 and 4.3 of 356 [RFC7252]). To reliably get a rejection message, it is therefore 357 REQUIRED that clients use a Confirmable message for determining 358 support for Q-Block1 and Q-Block2 Options. 360 The Q-Block1 and Q-Block2 Options are unsafe to forward. That is, a 361 CoAP proxy that does not understand the Q-Block1 (or Q-Block2) Option 362 MUST reject the request or response that uses either option. 364 The Q-Block2 Option is repeatable when requesting retransmission of 365 missing blocks, but not otherwise. Except that case, any request 366 carrying multiple Q-Block1 (or Q-Block2) Options MUST be handled 367 following the procedure specified in Section 5.4.5 of [RFC7252]. 369 The Q-Block1 and Q-Block2 Options, like the Block1 and Block2 370 Options, both of class E and class U for OSCORE processing (Table 2). 371 The Q-Block1 (or Q-Block2) Option MAY be an Inner or Outer option 372 (Section 4.1 of [RFC8613]). The Inner and Outer values are therefore 373 independent of each other. The Inner option is encrypted and 374 integrity protected between clients and servers, and provides message 375 body identification in case of end-to-end fragmentation of requests. 376 The Outer option is visible to proxies and labels message bodies in 377 case of hop-by-hop fragmentation of requests. 379 +--------+-----------------+---+---+ 380 | Number | Name | E | U | 381 +========+=================+===+===+ 382 | TBA1 | Q-Block1 | x | x | 383 | TBA2 | Q-Block2 | x | x | 384 +--------+-----------------+---+---+ 385 Table 2: OSCORE Protection of Q-Block1 and Q-Block2 Options 387 Note that if Q-Block1 or Q-Block2 Options are included in a packet as 388 Inner options, Block1 or Block2 Options MUST NOT be included as Inner 389 options. Similarly there MUST NOT be a mix of Q-Block and Block for 390 the Outer options. Q-Block and Block Options can be mixed across 391 Inner and Outer options as these are handled independently of each 392 other. 394 3.2. Structure of Q-Block1 and Q-Block2 Options 396 The structure of Q-Block1 and Q-Block2 Options follows the structure 397 defined in Section 2.2 of [RFC7959]. 399 There is no default value for the Q-Block1 and Q-Block2 Options. 400 Absence of one of these options is equivalent to an option value of 0 401 with respect to the value of block number (NUM) and more bit (M) that 402 could be given in the option, i.e., it indicates that the current 403 block is the first and only block of the transfer (block number is 404 set to 0, M is unset). However, in contrast to the explicit value 0, 405 which would indicate a size of the block (SZX) of 0, and thus a size 406 value of 16 bytes, there is no specific explicit size implied by the 407 absence of the option -- the size is left unspecified. (As for any 408 uint, the explicit value 0 is efficiently indicated by a zero-length 409 option; this, therefore, is different in semantics from the absence 410 of the option). 412 3.3. Using the Q-Block1 Option 414 The Q-Block1 Option is used when the client wants to send a large 415 amount of data to the server using the POST, PUT, FETCH, PATCH, or 416 iPATCH methods where the data and headers do not fit into a single 417 packet. 419 When Q-Block1 Option is used, the client MUST include a Request-Tag 420 Option [I-D.ietf-core-echo-request-tag]. The Request-Tag value MUST 421 be the same for all of the requests for the body of data that is 422 being transferred. It is also used to identify a particular payload 423 of a body that needs to be retransmitted. The Request-Tag is opaque, 424 the server still treats it as opaque but the client SHOULD ensure 425 that it is unique for every different body of transmitted data. 427 Implementation Note: It is suggested that the client treats the 428 Request-Tag as an unsigned integer of 8 bytes in length. An 429 implementation may want to consider limiting this to 4 bytes to 430 reduce packet overhead size. The initial Request-Tag value should 431 be randomly generated and then subsequently incremented by the 432 client whenever a new body of data is being transmitted between 433 peers. 435 Section 3.6 discusses the use of Size1 Option. 437 For Confirmable transmission, the server continues to acknowledge 438 each packet, but a response is not required (whether separate or 439 piggybacked) until successful receipt of the body by the server. For 440 Non-confirmable transmission, no response is required until the 441 successful receipt of the body by the server or some of the payloads 442 have not arrived after a timeout and a retransmit missing payloads 443 response is needed. For reliable transports (e.g., [RFC8323]), a 444 response is not required until successful receipt of the body by the 445 server. 447 Each individual payload of the body is treated as a new request 448 (Section 5). 450 The client MUST send the payloads with the block numbers increasing, 451 starting from zero, until the body is complete (subject to any 452 congestion control (Section 6)). Any missing payloads requested by 453 the server must in addition be separately transmitted with increasing 454 block numbers. 456 The following Response Codes are used: 458 2.01 (Created) 460 This Response Code indicates successful receipt of the entire body 461 and that the resource was created. The token used SHOULD be from 462 the last received payload. The client should then release all of 463 the tokens used for this body. 465 2.02 (Deleted) 467 This Response Code indicates successful receipt of the entire body 468 and that the resource was deleted when using POST (Section 5.8.2 469 [RFC7252]). The token used SHOULD be from the last received 470 payload. The client should then release all of the tokens used 471 for this body. 473 2.04 (Changed) 475 This Response Code indicates successful receipt of the entire body 476 and that the resource was updated. The token used SHOULD be from 477 the last received payload. The client should then release all of 478 the tokens used for this body. 480 2.05 (Content) 481 This Response Code indicates successful receipt of the entire 482 FETCH request body (Section 2 of [RFC8132]) and that the 483 appropriate representation of the resource is being returned. The 484 token used in the response SHOULD be from the last received 485 payload. 487 If the FETCH request includes the Observe Option, then the server 488 MUST use the same token as used for the initial response for 489 returning any Observe triggered responses so that the client can 490 match them up. 492 The client should then release all of the tokens used for this 493 body unless a resource is being observed. 495 2.31 (Continue) 497 This Response Code can be used to indicate that all of the blocks 498 up to and including the Q-Block1 Option block NUM (all having the 499 M bit set) have been successfully received. The token used SHOULD 500 be from the last received payload. 502 A response using this Response Code SHOULD NOT be generated for 503 every received Q-Block1 Option request. It SHOULD only be 504 generated when all the payload requests are Non-confirmable and a 505 set of MAX_PAYLOADS (Section 6.2) payloads have been received by 506 the server. 508 It SHOULD NOT be generated for CON. 510 4.00 (Bad Request) 512 This Response Code MUST be returned if the request does not 513 include neither a Request-Tag Option nor a Size1 Option but does 514 include a Q-Block1 option. 516 4.02 (Bad Option) 518 Either this Response Code (in case of Confirmable request) or a 519 reset message (in case of Non-confirmable request) MUST be 520 returned if the server does not support the Q-Block Options. 522 4.08 (Request Entity Incomplete) 524 This Response Code returned without Content-Type "application/ 525 missing-blocks+cbor-seq" (Section 11.3) is handled as in 526 Section 2.9.2 [RFC7959]. 528 This Response Code returned with Content-Type "application/ 529 missing-blocks+cbor-seq" indicates that some of the payloads are 530 missing and need to be resent. The client then retransmits the 531 missing payloads using the same Request-Tag, Size1 and Q-Block1 to 532 specify the block NUM, SZX, and M bit as appropriate. 534 The Request-Tag value to use is determined by taking the token in 535 the 4.08 (Request Entity Incomplete) response, locating the 536 matching client request, and then using its Request-Tag. 538 The token used in the response SHOULD be from the last received 539 payload. See Section 4 for further information. 541 If the server has not received all the payloads of a body, but one 542 or more NON payloads have been received, it SHOULD wait for up to 543 NON_RECEIVE_TIMEOUT (Section 6.2) before sending a 4.08 (Request 544 Entity Incomplete) response. 546 4.13 (Request Entity Too Large) 548 This Response Code can be returned under similar conditions to 549 those discussed in Section 2.9.3 of [RFC7959]. 551 This Response Code can be returned if there is insufficient space 552 to create a response PDU with a block size of 16 bytes (SZX = 0) 553 to send back all the response options as appropriate. In this 554 case, the Size1 Option is not included in the response. 556 Further considerations related to the transmission timings of 4.08 557 (Request Entity Incomplete) and 2.31 (Continue) Response Codes are 558 discussed in Section 6.2. 560 If a server receives payloads with different Request-Tags for the 561 same resource, it should continue to process all the bodies as it has 562 no way of determining which is the latest version, or which body, if 563 any, the client is terminating the transmission for. 565 If the client elects to stop the transmission of a complete body, it 566 SHOULD "forget" all tracked tokens associated with the body's 567 Request-Tag so that a reset message is generated for the invalid 568 token in the 4.08 (Request Entity Incomplete) response. The server 569 on receipt of the reset message SHOULD delete the partial body. 571 If the server receives a duplicate block with the same Request-Tag, 572 it SHOULD ignore the payload of the packet, but MUST still respond as 573 if the block was received for the first time. 575 A server SHOULD only maintain a partial body (missing payloads) for 576 up to NON_PARTIAL_TIMEOUT (Section 6.2). 578 3.4. Using the Q-Block2 Option 580 In a request for any block number, the M bit unset indicates the 581 request is just for that block. If the M bit is set, this has 582 different meanings based on the NUM value: 584 NUM is zero: This is a request for the entire body. 586 'NUM modulo MAX_PAYLOADS' is zero, while NUM is not zero: This is 587 used to confirm that the current set of MAX_PAYLOADS payloads (the 588 latest one having block number NUM-1) has been successfully 589 received and that, upon receipt of this request, the server can 590 continue to send the next set of payloads (the first one having 591 block number NUM). This is the 'Continue' Q-Block-2 and 592 conceptually has the same usage (i.e., continue sending the next 593 set of data) as the use of 2.31 (Continue) for Q-Block1. 595 Any other value of NUM: This is a request for that block and for all 596 of the remaining blocks in the current MAX_PAYLOADS set. 598 If the request includes multiple Q-Block2 Options and these options 599 overlap (e.g., combination of M being set (this and later blocks) and 600 being unset (this individual block)) resulting in an individual block 601 being requested multiple times, the server MUST only send back one 602 instance of that block. This behavior is meant to prevent 603 amplification attacks. 605 The payloads sent back from the server as a response MUST all have 606 the same ETag (Section 5.10.6 of [RFC7252]) for the same body. The 607 server MUST NOT use the same ETag value for different representations 608 of a resource. 610 The ETag is opaque, the client still treats it as opaque but the 611 server SHOULD ensure that it is unique for every different body of 612 transmitted data. 614 Implementation Note: It is suggested that the server treats the 615 ETag as an unsigned integer of 8 bytes in length. An 616 implementation may want to consider limiting this to 4 bytes to 617 reduce packet overhead size. The initial ETag value should be 618 randomly generated and then subsequently incremented by the server 619 whenever a new body of data is being transmitted between peers. 621 Section 3.6 discusses the use of Size2 Option. 623 The client may elect to request any detected missing blocks or just 624 ignore the partial body. This decision is implementation specific. 626 The client SHOULD wait for up to NON_RECEIVE_TIMEOUT (Section 6.2) 627 after the last received payload for NON payloads before issuing a 628 GET, POST, PUT, FETCH, PATCH, or iPATCH request that contains one or 629 more Q-Block2 Options that define the missing blocks with the M bit 630 unset. It is permissible to set the M bit to request this and 631 missing blocks from this MAX_PAYLOADS set. Further considerations 632 related to the transmission timing for missing requests are discussed 633 in Section 6.2. 635 The requested missing block numbers MUST have an increasing block 636 number in each additional Q-Block2 Option with no duplicates. The 637 server SHOULD respond with a 4.00 (Bad Request) to requests not 638 adhering to this behavior. 640 For Confirmable responses, the client continues to acknowledge each 641 packet. The server acknowledges the initial request using an ACK 642 with the payload, and then sends the subsequent payloads as CON 643 responses. The server will detect failure to send a packet, but the 644 client can issue, after a MAX_TRANSMIT_SPAN delay, a separate GET, 645 POST, PUT, FETCH, PATCH, or iPATCH for any missing blocks as needed. 647 If the client receives a duplicate block with the same ETag, it 648 SHOULD silently ignore the packet. 650 A client SHOULD only maintain a partial body (missing payloads) for 651 up to NON_PARTIAL_TIMEOUT (Section 6.2) or as defined by the Max-Age 652 Option (or its default of 60 seconds (Section 5.6.1 of [RFC7252])), 653 whichever is the less. On release of the partial body, the client 654 should then release all of the tokens used for this body unless a 655 resource is being observed. 657 The ETag Option should not be used in the request for missing blocks 658 as the server could respond with a 2.03 (Valid) response with no 659 payload. It can be used in the request if the client wants to check 660 the freshness of the locally cached body response. 662 It is RECOMMENDED that the server maintains a cached copy of the body 663 when using the Q-Block2 Option to facilitate retransmission of any 664 missing payloads. 666 If the server detects part way through a body transfer that the 667 resource data has changed and the server is not maintaining a cached 668 copy of the old data, then the transmission is terminated. Any 669 subsequent missing block requests MUST be responded to using the 670 latest ETag and Size2 Option values with the updated data. 672 If the server responds during a body update with a different ETag 673 Option value (as the resource representation has changed), then the 674 client should treat the partial body with the old ETag as no longer 675 being fresh. 677 If the server transmits a new body of data (e.g., a triggered Observe 678 notification) with a new ETag to the same client as an additional 679 response, the client should remove any partially received body held 680 for a previous ETag for that resource as it is unlikely the missing 681 blocks can be retrieved. 683 If there is insufficient space to create a response PDU with a block 684 size of 16 bytes (SZX = 0) to send back all the response options as 685 appropriate, a 4.13 (Request Entity Too Large) is returned without 686 the Size1 Option. 688 3.5. Using Observe Option 690 For a request that uses Q-Block1, the Observe value [RFC7641] MUST be 691 the same for all the payloads of the same body. This includes any 692 missing payloads that are retransmitted. 694 For a response that uses Q-Block2, the Observe value MUST be the same 695 for all the payloads of the same body. This includes payloads 696 transmitted following receipt of the 'Continue' Q-Block2 Option 697 (Section 3.4) by the server. If a missing payload is requested, then 698 both the request and response MUST NOT include the Observe Option. 700 3.6. Using Size1 and Size2 Options 702 Section 4 of [RFC7959] defines two CoAP options: Size1 for indicating 703 the size of the representation transferred in requests and Size2 for 704 indicating the size of the representation transferred in responses. 706 The Size1 or Size2 option values MUST exactly represent the size of 707 the data on the body so that any missing data can easily be 708 determined. 710 The Size1 Option MUST be used with the Q-Block1 Option when used in a 711 request and MUST be present in all payloads of the request preserving 712 the same value. The Size2 Option MUST be used with the Q-Block2 713 Option when used in a response and MUST be present in all payloads of 714 the response preserving the same value. 716 3.7. Using Q-Block1 and Q-Block2 Options Together 718 The behavior is similar to the one defined in Section 3.3 of 719 [RFC7959] with Q-Block1 substituted for Block1 and Q-Block2 for 720 Block2. 722 3.8. Using Q-Block2 Option With Multicast 724 Servers MUST ignore multicast requests that contain the Q-Block2 725 Option. As a reminder, Block2 Option can be used as stated in 726 Section 2.8 of [RFC7959]. 728 4. The Use of 4.08 (Request Entity Incomplete) Response Code 730 4.08 (Request Entity Incomplete) Response Code has a new Content-Type 731 "application/missing-blocks+cbor-seq" used to indicate that the 732 server has not received all of the blocks of the request body that it 733 needs to proceed. 735 Likely causes are the client has not sent all blocks, some blocks 736 were dropped during transmission, or the client has sent them 737 sufficiently long ago that the server has already discarded them. 739 The data payload of the 4.08 (Request Entity Incomplete) response is 740 encoded as a CBOR Sequence [RFC8742]. It comprises of one or more 741 CBOR encoded [RFC8949] missing block numbers. The missing block 742 numbers MUST be unique in each 4.08 (Request Entity Incomplete) 743 response when created by the server; the client SHOULD drop any 744 duplicates in the same 4.08 (Request Entity Incomplete) response. 746 The Content-Format Option (Section 5.10.3 of [RFC7252]) MUST be used 747 in the 4.08 (Request Entity Incomplete) response. It MUST be set to 748 "application/missing-blocks+cbor-seq" (Section 11.3). 750 The Concise Data Definition Language [RFC8610] (and see Section 4.1 751 [RFC8742]) for the data describing these missing blocks is as 752 follows: 754 ; A notional array, the elements of which are to be used 755 ; in a CBOR Sequence: 756 payload = [+ missing-block-number] 757 ; A unique block number not received: 758 missing-block-number = uint 760 Figure 1: Structure of the Missing Blocks Payload 762 The token to use for the response SHOULD be the token that was used 763 in the last block number received so far with the same Request-Tag 764 value. Note that the use of any received token with the same 765 Request-Tag would work, but providing the one used in the last 766 received payload will aid any troubleshooting. The client will use 767 the token to determine what was the previously sent request to obtain 768 the Request-Tag value to be used. 770 If the size of the 4.08 (Request Entity Incomplete) response packet 771 is larger than that defined by Section 4.6 [RFC7252], then the number 772 of missing blocks MUST be limited so that the response can fit into a 773 single packet. If this is the case, then the server can send 774 subsequent 4.08 (Request Entity Incomplete) responses containing the 775 missing other blocks on receipt of a new request providing a missing 776 payload with the same Request-Tag. 778 The missing blocks MUST be reported in ascending order without any 779 duplicates. The client SHOULD silently drop 4.08 (Request Entity 780 Incomplete) responses not adhering with this behavior. 782 Implementation Note: Consider limiting the number of missing 783 payloads to MAX_PAYLOADS to minimize congestion control being 784 needed. The CBOR sequence does not include any array wrapper. 786 The 4.08 (Request Entity Incomplete) with Content-Type "application/ 787 missing-blocks+cbor-seq" SHOULD NOT be used when using Confirmable 788 requests or a reliable connection [RFC8323] as the client will be 789 able to determine that there is a transmission failure of a 790 particular payload and hence that the server is missing that payload. 792 5. The Use of Tokens 794 Each new request generally uses a new Token (and sometimes must, see 795 Section 4 of [I-D.ietf-core-echo-request-tag]). Additional responses 796 to a request all use the token of the request they respond to. 798 Implementation Note: To minimize on the number of tokens that have 799 to be tracked by clients, it is suggested that the bottom 32 bits 800 is kept the same for the same body and the upper 32 bits contains 801 the current body's request number (incrementing every request, 802 including every re-transmit). This allows the client to be 803 alleviated from keeping all the per-request-state, e.g., in 804 Section 3 of [RFC8974]. 806 6. Congestion Control for Unreliable Transports 808 The transmission of the payloads of a body over an unreliable 809 transport SHOULD either all be Confirmable or all be Non-confirmable. 810 This is meant to simplify the congestion control procedure. 812 As a reminder, there is no need for CoAP-specific congestion control 813 for reliable transports [RFC8323]. 815 6.1. Confirmable (CON) 817 Congestion control for CON requests and responses is specified in 818 Section 4.7 of [RFC7252]. For faster transmission rates, NSTART will 819 need to be increased from 1. However, the other CON congestion 820 control parameters will need to be tuned to cover this change. This 821 tuning is out of scope of this document as it is expected that all 822 requests and responses using Q-Block1 and Q-Block2 will be Non- 823 confirmable. 825 It is implementation specific as to whether there should be any 826 further requests for missing data as there will have been significant 827 transmission failure as individual payloads will have failed after 828 MAX_TRANSMIT_SPAN. 830 6.2. Non-confirmable (NON) 832 This document introduces new parameters MAX_PAYLOADS, NON_TIMEOUT, 833 NON_RECEIVE_TIMEOUT, NON_MAX_RETRANSMIT, NON_PROBING_WAIT, and 834 NON_PARTIAL_TIMEOUT primarily for use with NON (Table 3). 836 MAX_PAYLOADS should be configurable with a default value of 10. Both 837 CoAP endpoints SHOULD have the same value (otherwise there will be 838 transmission delays in one direction) and the value MAY be negotiated 839 between the endpoints to a common value by using a higher level 840 protocol (out of scope of this document). This is the maximum number 841 of payloads that can be transmitted at any one time. 843 Note: The default value of 10 is chosen for reasons similar to 844 those discussed in Section 5 of [RFC6928]. 846 NON_TIMEOUT is the maximum period of delay between sending sets of 847 MAX_PAYLOADS payloads for the same body. By default, NON_TIMEOUT has 848 the same value as ACK_TIMEOUT (Section 4.8 of [RFC7252]). 850 NON_RECEIVE_TIMEOUT is the initial maximum time to wait for a missing 851 payload before requesting retransmission for the first time. Every 852 time the missing payload is re-requested, the time to wait value 853 doubles. The time to wait is calculated as: 855 Time-to-Wait = NON_RECEIVE_TIMEOUT * (2 ** (Re-Request-Count - 1)) 857 NON_RECEIVE_TIMEOUT has a default value of twice NON_TIMEOUT. 858 NON_RECEIVE_TIMEOUT MUST always be greater than NON_TIMEOUT by at 859 least one second so that the sender of the payloads has the 860 opportunity to start sending the next set of payloads before the 861 receiver times out. 863 NON_MAX_RETRANSMIT is the maximum number of times a request for the 864 retransmission of missing payloads can occur without a response from 865 the remote peer. After this occurs, the local endpoint SHOULD 866 consider the body stale, remove any body, and release Tokens and 867 Request-Tag on the client (or the ETag on the server). By default, 868 NON_MAX_RETRANSMIT has the same value as MAX_RETRANSMIT (Section 4.8 869 of [RFC7252]). 871 NON_PROBING_WAIT is used to limit the potential wait needed 872 calculated when using PROBING_WAIT. NON_PROBING_WAIT has the same 873 value as computed for EXCHANGE_LIFETIME (Section 4.8.2 of [RFC7252]). 875 NON_PARTIAL_TIMEOUT is used for expiring partially received bodies. 876 NON_PARTIAL_TIMEOUT has the same value as computed for 877 EXCHANGE_LIFETIME (Section 4.8.2 of [RFC7252]). 879 +---------------------+---------------+ 880 | Parameter Name | Default Value | 881 +=====================+===============| 882 | MAX_PAYLOADS | 10 | 883 | NON_MAX_RETRANSMIT | 4 | 884 | NON_TIMEOUT | 2 s | 885 | NON_RECEIVE_TIMEOUT | 4 s | 886 | NON_PROBING_WAIT | 247 s | 887 | NON_PARTIAL_TIMEOUT | 247 s | 888 +---------------------+---------------+ 890 Table 3: Congestion Control Parameters 892 PROBING_RATE parameter in CoAP indicates the average data rate that 893 must not be exceeded by a CoAP endpoint in sending to a peer endpoint 894 that does not respond. The single body of blocks will be subjected 895 to PROBING_RATE (Section 4.7 of [RFC7252]), not the individual 896 packets. If the wait time between sending bodies that are not being 897 responded to based on PROBING_RATE exceeds NON_PROBING_WAIT, then the 898 gap time is limited to NON_PROBING_WAIT. 900 Note: For the particular DOTS application, PROBING_RATE and other 901 transmission parameters are negotiated between peers. Even when 902 not negotiated, the DOTS application uses customized defaults as 903 discussed in Section 4.5.2 of [RFC8782]. Note that MAX_PAYLOADS, 904 NON_MAX_RETRANSMIT, and NON_TIMEOUT can be negotiated between DOTS 905 peers as per [I-D.bosh-dots-quick-blocks]. 907 Each NON 4.08 (Request Entity Incomplete) response is subject to 908 PROBING_RATE. 910 Each NON GET or FETCH request using Q-Block2 Option is subject to 911 PROBING_RATE. 913 As the sending of many payloads of a single body may itself cause 914 congestion, it is RECOMMENDED that after transmission of every set of 915 MAX_PAYLOADS payloads of a single body, a delay is introduced of 916 NON_TIMEOUT before sending the next set of payloads to manage 917 potential congestion issues. 919 If the CoAP peer reports at least one payload has not arrived for 920 each body for at least a 24 hour period and it is known that there 921 are no other network issues over that period, then the value of 922 MAX_PAYLOADS can be reduced by 1 at a time (to a minimum of 1) and 923 the situation re-evaluated for another 24 hour period until there is 924 no report of missing payloads under normal operating conditions. The 925 newly derived value for MAX_PAYLOADS should be used for both ends of 926 this particular CoAP peer link. Note that the CoAP peer will not 927 know about the MAX_PAYLOADS change until it is reconfigured. As a 928 consequence of the two peers having different MAX_PAYLOADS values, a 929 peer may continue indicate that there are some missing payloads as 930 all of its MAX_PAYLOADS set may not have arrived. How the two peer 931 values for MAX_PAYLOADS are synchronized is out of the scope. 933 The sending of a set of missing payloads of a body is subject to 934 MAX_PAYLOADS set of payloads. 936 For Q-Block1 Option, if the server responds with a 2.31 (Continue) 937 Response Code for the latest payload sent, then the client can 938 continue to send the next set of payloads without any delay. If the 939 server responds with a 4.08 (Request Entity Incomplete) Response 940 Code, then the missing payloads SHOULD be retransmitted before going 941 into another NON_TIMEOUT delay prior to sending the next set of 942 payloads. 944 For the server receiving NON Q-Block1 requests, it SHOULD send back a 945 2.31 (Continue) Response Code on receipt of all of the MAX_PAYLOADS 946 payloads to prevent the client unnecessarily delaying. Otherwise the 947 server SHOULD delay for NON_RECEIVE_TIMEOUT (exponentially scaled 948 based on the repeat request count for a payload), before sending the 949 4.08 (Request Entity Incomplete) Response Code for the missing 950 payload(s). If this is a repeat for the 2.31 (Continue) response, 951 the server SHOULD send a 4.08 (Request Entity Incomplete) response 952 detailing the missing payloads after the block number that would have 953 been indicated in the 2.31 (Continue). If the repeat request count 954 for a missing payload exceeds NON_MAX_RETRANSMIT, the server SHOULD 955 discard the partial body and stop requesting the missing payloads. 957 It is likely that the client will start transmitting the next set of 958 MAX_PAYLOADS payloads before the server times out on waiting for the 959 last of the previous MAX_PAYLOADS payloads. On receipt of the first 960 received payload from the new set of MAX_PAYLOADS payloads, the 961 server SHOULD send a 4.08 (Request Entity Incomplete) Response Code 962 indicating any missing payloads from any previous MAX_PAYLOADS 963 payloads. Upon receipt of the 4.08 (Request Entity Incomplete) 964 Response Code, the client SHOULD send the missing payloads before 965 continuing to send the remainder of the MAX_PAYLOADS payloads and 966 then go into another NON_TIMEOUT delay prior to sending the next set 967 of payloads. 969 For the client receiving NON Q-Block2 responses, it SHOULD send a 970 'Continue' Q-Block2 request (Section 3.4) for the next set of 971 payloads on receipt of all of the MAX_PAYLOADS payloads to prevent 972 the server unnecessarily delaying. Otherwise the client SHOULD delay 973 for NON_RECEIVE_TIMEOUT (exponentially scaled based on the repeat 974 request count for a payload), before sending the request for the 975 missing payload(s). If the repeat request count for a missing 976 payload exceeds NON_MAX_RETRANSMIT, the client SHOULD discard the 977 partial body and stop requesting the missing payloads. 979 The server SHOULD recognize the 'Continue' Q-Block2 request as a 980 continue request and just continue the transmission of the body 981 (including Observe Option, if appropriate for an unsolicited 982 response) rather than as a request for the remaining missing blocks. 984 It is likely that the server will start transmitting the next set of 985 MAX_PAYLOADS payloads before the client times out on waiting for the 986 last of the previous MAX_PAYLOADS payloads. Upon receipt of the 987 first payload from the new set of MAX_PAYLOADS payloads, the client 988 SHOULD send a request indicating any missing payloads from any 989 previous set of MAX_PAYLOADS payloads. Upon receipt of such request, 990 the server SHOULD send the missing payloads before continuing to send 991 the remainder of the MAX_PAYLOADS payloads and then go into another 992 NON_TIMEOUT delay prior to sending the next set of payloads. 994 The client does not need to acknowledge the receipt of the entire 995 body. 997 Note: If there is asymmetric traffic loss causing responses to 998 never get received, a delay of NON_TIMEOUT after every 999 transmission of MAX_PAYLOADS blocks will be observed. The 1000 endpoint receiving the body is still likely to receive the entire 1001 body. 1003 7. Caching Considerations 1005 Caching block based information is not straight forward in a proxy. 1006 For Q-Block1 and Q-Block2 Options, for simplicity it is expected that 1007 the proxy will reassemble the body (using any appropriate recovery 1008 options for packet loss) before passing on the body to the 1009 appropriate CoAP endpoint. This does not preclude an implementation 1010 doing a more complex per payload caching, but how to do this is out 1011 of the scope of this document. The onward transmission of the body 1012 does not require the use of the Q-Block1 or Q-Block2 Options as these 1013 options may not be supported in that link. This means that the proxy 1014 must fully support the Q-Block1 and Q-Block2 Options. 1016 How the body is cached in the CoAP client (for Q-Block1 1017 transmissions) or the CoAP server (for Q-Block2 transmissions) is 1018 implementation specific. 1020 As the entire body is being cached in the proxy, the Q-Block1 and 1021 Q-Block2 Options are removed as part of the block assembly and thus 1022 do not reach the cache. 1024 For Q-Block2 responses, the ETag Option value is associated with the 1025 data (and onward transmitted to the CoAP client), but is not part of 1026 the cache key. 1028 For requests with Q-Block1 Option, the Request-Tag Option is 1029 associated with the build up of the body from successive payloads, 1030 but is not part of the cache key. For the onward transmission of the 1031 body using CoAP, a new Request-Tag SHOULD be generated and used. 1032 Ideally this new Request-Tag should replace the client's request 1033 Request-Tag. 1035 It is possible that two or more CoAP clients are concurrently 1036 updating the same resource through a common proxy to the same CoAP 1037 server using Q-Block1 (or Block1) Option. If this is the case, the 1038 first client to complete building the body causes that body to start 1039 transmitting to the CoAP server with an appropriate Request-Tag 1040 value. When the next client completes building the body, any 1041 existing partial body transmission to the CoAP server is terminated 1042 and the new body representation transmission starts with a new 1043 Request-Tag value. Note that it cannot be assumed that the proxy 1044 will always receive a complete body from a client. 1046 A proxy that supports Q-Block2 Option MUST be prepared to receive a 1047 GET or similar request indicating one or more missing blocks. The 1048 proxy will serve from its cache the missing blocks that are available 1049 in its cache in the same way a server would send all the appropriate 1050 Q-Block2 responses. If the cache key matching body is not available 1051 in the cache, the proxy MUST request the entire body from the CoAP 1052 server using the information in the cache key. 1054 How long a CoAP endpoint (or proxy) keeps the body in its cache is 1055 implementation specific (e.g., it may be based on Max-Age). 1057 8. HTTP-Mapping Considerations 1059 As a reminder, the basic normative requirements on HTTP/CoAP mappings 1060 are defined in Section 10 of [RFC7252]. The implementation 1061 guidelines for HTTP/CoAP mappings are elaborated in [RFC8075]. 1063 The rules defined in Section 5 of [RFC7959] are to be followed. 1065 9. Examples with Non-confirmable Messages 1067 This section provides some sample flows to illustrate the use of 1068 Q-Block1 and Q-Block2 Options with NON. Examples with CON are 1069 provided in Appendix A. 1071 The examples in the following subsections assume MAX_PAYLOADS is set 1072 to 10 and NON_MAX_RETRANSMIT is set to 4. 1074 Figure 2 lists the conventions that are used in the following 1075 subsections. 1077 T: Token value 1078 O: Observe Option value 1079 M: Message ID 1080 RT: Request-Tag 1081 ET: ETag 1082 QB1: Q-Block1 Option values NUM/More/SZX 1083 QB2: Q-Block2 Option values NUM/More/SZX 1084 \: Trimming long lines 1085 [[]]: Comments 1086 -->X: Message loss (request) 1087 X<--: Message loss (response) 1088 ...: Passage of time 1090 Figure 2: Notations Used in the Figures 1092 9.1. Q-Block1 Option 1094 9.1.1. A Simple Example 1096 Figure 3 depicts an example of a NON PUT request conveying Q-Block1 1097 Option. All the blocks are received by the server. 1099 CoAP CoAP 1100 Client Server 1101 | | 1102 +--------->| NON PUT /path M:0x81 T:0xc0 RT=9 QB1:0/1/1024 1103 +--------->| NON PUT /path M:0x82 T:0xc1 RT=9 QB1:1/1/1024 1104 +--------->| NON PUT /path M:0x83 T:0xc2 RT=9 QB1:2/1/1024 1105 +--------->| NON PUT /path M:0x84 T:0xc3 RT=9 QB1:3/0/1024 1106 |<---------+ NON 2.04 M:0xf1 T:0xc3 1107 | ... | 1109 Figure 3: Example of NON Request with Q-Block1 Option (Without Loss) 1111 9.1.2. Handling MAX_PAYLOADS Limits 1113 Figure 4 depicts an example of a NON PUT request conveying Q-Block1 1114 Option. The number of payloads exceeds MAX_PAYLOADS. All the blocks 1115 are received by the server. 1117 CoAP CoAP 1118 Client Server 1119 | | 1120 +--------->| NON PUT /path M:0x01 T:0xf1 RT=10 QB1:0/1/1024 1121 +--------->| NON PUT /path M:0x02 T:0xf2 RT=10 QB1:1/1/1024 1122 +--------->| [[Payloads 3 - 9 not detailed]] 1123 +--------->| NON PUT /path M:0x0a T:0xfa RT=10 QB1:9/1/1024 1124 [[MAX_PAYLOADS has been reached]] 1125 | [[MAX_PAYLOADS blocks receipt acknowledged by server]] 1126 |<---------+ NON 2.31 M:0x81 T:0xfa 1127 +--------->| NON PUT /path M:0x0b T:0xfb RT=10 QB1:10/0/1024 1128 |<---------+ NON 2.04 M:0x82 T:0xfb 1129 | ... | 1131 Figure 4: Example of MAX_PAYLOADS NON Request with Q-Block1 Option 1132 (Without Loss) 1134 9.1.3. Handling MAX_PAYLOADS with Recovery 1136 Consider now a scenario where a new body of data is to be sent by the 1137 client, but some blocks are dropped in transmission as illustrated in 1138 Figure 5. 1140 CoAP CoAP 1141 Client Server 1142 | | 1143 +--------->| NON PUT /path M:0x11 T:0xe1 RT=11 QB1:0/1/1024 1144 +--->X | NON PUT /path M:0x12 T:0xe2 RT=11 QB1:1/1/1024 1145 +--------->| [[Payloads 3 - 8 not detailed]] 1146 +--------->| NON PUT /path M:0x19 T:0xe9 RT=11 QB1:8/1/1024 1147 +--->X | NON PUT /path M:0x1a T:0xea RT=11 QB1:9/1/1024 1148 [[MAX_PAYLOADS has been reached]] 1149 | ... | 1150 [[NON_TIMEOUT (client) delay expires]] 1151 | [[Client starts sending next set of payloads]] 1152 +--->X | NON PUT /path M:0x1b T:0xeb RT=11 QB1:10/1/1024 1153 +--------->| NON PUT /path M:0x1c T:0xec RT=11 QB1:11/1/1024 1154 | | 1156 Figure 5: Example of MAX_PAYLOADS NON Request with Q-Block1 Option 1157 (With Loss) 1159 On seeing a payload from the next set of payloads, the server 1160 realizes that some blocks are missing from the previous MAX_PAYLOADS 1161 payloads and asks for the missing blocks in one go (Figure 6). It 1162 does so by indicating which blocks from the previous MAX_PAYLOADS 1163 payloads have not been received in the data portion of the response. 1164 The token used in the response should be the token that was used in 1165 the last received payload. The client can then derive the Request- 1166 Tag by matching the token with the sent request. 1168 CoAP CoAP 1169 Client Server 1170 | | 1171 |<---------+ NON 4.08 M:0x91 T:0xec [Missing 1,9] 1172 | [[Client responds with missing payloads]] 1173 +--------->| NON PUT /path M:0x1d T:0xed RT=11 QB1:1/1/1024 1174 +--------->| NON PUT /path M:0x1e T:0xee RT=11 QB1:9/1/1024 1175 | [[Client continues sending next set of payloads]] 1176 +--------->| NON PUT /path M:0x1f T:0xef RT=11 QB1:12/0/1024 1177 | ... | 1178 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1179 | [[The server realizes a block is still missing and asks 1180 | for the missing one]] 1181 |<---------+ NON 4.08 M:0x92 T:0xef [Missing 10] 1182 +--------->| NON PUT /path M:0x20 T:0xf0 RT=11 QB1:10/1/1024 1183 |<---------+ NON 2.04 M:0x93 T:0xf0 1184 | ... | 1186 Figure 6: Example of NON Request with Q-Block1 Option (Blocks 1187 Recovery) 1189 9.1.4. Handling Recovery with Failure 1191 Figure 7 depicts an example of a NON PUT request conveying Q-Block1 1192 Option where recovery takes place, but eventually fails. 1194 CoAP CoAP 1195 Client Server 1196 | | 1197 +--------->| NON PUT /path M:0x91 T:0xd0 RT=12 QB1:0/1/1024 1198 +--->X | NON PUT /path M:0x92 T:0xd1 RT=12 QB1:1/1/1024 1199 +--------->| NON PUT /path M:0x93 T:0xd2 RT=12 QB1:2/0/1024 1200 | ... | 1201 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1202 | [[The server realizes a block is missing and asks 1203 | for the missing one. Retry #1]] 1204 |<---------+ NON 4.08 M:0x01 T:0xd2 [Missing 1] 1205 | ... | 1206 [[2 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1207 | [[The server realizes a block is still missing and asks 1208 | for the missing one. Retry #2]] 1209 |<---------+ NON 4.08 M:0x02 T:0xd2 [Missing 1] 1210 | ... | 1211 [[4 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1212 | [[The server realizes a block is still missing and asks 1213 | for the missing one. Retry #3]] 1214 |<---------+ NON 4.08 M:0x03 T:0xd2 [Missing 1] 1215 | ... | 1216 [[8 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1217 | [[The server realizes a block is still missing and asks 1218 | for the missing one. Retry #4]] 1219 |<---------+ NON 4.08 M:0x04 T:0xd2 [Missing 1] 1220 | ... | 1221 [[16 * NON_RECEIVE_TIMEOUT (server) delay expires]] 1222 | [[NON_MAX_RETRANSMIT exceeded. Server stops requesting 1223 | for missing blocks and releases partial body]] 1224 | ... | 1226 Figure 7: Example of NON Request with Q-Block1 Option (With Eventual 1227 Failure) 1229 9.2. Q-Block2 Option 1231 These examples include the Observe Option to demonstrate how that 1232 option is used. Note that the Observe Option is not required for 1233 Q-Block2; the observe detail can thus be ignored. 1235 9.2.1. A Simple Example 1237 Figure 8 illustrates the example of Q-Block2 Option. The client 1238 sends a NON GET carrying Observe and Q-Block2 Options. The Q-Block2 1239 Option indicates a block size hint (1024 bytes). This request is 1240 replied to by the server using four (4) blocks that are transmitted 1241 to the client without any loss. Each of these blocks carries a 1242 Q-Block2 Option. The same process is repeated when an Observe is 1243 triggered, but no loss is experienced by any of the notification 1244 blocks. 1246 CoAP CoAP 1247 Client Server 1248 | | 1249 +--------->| NON GET /path M:0x01 T:0xc0 O:0 QB2:0/1/1024 1250 |<---------+ NON 2.05 M:0xf1 T:0xc0 O:1220 ET=19 QB2:0/1/1024 1251 |<---------+ NON 2.05 M:0xf2 T:0xc0 O:1220 ET=19 QB2:1/1/1024 1252 |<---------+ NON 2.05 M:0xf3 T:0xc0 O:1220 ET=19 QB2:2/1/1024 1253 |<---------+ NON 2.05 M:0xf4 T:0xc0 O:1220 ET=19 QB2:3/0/1024 1254 | ... | 1255 | [[Observe triggered]] 1256 |<---------+ NON 2.05 M:0xf5 T:0xc0 O:1221 ET=20 QB2:0/1/1024 1257 |<---------+ NON 2.05 M:0xf6 T:0xc0 O:1221 ET=20 QB2:1/1/1024 1258 |<---------+ NON 2.05 M:0xf7 T:0xc0 O:1221 ET=20 QB2:2/1/1024 1259 |<---------+ NON 2.05 M:0xf8 T:0xc0 O:1221 ET=20 QB2:3/0/1024 1260 | ... | 1262 Figure 8: Example of NON Notifications with Q-Block2 Option (Without 1263 Loss) 1265 9.2.2. Handling MAX_PAYLOADS Limits 1267 Figure 9 illustrates the same as Figure 8 but this time has eleven 1268 (11) payloads which exceeds MAX_PAYLOADS. There is no loss 1269 experienced. 1271 CoAP CoAP 1272 Client Server 1273 | | 1274 +--------->| NON GET /path M:0x01 T:0xf0 O:0 QB2:0/1/1024 1275 |<---------+ NON 2.05 M:0x81 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1276 |<---------+ NON 2.05 M:0x82 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1277 |<---------+ [[Payloads 3 - 9 not detailed]] 1278 |<---------+ NON 2.05 M:0x8a T:0xf0 O:1234 ET=21 QB2:9/1/1024 1279 [[MAX_PAYLOADS has been reached]] 1280 | [[MAX_PAYLOADS blocks acknowledged by client using 1281 | 'Continue' Q-Block2]] 1282 +--------->| NON GET /path M:0x02 T:0xf1 QB2:10/1/1024 1283 |<---------+ NON 2.05 M:0x8b T:0xf0 O:1234 ET=21 QB2:10/0/1024 1284 | ... | 1285 | [[Observe triggered]] 1286 |<---------+ NON 2.05 M:0x91 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1287 |<---------+ NON 2.05 M:0x92 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1288 |<---------+ [[Payloads 3 - 9 not detailed]] 1289 |<---------+ NON 2.05 M:0x9a T:0xf0 O:1235 ET=22 QB2:9/1/1024 1290 [[MAX_PAYLOADS has been reached]] 1291 | [[MAX_PAYLOADS blocks acknowledged by client using 1292 | 'Continue' Q-Block2]] 1293 +--------->| NON GET /path M:0x03 T:0xf2 QB2:10/1/1024 1294 |<---------+ NON 2.05 M:0x9b T:0xf0 O:1235 ET=22 QB2:10/0/1024 1295 [[Body has been received]] 1296 | ... | 1298 Figure 9: Example of NON Notifications with Q-Block2 Option (Without 1299 Loss) 1301 9.2.3. Handling MAX_PAYLOADS with Recovery 1303 Figure 10 shows the example of an Observe that is triggered but for 1304 which some notification blocks are lost. The client detects the 1305 missing blocks and requests their retransmission. It does so by 1306 indicating the blocks that are missing as one or more Q-Block2 1307 Options. 1309 CoAP CoAP 1310 Client Server 1311 | ... | 1312 | [[Observe triggered]] 1313 |<---------+ NON 2.05 M:0xa1 T:0xf0 O:1236 ET=23 QB2:0/1/1024 1314 | X<---+ NON 2.05 M:0xa2 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1315 |<---------+ [[Payloads 3 - 8 not detailed]] 1316 | X<---+ NON 2.05 M:0xaa T:0xf0 O:1236 ET=23 QB2:9/1/1024 1317 [[MAX_PAYLOADS has been reached]] 1318 | ... | 1319 [[NON_TIMEOUT (server) delay expires]] 1320 | [[Server sends next set of payloads]] 1321 |<---------+ NON 2.05 M:0xab T:0xf0 O:1236 ET=23 QB2:10/0/1024 1322 | ... | 1323 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1324 | [[Client realizes blocks are missing and asks for the 1325 | missing ones in one go]] 1326 +--------->| NON GET /path M:0x04 T:0xf3 QB2:1/0/1024\ 1327 | | QB2:9/0/1024 1328 | X<---+ NON 2.05 M:0xac T:0xf3 ET=23 QB2:1/1/1024 1329 |<---------+ NON 2.05 M:0xad T:0xf3 ET=23 QB2:9/1/1024 1330 | ... | 1331 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1332 | [[Client realizes block is still missing and asks for 1333 | missing block]] 1334 +--------->| NON GET /path M:0x05 T:0xf4 QB2:1/0/1024 1335 |<---------+ NON 2.05 M:0xae T:0xf4 ET=23 QB2:1/1/1024 1336 [[Body has been received]] 1337 | ... | 1339 Figure 10: Example of NON Notifications with Q-Block2 Option (Blocks 1340 Recovery) 1342 9.2.4. Handling Recovery using M-bit Set 1344 Figure 11 shows the example of an Observe that is triggered but only 1345 the first two notification blocks reach the client. In order to 1346 retrieve the missing blocks, the client sends a request with a single 1347 Q-Block2 Option with the M bit set. 1349 CoAP CoAP 1350 Client Server 1351 | ... | 1352 | [[Observe triggered]] 1353 |<---------+ NON 2.05 M:0xb1 T:0xf0 O:1237 ET=24 QB2:0/1/1024 1354 |<---------+ NON 2.05 M:0xb2 T:0xf0 O:1237 ET=24 QB2:1/1/1024 1355 | X<---+ NON 2.05 M:0xb3 T:0xf0 O:1237 ET=24 QB2:2/1/1024 1356 | X<---+ [[Payloads 4 - 9 not detailed]] 1357 | X<---+ NON 2.05 M:0xb9 T:0xf0 O:1237 ET=24 QB2:9/1/1024 1358 [[MAX_PAYLOADS has been reached]] 1359 | ... | 1360 [[NON_TIMEOUT (server) delay expires]] 1361 | [[Server sends next set of payloads]] 1362 | X<---+ NON 2.05 M:0xba T:0xf0 O:1237 ET=24 QB2:10/0/1024 1363 | ... | 1364 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1365 | [[Client realizes blocks are missing and asks for the 1366 | missing ones in one go by setting the M bit]] 1367 +--------->| NON GET /path M:0x06 T:0xf5 QB2:2/1/1024 1368 |<---------+ NON 2.05 M:0xbb T:0xf5 ET=24 QB2:2/1/1024 1369 |<---------+ [[Payloads 3 - 9 not detailed]] 1370 |<---------+ NON 2.05 M:0xc2 T:0xf5 ET=24 QB2:9/1/1024 1371 [[MAX_PAYLOADS has been reached]] 1372 | [[MAX_PAYLOADS acknowledged by client using 'Continue' 1373 | Q-Block2]] 1374 +--------->| NON GET /path M:0x87 T:0xf6 QB2:10/1/1024 1375 |<---------+ NON 2.05 M:0xc3 T:0xf0 O:1237 ET=24 QB2:10/0/1024 1376 [[Body has been received]] 1377 | ... | 1379 Figure 11: Example of NON Notifications with Q-Block2 Option (Blocks 1380 Recovery with M bit Set) 1382 9.3. Q-Block1 and Q-Block2 Options 1384 9.3.1. A Simple Example 1386 Figure 12 illustrates the example of a FETCH using both Q-Block1 and 1387 Q-Block2 Options along with an Observe Option. No loss is 1388 experienced. 1390 CoAP CoAP 1391 Client Server 1392 | | 1393 +--------->| NON FETCH /path M:0x10 T:0x90 O:0 RT=30 QB1:0/1/1024 1394 +--------->| NON FETCH /path M:0x11 T:0x91 O:0 RT=30 QB1:1/1/1024 1395 +--------->| NON FETCH /path M:0x12 T:0x93 O:0 RT=30 QB1:2/0/1024 1396 |<---------+ NON 2.05 M:0x60 T:0x93 O:1320 ET=90 QB2:0/1/1024 1397 |<---------+ NON 2.05 M:0x61 T:0x93 O:1320 ET=90 QB2:1/1/1024 1398 |<---------+ NON 2.05 M:0x62 T:0x93 O:1320 ET=90 QB2:2/1/1024 1399 |<---------+ NON 2.05 M:0x63 T:0x93 O:1320 ET=90 QB2:3/0/1024 1400 | ... | 1401 | [[Observe triggered]] 1402 |<---------+ NON 2.05 M:0x64 T:0x93 O:1321 ET=91 QB2:0/1/1024 1403 |<---------+ NON 2.05 M:0x65 T:0x93 O:1321 ET=91 QB2:1/1/1024 1404 |<---------+ NON 2.05 M:0x66 T:0x93 O:1321 ET=91 QB2:2/1/1024 1405 |<---------+ NON 2.05 M:0x67 T:0x93 O:1321 ET=91 QB2:3/0/1024 1406 | ... | 1408 Figure 12: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1409 (Without Loss) 1411 9.3.2. Handling MAX_PAYLOADS Limits 1413 Figure 13 illustrates the same as Figure 12 but this time has eleven 1414 (11) payloads in both directions which exceeds MAX_PAYLOADS. There 1415 is no loss experienced. 1417 CoAP CoAP 1418 Client Server 1419 | | 1420 +--------->| NON FETCH /path M:0x30 T:0xa0 O:0 RT=10 QB1:0/1/1024 1421 +--------->| NON FETCH /path M:0x31 T:0xa1 O:0 RT=10 QB1:1/1/1024 1422 +--------->| [[Payloads 3 - 9 not detailed]] 1423 +--------->| NON FETCH /path M:0x39 T:0xa9 O:0 RT=10 QB1:9/1/1024 1424 [[MAX_PAYLOADS has been reached]] 1425 | [[MAX_PAYLOADS blocks receipt acknowledged by server]] 1426 |<---------+ NON 2.31 M:0x80 T:0xa9 1427 +--------->| NON FETCH /path M:0x3a T:0xaa O:0 RT=10 QB1:10/0/1024 1428 |<---------+ NON 2.05 M:0x81 T:0xaa O:1334 ET=21 QB2:0/1/1024 1429 |<---------+ NON 2.05 M:0x82 T:0xaa O:1334 ET=21 QB2:1/1/1024 1430 |<---------+ [[Payloads 3 - 9 not detailed]] 1431 |<---------+ NON 2.05 M:0x8a T:0xaa O:1334 ET=21 QB2:9/1/1024 1432 [[MAX_PAYLOADS has been reached]] 1433 | [[MAX_PAYLOADS blocks acknowledged by client using 1434 | 'Continue' Q-Block2]] 1435 +--------->| NON FETCH /path M:0x3b T:0xab QB2:10/1/1024 1436 |<---------+ NON 2.05 M:0x8b T:0xaa O:1334 ET=21 QB2:10/0/1024 1437 | ... | 1438 | [[Observe triggered]] 1439 |<---------+ NON 2.05 M:0x8c T:0xaa O:1335 ET=22 QB2:0/1/1024 1440 |<---------+ NON 2.05 M:0x8d T:0xaa O:1335 ET=22 QB2:1/1/1024 1441 |<---------+ [[Payloads 3 - 9 not detailed]] 1442 |<---------+ NON 2.05 M:0x95 T:0xaa O:1335 ET=22 QB2:9/1/1024 1443 [[MAX_PAYLOADS has been reached]] 1444 | [[MAX_PAYLOADS blocks acknowledged by client using 1445 | 'Continue' Q-Block2]] 1446 +--------->| NON FETCH /path M:0x3c T:0xac QB2:10/1/1024 1447 |<---------+ NON 2.05 M:0x96 T:0xaa O:1335 ET=22 QB2:10/0/1024 1448 [[Body has been received]] 1449 | ... | 1451 Figure 13: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1452 (Without Loss) 1454 9.3.3. Handling Recovery 1456 Consider now a scenario where some blocks are lost in transmission as 1457 illustrated in Figure 14. 1459 CoAP CoAP 1460 Client Server 1461 | | 1462 +--------->| NON FETCH /path M:0x50 T:0xc0 O:0 RT=31 QB1:0/1/1024 1463 +--->X | NON FETCH /path M:0x51 T:0xc1 O:0 RT=31 QB1:1/1/1024 1464 +--->X | NON FETCH /path M:0x52 T:0xc2 O:0 RT=31 QB1:2/1/1024 1465 +--------->| NON FETCH /path M:0x53 T:0xc3 O:0 RT=31 QB1:3/0/1024 1466 | ... | 1467 [[NON_RECEIVE_TIMEOUT (server) delay expires]] 1469 Figure 14: Example of NON FETCH with Q-Block1 and Q-Block2 Options 1470 (With Loss) 1472 The server realizes that some blocks are missing and asks for the 1473 missing blocks in one go (Figure 15). It does so by indicating which 1474 blocks have not been received in the data portion of the response. 1475 The token used in the response is the token that was used in the last 1476 received payload. The client can then derive the Request-Tag by 1477 matching the token with the sent request. 1479 CoAP CoAP 1480 Client Server 1481 | | 1482 |<---------+ NON 4.08 M:0xa0 T:0xc3 [Missing 1,2] 1483 | [[Client responds with missing payloads]] 1484 +--------->| NON FETCH /path M:0x54 T:0xc4 O:0 RT=31 QB1:1/1/1024 1485 +--------->| NON FETCH /path M:0x55 T:0xc5 O:0 RT=31 QB1:2/1/1024 1486 | [[Server received FETCH body, 1487 | starts transmitting response body]] 1488 |<---------+ NON 2.05 M:0xa1 T:0xc3 O:1236 ET=23 QB2:0/1/1024 1489 | X<---+ NON 2.05 M:0xa2 T:0xc3 O:1236 ET=23 QB2:1/1/1024 1490 |<---------+ NON 2.05 M:0xa3 T:0xc3 O:1236 ET=23 QB2:2/1/1024 1491 | X<---+ NON 2.05 M:0xa4 T:0xc3 O:1236 ET=23 QB2:3/0/1024 1492 | ... | 1493 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1494 | | 1496 Figure 15: Example of NON Request with Q-Block1 Option (Server 1497 Recovery) 1499 The client realizes that not all the payloads of the response have 1500 been returned. The client then asks for the missing blocks in one go 1501 (Figure 16). Note that, following Section 2.7 of [RFC7959], the 1502 FETCH request does not include the Q-Block1 or any payload. 1504 CoAP CoAP 1505 Client Server 1506 | | 1507 +--------->| NON FETCH /path M:0x56 T:0xc6 RT=31 QB2:1/0/1024\ 1508 | | QB2:3/0/1024 1509 | [[Server receives FETCH request for missing payloads, 1510 | starts transmitting missing blocks]] 1511 | X<---+ NON 2.05 M:0xa5 T:0xc6 ET=23 QB2:1/1/1024 1512 |<---------+ NON 2.05 M:0xa6 T:0xc6 ET=23 QB2:3/0/1024 1513 | ... | 1514 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1515 | [[Client realizes block is still missing and asks for 1516 | missing block]] 1517 +--------->| NON FETCH /path M:0x57 T:0xc7 RT=31 QB2:1/0/1024 1518 | [[Server receives FETCH request for missing payload, 1519 | starts transmitting missing block]] 1520 |<---------+ NON 2.05 M:0xa7 T:0xc7 ET=23 QB2:1/1/1024 1521 [[Body has been received]] 1522 | ... | 1523 | [[Observe triggered]] 1524 |<---------+ NON 2.05 M:0xa8 T:0xc3 O:1337 ET=24 QB2:0/1/1024 1525 | X<---+ NON 2.05 M:0xa9 T:0xc3 O:1337 ET=24 QB2:1/1/1024 1526 |<---------+ NON 2.05 M:0xaa T:0xc3 O:1337 ET=24 QB2:2/0/1024 1527 [[NON_RECEIVE_TIMEOUT (client) delay expires]] 1528 | [[Client realizes block is still missing and asks for 1529 | missing block]] 1530 +--------->| NON FETCH /path M:0x58 T:0xc8 RT=31 QB2:1/0/1024 1531 | [[Server receives FETCH request for missing payload, 1532 | starts transmitting missing block]] 1533 |<---------+ NON 2.05 M:0xa7 T:0xc8 ET=24 QB2:1/1/1024 1534 [[Body has been received]] 1535 | ... | 1537 Figure 16: Example of NON Request with Q-Block1 Option (Client 1538 Recovery) 1540 10. Security Considerations 1542 Security considerations discussed in Section 7 of [RFC7959] should be 1543 taken into account. 1545 Security considerations discussed in Sections 11.3 and 11.4 of 1546 [RFC7252] should be taken into account. 1548 OSCORE provides end-to-end protection of all information that is not 1549 required for proxy operations and requires that a security context is 1550 set up (Section 3.1 of [RFC8613]). It can be trusted that the source 1551 endpoint is legitimate even if NoSec security mode is used. However, 1552 an intermediary node can modify the unprotected outer Q-Block1 and/or 1553 Q-Block2 Options to cause a Q-Block transfer to fail or keep 1554 requesting all the blocks by setting the M bit and, thus, causing 1555 attack amplification. As discussed in Section 12.1 of [RFC8613], 1556 applications need to consider that certain message fields and 1557 messages types are not protected end-to-end and may be spoofed or 1558 manipulated. It is NOT RECOMMENDED that the NoSec security mode is 1559 used if the Q-Block1 and Q-Block2 Options are to be used. 1561 Security considerations related to the use of Request-Tag are 1562 discussed in Section 5 of [I-D.ietf-core-echo-request-tag]. 1564 11. IANA Considerations 1566 RFC Editor Note: Please replace [RFCXXXX] with the RFC number to be 1567 assigned to this document. 1569 11.1. CoAP Option Numbers Registry 1571 IANA is requested to add the following entries to the "CoAP Option 1572 Numbers" sub-registry [Options] defined in [RFC7252] within the 1573 "Constrained RESTful Environments (CoRE) Parameters" registry: 1575 +--------+------------------+-----------+ 1576 | Number | Name | Reference | 1577 +========+==================+===========+ 1578 | TBA1 | Q-Block1 | [RFCXXXX] | 1579 | TBA2 | Q-Block2 | [RFCXXXX] | 1580 +--------+------------------+-----------+ 1582 Table 4: CoAP Q-Block1 and Q-Block2 Option Numbers 1584 This document suggests 19 (TBA1) and 31 (TBA2) as values to be 1585 assigned for the new option numbers. 1587 11.2. Media Type Registration 1589 This document requests IANA to register the "application/missing- 1590 blocks+cbor-seq" media type in the "Media Types" registry 1591 [IANA-MediaTypes]. This registration follows the procedures 1592 specified in [RFC6838]: 1594 Type name: application 1596 Subtype name: missing-blocks+cbor-seq 1598 Required parameters: N/A 1600 Optional parameters: N/A 1602 Encoding considerations: Must be encoded as a CBOR 1603 sequence [RFC8742], as defined in Section 4 of [RFCXXXX]. 1605 Security considerations: See Section 10 of [RFCXXXX]. 1607 Interoperability considerations: N/A 1609 Published specification: [RFCXXXX] 1611 Applications that use this media type: Data serialization and 1612 deserialization. In particular, the type is used by applications 1613 relying upon block-wise transfers, allowing a server to specify 1614 non-received blocks and request for their retransmission, as 1615 defined in Section 4 of [RFCXXXX]. 1617 Fragment identifier considerations: N/A 1619 Additional information: N/A 1621 Person & email address to contact for further information: IETF, 1622 iesg@ietf.org 1624 Intended usage: COMMON 1626 Restrictions on usage: none 1628 Author: See Authors' Addresses section. 1630 Change controller: IESG 1632 Provisional registration? No 1634 11.3. CoAP Content-Formats Registry 1636 This document requests IANA to register the following CoAP Content- 1637 Format for the "application/missing-blocks+cbor-seq" media type in 1638 the "CoAP Content-Formats" registry [Format], defined in [RFC7252], 1639 within the "Constrained RESTful Environments (CoRE) Parameters" 1640 registry: 1642 o Media Type: application/missing-blocks+cbor-seq 1643 o Encoding: - 1644 o Id: TBA3 1645 o Reference: [RFCXXXX] 1647 This document suggests 272 (TBA3) as a value to be assigned for the 1648 new content format number. 1650 12. References 1652 12.1. Normative References 1654 [I-D.ietf-core-echo-request-tag] 1655 Amsuess, C., Mattsson, J., and G. Selander, "CoAP: Echo, 1656 Request-Tag, and Token Processing", draft-ietf-core-echo- 1657 request-tag-11 (work in progress), November 2020. 1659 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1660 Requirement Levels", BCP 14, RFC 2119, 1661 DOI 10.17487/RFC2119, March 1997, 1662 . 1664 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1665 Specifications and Registration Procedures", BCP 13, 1666 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1667 . 1669 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1670 Application Protocol (CoAP)", RFC 7252, 1671 DOI 10.17487/RFC7252, June 2014, 1672 . 1674 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1675 Application Protocol (CoAP)", RFC 7641, 1676 DOI 10.17487/RFC7641, September 2015, 1677 . 1679 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1680 the Constrained Application Protocol (CoAP)", RFC 7959, 1681 DOI 10.17487/RFC7959, August 2016, 1682 . 1684 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1685 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1686 the Constrained Application Protocol (CoAP)", RFC 8075, 1687 DOI 10.17487/RFC8075, February 2017, 1688 . 1690 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1691 FETCH Methods for the Constrained Application Protocol 1692 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1693 . 1695 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1696 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1697 May 2017, . 1699 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1700 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1701 Application Protocol) over TCP, TLS, and WebSockets", 1702 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1703 . 1705 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1706 "Object Security for Constrained RESTful Environments 1707 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1708 . 1710 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 1711 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 1712 . 1714 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1715 Representation (CBOR)", STD 94, RFC 8949, 1716 DOI 10.17487/RFC8949, December 2020, 1717 . 1719 12.2. Informative References 1721 [Format] "CoAP Content-Formats", . 1724 [I-D.bosh-dots-quick-blocks] 1725 Boucadair, M. and J. Shallow, "Distributed Denial-of- 1726 Service Open Threat Signaling (DOTS) Signal Channel 1727 Configuration Attributes for Faster Block Transmission", 1728 draft-bosh-dots-quick-blocks-01 (work in progress), 1729 January 2021. 1731 [I-D.ietf-dots-telemetry] 1732 Boucadair, M., Reddy.K, T., Doron, E., chenmeiling, c., 1733 and J. Shallow, "Distributed Denial-of-Service Open Threat 1734 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-15 1735 (work in progress), December 2020. 1737 [IANA-MediaTypes] 1738 IANA, "Media Types", 1739 . 1741 [Options] "CoAP Option Numbers", . 1744 [RFC6928] Chu, J., Dukkipati, N., Cheng, Y., and M. Mathis, 1745 "Increasing TCP's Initial Window", RFC 6928, 1746 DOI 10.17487/RFC6928, April 2013, 1747 . 1749 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1750 Definition Language (CDDL): A Notational Convention to 1751 Express Concise Binary Object Representation (CBOR) and 1752 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1753 June 2019, . 1755 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 1756 Mortensen, A., and N. Teague, "Distributed Denial-of- 1757 Service Open Threat Signaling (DOTS) Signal Channel 1758 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 1759 . 1761 [RFC8974] Hartke, K. and M. Richardson, "Extended Tokens and 1762 Stateless Clients in the Constrained Application Protocol 1763 (CoAP)", RFC 8974, DOI 10.17487/RFC8974, January 2021, 1764 . 1766 Appendix A. Examples with Confirmable Messages 1768 The following examples assume NSTART has been increased to 3. 1770 The notations provided in Figure 2 are used in the following 1771 subsections. 1773 A.1. Q-Block1 Option 1775 Let's now consider the use of Q-Block1 Option with a CON request as 1776 shown in Figure 17. All the blocks are acknowledged (ACK). 1778 CoAP CoAP 1779 Client Server 1780 | | 1781 +--------->| CON PUT /path M:0x01 T:0xf0 RT=10 QB1:0/1/1024 1782 +--------->| CON PUT /path M:0x02 T:0xf1 RT=10 QB1:1/1/1024 1783 +--------->| CON PUT /path M:0x03 T:0xf2 RT=10 QB1:2/1/1024 1784 [[NSTART(3) limit reached]] 1785 |<---------+ ACK 0.00 M:0x01 1786 +--------->| CON PUT /path M:0x04 T:0xf3 RT=10 QB1:3/0/1024 1787 |<---------+ ACK 0.00 M:0x02 1788 |<---------+ ACK 0.00 M:0x03 1789 |<---------+ ACK 2.04 M:0x04 1790 | | 1792 Figure 17: Example of CON Request with Q-Block1 Option (Without Loss) 1794 Now, suppose that a new body of data is to be sent but with some 1795 blocks dropped in transmission as illustrated in Figure 18. The 1796 client will retry sending blocks for which no ACK was received. 1798 CoAP CoAP 1799 Client Server 1800 | | 1801 +--------->| CON PUT /path M:0x05 T:0xf4 RT=11 QB1:0/1/1024 1802 +--->X | CON PUT /path M:0x06 T:0xf5 RT=11 QB1:1/1/1024 1803 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1804 [[NSTART(3) limit reached]] 1805 |<---------+ ACK 0.00 M:0x05 1806 +--------->| CON PUT /path M:0x08 T:0xf7 RT=11 QB1:3/1/1024 1807 |<---------+ ACK 0.00 M:0x08 1808 | ... | 1809 [[ACK_TIMEOUT (client) for M:0x06 delay expires]] 1810 | [[Client retransmits packet]] 1811 +--------->| CON PUT /path M:0x06 T:0xf5 RT=11 QB1:1/1/1024 1812 [[ACK_TIMEOUT (client) for M:0x07 delay expires]] 1813 | [[Client retransmits packet]] 1814 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1815 |<---------+ ACK 0.00 M:0x06 1816 | ... | 1817 [[ACK_TIMEOUT exponential backoff (client) delay expires]] 1818 | [[Client retransmits packet]] 1819 +--->X | CON PUT /path M:0x07 T:0xf6 RT=11 QB1:2/1/1024 1820 | ... | 1821 [[Either body transmission failure (acknowledge retry timeout) 1822 or successfully transmitted.]] 1824 Figure 18: Example of CON Request with Q-Block1 Option (Blocks 1825 Recovery) 1827 It is up to the implementation as to whether the application process 1828 stops trying to send this particular body of data on reaching 1829 MAX_RETRANSMIT for any payload, or separately tries to initiate the 1830 new transmission of the payloads that have not been acknowledged 1831 under these adverse traffic conditions. 1833 If there is likely to be the possibility of network transient losses, 1834 then the use of NON should be considered. 1836 A.2. Q-Block2 Option 1838 An example of the use of Q-Block2 Option with Confirmable messages is 1839 shown in Figure 19. 1841 Client Server 1842 | | 1843 +--------->| CON GET /path M:0x01 T:0xf0 O:0 QB2:0/1/1024 1844 |<---------+ ACK 2.05 M:0x01 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1845 |<---------+ CON 2.05 M:0xe1 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1846 |<---------+ CON 2.05 M:0xe2 T:0xf0 O:1234 ET=21 QB2:2/1/1024 1847 |<---------+ CON 2.05 M:0xe3 T:0xf0 O:1234 ET=21 QB2:3/0/1024 1848 |--------->+ ACK 0.00 M:0xe1 1849 |--------->+ ACK 0.00 M:0xe2 1850 |--------->+ ACK 0.00 M:0xe3 1851 | ... | 1852 | [[Observe triggered]] 1853 |<---------+ CON 2.05 M:0xe4 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1854 |<---------+ CON 2.05 M:0xe5 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1855 |<---------+ CON 2.05 M:0xe6 T:0xf0 O:1235 ET=22 QB2:2/1/1024 1856 [[NSTART(3) limit reached]] 1857 |--------->+ ACK 0.00 M:0xe4 1858 |<---------+ CON 2.05 M:0xe7 T:0xf0 O:1235 ET=22 QB2:3/0/1024 1859 |--------->+ ACK 0.00 M:0xe5 1860 |--------->+ ACK 0.00 M:0xe6 1861 |--------->+ ACK 0.00 M:0xe7 1862 | ... | 1863 | [[Observe triggered]] 1864 |<---------+ CON 2.05 M:0xe8 T:0xf0 O:1236 ET=23 QB2:0/1/1024 1865 | X<---+ CON 2.05 M:0xe9 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1866 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1867 [[NSTART(3) limit reached]] 1868 |--------->+ ACK 0.00 M:0xe8 1869 |<---------+ CON 2.05 M:0xeb T:0xf0 O:1236 ET=23 QB2:3/0/1024 1870 |--------->+ ACK 0.00 M:0xeb 1871 | ... | 1872 [[ACK_TIMEOUT (server) for M:0xe9 delay expires]] 1873 | [[Server retransmits packet]] 1874 |<---------+ CON 2.05 M:0xe9 T:0xf0 O:1236 ET=23 QB2:1/1/1024 1875 [[ACK_TIMEOUT (server) for M:0xea delay expires]] 1876 | [[Server retransmits packet]] 1877 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1878 |--------->+ ACK 0.00 M:0xe9 1879 | ... | 1880 [[ACK_TIMEOUT exponential backoff (server) delay expires]] 1881 | [[Server retransmits packet]] 1882 | X<---+ CON 2.05 M:0xea T:0xf0 O:1236 ET=23 QB2:2/1/1024 1883 | ... | 1884 [[Either body transmission failure (acknowledge retry timeout) 1885 or successfully transmitted.]] 1887 Figure 19: Example of CON Notifications with Q-Block2 Option 1889 It is up to the implementation as to whether the application process 1890 stops trying to send this particular body of data on reaching 1891 MAX_RETRANSMIT for any payload, or separately tries to initiate the 1892 new transmission of the payloads that have not been acknowledged 1893 under these adverse traffic conditions. 1895 If there is likely to be the possibility of network transient losses, 1896 then the use of NON should be considered. 1898 Appendix B. Examples with Reliable Transports 1900 The notations provided in Figure 2 are used in the following 1901 subsections. 1903 B.1. Q-Block1 Option 1905 Let's now consider the use of Q-Block1 Option with a reliable 1906 transport as shown in Figure 20. There is no acknowledgment of 1907 packets at the CoAP layer, just the final result. 1909 CoAP CoAP 1910 Client Server 1911 | | 1912 +--------->| PUT /path T:0xf0 RT=10 QB1:0/1/1024 1913 +--------->| PUT /path T:0xf1 RT=10 QB1:1/1/1024 1914 +--------->| PUT /path T:0xf2 RT=10 QB1:2/1/1024 1915 +--------->| PUT /path T:0xf3 RT=10 QB1:3/0/1024 1916 |<---------+ 2.04 1917 | | 1919 Figure 20: Example of Reliable Request with Q-Block1 Option 1921 If there is likely to be the possibility of network transient losses, 1922 then the use of unreliable transport with NON should be considered. 1924 B.2. Q-Block2 Option 1926 An example of the use of Q-Block2 Option with a reliable transport is 1927 shown in Figure 21. 1929 Client Server 1930 | | 1931 +--------->| GET /path T:0xf0 O:0 QB2:0/1/1024 1932 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:0/1/1024 1933 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:1/1/1024 1934 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:2/1/1024 1935 |<---------+ 2.05 T:0xf0 O:1234 ET=21 QB2:3/0/1024 1936 | ... | 1937 | [[Observe triggered]] 1938 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:0/1/1024 1939 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:1/1/1024 1940 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:2/1/1024 1941 |<---------+ 2.05 T:0xf0 O:1235 ET=22 QB2:3/0/1024 1942 | ... | 1944 Figure 21: Example of Notifications with Q-Block2 Option 1946 If there is likely to be the possibility of network transient losses, 1947 then the use of unreliable transport with NON should be considered. 1949 Acknowledgements 1951 Thanks to Achim Kraus, Jim Schaad, and Michael Richardson for their 1952 comments. 1954 Special thanks to Christian Amsuess, Carsten Bormann, and Marco 1955 Tiloca for their suggestions and several reviews, which improved this 1956 specification significantly. 1958 Some text from [RFC7959] is reused for readers convenience. 1960 Authors' Addresses 1962 Mohamed Boucadair 1963 Orange 1964 Rennes 35000 1965 France 1967 Email: mohamed.boucadair@orange.com 1969 Jon Shallow 1970 United Kingdom 1972 Email: supjps-ietf@jpshallow.com