RFC 7959
Block-Wise Transfers in the Constrained Application Protocol (CoAP)
Part 1 of 9 🎀
RFC 7959: Block-Wise Transfers in the Constrained Application Protocol (CoAP) 💖
okay bestie, this is the RFC that makes big CoAP payloads actually work 🦋 it's an IETF Standards Track doc from August 2016, so it's an official spec and not just someone's opinion. Carsten Bormann from Universitaet Bremen TZI wrote the first draft, and Z. Shelby (ARM) is the editor. It's ISSN 2070-1721, and it updates RFC 7252 (that's the base CoAP spec). Nothing in this doc gets listed as obsoleting anything, so it's just adding to the CoAP family tree 🌳
Abstract ✨
CoAP is a RESTful transfer protocol made for constrained nodes and networks 🧚 Basic CoAP messages are great for small payloads from sensors and actuators, but apps will occasionally need to move bigger stuff, like firmware updates 📦
Here's the tea: HTTP gets TCP to do the heavy lifting of segmenting and resequencing, but CoAP runs on datagram transports like UDP or Datagram Transport Layer Security (DTLS) 😭 Those only offer fragmentation, which is even messier on constrained nodes and networks, and it caps how big a resource representation can practically get.
So this spec doesn't rely on IP fragmentation. Instead it adds a pair of "Block" options to basic CoAP, so you can move multiple blocks of a representation across several request-response pairs 🔥 In lots of important cases the Block options make a server truly stateless. It can handle every block on its own, with no connection setup and no memory of earlier blocks, which is so iconic 👑 Basically, the Block options are the minimal way to send larger representations block by block.
Also, a CoAP implementation that doesn't support these options is generally limited in how big the representations it can swap are. So the expectation is that the Block options will be widely used in CoAP implementations 🌈 That's why this spec updates RFC 7252.
Status of This Memo 🦋
This is an Internet Standards Track document 💅
It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841 📚
For the current status of this doc, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7959 🎀
Copyright Notice 🌸
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved 🫶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication. Read these carefully, because they spell out your rights and restrictions for this document 🙈 Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License 💀
Table of Contents 🧚
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Block-Wise Transfers . . . . . . . . . . . . . . . . . . . . 6
2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 7
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 8
2.3. Block Options in Requests and Responses . . . . . . . . . 10
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 12
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 14
2.6. Combining Block-Wise Transfers with the Observe Option . 15
2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 16
2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 16
2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 17
2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 17
2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 17
2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 17
2.10. Caching Considerations . . . . . . . . . . . . . . . . . 18
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 19
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 23
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 25
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 26
4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 29
5. HTTP-Mapping Considerations . . . . . . . . . . . . . . . . . 31
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
7. Security Considerations . . . . . . . . . . . . . . . . . . . 33
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 33
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 34
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
8.1. Normative References . . . . . . . . . . . . . . . . . . 34
8.2. Informative References . . . . . . . . . . . . . . . . . 35
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 36
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 371. Introduction ✨
Okay bestie, so CoRE (Constrained RESTful Environments) is all about bringing REST to the most constrained nodes out there 🧚. We're talking microcontrollers with limited RAM and ROM [RFC7228], and networks like IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) [RFC4944] [RFC7252]. CoAP gives you RESTful [REST] services that feel a lot like HTTP [RFC7230], but way lighter, with less implementation complexity and smaller packets so it actually works in a highly constrained network full of highly constrained nodes 💖.
This goal takes restraint in a few ways that can pull against each other:
- reducing implementation complexity to minimize code size 💅,
- reducing message sizes to minimize the number of fragments needed for each message (to maximize the probability of delivery of the message), the amount of transmission power needed, and the loading of the limited-bandwidth channel 🔋,
- reducing requirements on the environment, like stable storage, good sources of randomness, or user-interaction capabilities 🙈.
Because CoAP is built on datagram transports like UDP or Datagram Transport Layer Security (DTLS), the maximum size of a resource representation you can send without too much fragmentation is limited 😭. Not every representation fits in a single link-layer packet of a constrained network either, so adaptation layer fragmentation can happen even when IP-layer fragmentation isn't needed. You could use fragmentation (at the adaptation layer or the IP layer) for bigger representations, up to the maximum size of the underlying datagram protocol (like UDP). But the fragmentation and reassembly process loads the lower layers with conversation state that's way better managed up in the application layer 🧠.
This specification defines a pair of CoAP options for block-wise access to resource representations. The Block options give you a minimal way to transfer bigger representations block by block 🎀. The overriding goal is to avoid creating conversation state at the server for block-wise GET requests. (It's impossible to avoid creating conversation state entirely for POST and PUT if the creation or replacement of resources has to be atomic. Where that property isn't needed, there's no need to create server conversation state in that case either.)
Block-wise transfers are combinations of exchanges, and each exchange follows the CoAP base protocol [RFC7252]. Every exchange in such a combination is governed by the specifications in [RFC7252], including the congestion control specifications (Section 4.7 of [RFC7252]) and the security considerations (Section 11 of [RFC7252]). On top of that, additional security considerations apply to the transfers as a whole, see Section 7 🔐. This specification adds as few constraints as it can to those base exchanges. Still, not every way of using CoAP is very useful inside a block-wise transfer. For example, using Non-confirmable requests within block-wise transfers outside the use case of Section 2.8 would escalate the overall non-delivery probability 🙃. To be perfectly clear, this specification also doesn't remove any of the constraints of the base specification it's strictly layered on top of. For example, back-to-back packets are still limited by the congestion control described in Section 4.7 of [RFC7252] (NSTART as a limit for initiating exchanges, PROBING_RATE as a limit for sending with no response). Block-wise transfers can't send or solicit more traffic than a client could be sending to, or soliciting from, the same server without the block-wise mode.
In some cases, this specification will RECOMMEND that a client perform a sequence of block-wise transfers "without undue delay". That can't be phrased as an interoperability requirement, but it is an expectation on implementation quality ⭐. On the flip side, servers aren't expected to go out of their way to accommodate clients that take a long time to finish a block-wise transfer. For example, during a block-wise GET, if the resource changes while this is happening, the entity-tag (ETag) for a further block obtained may be different. To keep that from happening all the time with a fast-changing resource, a server MAY try to keep a cache around for a specific client for a short amount of time. The expectation here is that the lifetime of such a cache can be kept short, on the order of a few expected round-trip times, counting from the previous block transferred ⏳.
In summary, this specification adds a pair of Block options to CoAP that can be used for block-wise transfers. Here's why they're so good 🦋:
- Transfers larger than what fits in constrained-network link-layer packets can be performed in smaller blocks.
- No hard-to-manage conversation state gets created at the adaptation layer or IP layer for fragmentation.
- The transfer of each block is acknowledged, which enables individual retransmission if required.
- Both sides get a say in the block size that actually gets used.
- The resulting exchanges are easy to understand with packet analyzer tools, so they're super accessible for debugging 🔍.
- If needed, the Block options can also be used (without changes) to provide random access to power-of-two sized blocks within a resource representation.
A CoAP implementation that doesn't support these options generally is limited in the size of the representations it can exchange (see Section 4.6 of [RFC7252]). Even though the options are Critical, a server may decide to start using them in an unsolicited way in a response. No effort went into a capability indication mechanism for that decision. Since block-wise transfer mechanisms are so fundamental to using CoAP for representations bigger than about a kilobyte, there's an expectation that they're very widely implemented 🌈.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119, BCP 14 [RFC2119] and indicate requirement levels for compliant CoAP implementations 📖.
In this document, "byte" is used in its now-customary sense as a synonym for "octet" 🍓.
Where bit arithmetic is explained, this document uses the notation familiar from the programming language C, except that the operator ** stands for exponentiation 🧮.
2. Block-Wise Transfers
As we covered in the introduction, there are good reasons to limit the size of datagrams in constrained networks 🤓:
- by the maximum datagram size (~ 64 KiB for UDP)
- by the desire to avoid IP fragmentation (MTU of 1280 for IPv6)
- by the desire to avoid adaptation-layer fragmentation (60-80 bytes for 6LoWPAN [RFC4919])
When a resource representation is larger than can be comfortably transferred in the payload of a single CoAP datagram, a Block option can be used to indicate a block-wise transfer 🎁. Payloads can be sent with both requests and responses, so this specification provides two separate options, one for each direction of payload transfer. When naming these options (for block-wise transfers as well as in Section 4), we use the number 1 ("Block1", "Size1") for the transfer of the resource representation that pertains to the request, and the number 2 ("Block2", "Size2") for the transfer of the resource representation for the response 💜.
In what follows, "payload" means the actual content of a single CoAP message, i.e., a single block being transferred. "Body" means the entire resource representation being transferred block-wise 🧁. The Content-Format Option applies to the body, not to the payload. In particular, the boundaries between blocks may fall in places that don't separate whole units in terms of the structure, encoding, or content-coding used by the Content-Format. (Similarly, the ETag Option defined in Section 5.10.6 of [RFC7252] applies to the whole representation of the resource, and thus to the body of the response.)
In most cases, all blocks being transferred for a body (except the last one) will be the same size. (If the first request uses a bigger block size than the receiver prefers, subsequent requests will use the preferred block size.) The block size isn't fixed by the protocol. To keep implementation as simple as possible, the Block options only support a small range of power-of-two block sizes, from 2**4 (16) to 2**10 (1024) bytes 🧩. Since bodies often won't divide evenly into the chosen power-of-two block size, the size doesn't need to be reached in the final block. Even so, for the final block, the chosen power-of-two size is still indicated in the block size field of the Block option ✨.
2.1. The Block2 and Block1 Options
+-----+---+---+---+---+--------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+--------+--------+--------+---------+
| 23 | C | U | - | - | Block2 | uint | 0-3 | (none) |
| | | | | | | | | |
| 27 | C | U | - | - | Block1 | uint | 0-3 | (none) |
+-----+---+---+---+---+--------+--------+--------+---------+
Table 1: Block Option NumbersBoth Block1 and Block2 Options can be present in both request and response messages. In either case, the Block1 Option pertains to the request payload, and the Block2 Option pertains to the response payload 🎀.
So, for the methods defined in [RFC7252], Block1 is useful with the payload-bearing POST and PUT requests and their responses. Block2 is useful with GET, POST, and PUT requests and their payload-bearing responses (2.01, 2.02, 2.04, and 2.05; see Section 5.5 of [RFC7252]) 💅.
When Block1 is present in a request, or Block2 in a response (i.e., in the message whose payload it pertains to), it indicates a block-wise transfer and describes how this specific block-wise payload forms part of the entire body being transferred ("descriptive usage"). When it's present in the opposite direction, it provides additional control over how that payload will be formed or was processed ("control usage") 🎛️.
Implementation of either Block option is intended to be optional. However, when it's present in a CoAP message, it MUST be processed (or the message rejected), so it's identified as a Critical option 🚨. Either Block option MUST NOT occur more than once in a single message 🙅♀️.
2.2. Structure of a Block Option
okay so there are three things we need to pass along in a Block (Block1 or Block2) option, bestie 🎀
- the size of the block (SZX) 📦
- whether more blocks are following (M) 🏃♀️
- the relative number of the block (NUM) within a sequence of blocks with the given size 🔢
The value of the Block option is a variable-size (0 to 3 byte) unsigned integer (uint, see Section 3.2 of [RFC7252]) 💖 That one integer packs all three fields together, and you can see the layout in Figure 1. (Because of the CoAP uint-encoding rules, when NUM, M, and SZX are all zero, a zero-byte integer gets sent. Iconic, right? 🧚)
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| NUM |M| SZX |
+-+-+-+-+-+-+-+-+
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 1: Block Option ValueThe block size is encoded with a three-bit unsigned integer (0 for 24 bytes up to 6 for 210 bytes), and we call that the "SZX" ("size exponent") ✨ The actual block size is then "2**(SZX + 4)". SZX lives in the three least significant bits of the option value (i.e., "val & 7" where "val" is the value of the option). It's giving tiny bit-packing energy 🦋
The fourth least significant bit is the M or "more" bit ("val & 8"). It tells you whether more blocks are coming or whether the current block-wise transfer is the last block being sent 🏁
The option value divided by sixteen (the NUM field) is the sequence number of the block currently being transferred, starting from zero. So the current transfer is, therefore, about the "size" bytes starting at byte "NUM << (SZX + 4)" 🌸
Implementation note: as an implementation convenience, "(val & ~0xF) << (val & 7)", i.e., the option value with the last 4 bits masked out, shifted to the left by the value of SZX, gives the byte position of the first byte of the block being transferred. Cute little trick, no cap 💅
More specifically, within the option value of a Block1 or Block2 Option, the meaning of the option fields is defined as follows:
- NUM: Block Number, indicating the block number being requested or provided. Block number 0 indicates the first block of a body (i.e., starting with the first byte of the body) 🥇
- M: More Flag ("not last block"). For descriptive usage, this flag, if unset, indicates that the payload in this message is the last block in the body; when set, it indicates that there are one or more additional blocks available. When a Block2 Option is used in a request to retrieve a specific block number ("control usage"), the M bit MUST be sent as zero and ignored on reception. (In a Block1 Option in a response, the M flag is used to indicate atomicity, see below.) 🙈
- SZX: Block Size. The block size is represented as a three-bit unsigned integer indicating the size of a block to the power of two. Thus, block size = 2(SZX + 4). The allowed values of SZX are 0 to 6, i.e., the minimum block size is 2(0+4) = 16 and the maximum is 2**(6+4) = 1024. The value 7 for SZX (which would indicate a block size of 2048) is reserved, i.e., MUST NOT be sent and MUST lead to a 4.00 Bad Request response code upon reception in a request. Not allowed, periodt 🚫
There is no default value for the Block1 and Block2 Options. Absence of one of these options is equivalent to an option value of 0 with respect to the value of NUM and M that could be given in the option, i.e., it indicates that the current block is the first and only block of the transfer (block number 0, M bit not set). However, in contrast to the explicit value 0, which would indicate an SZX of 0 and thus a size value of 16 bytes, there is no specific explicit size implied by the absence of the option -- the size is left unspecified. (As for any uint, the explicit value 0 is efficiently indicated by a zero-length option; this, therefore, is different in semantics from the absence of the option.) 🫶
2.3. Block Options in Requests and Responses
The Block options are used in one of three roles, and each one has its own main character energy 👑
- In descriptive usage, i.e., a Block2 Option in a response (such as a 2.05 response for GET), or a Block1 Option in a request (a PUT or POST):
- The NUM field in the option value describes what block number is contained in the payload of this message. 📬
- The M bit indicates whether further blocks need to be transferred to complete the transfer of that body. 🔁
- The block size implied by SZX MUST match the size of the payload in bytes, if the M bit is set. (SZX does not govern the payload size if M is unset). For Block2, if the request suggested a larger value of SZX, the next request MUST move SZX down to the size given in the response. (The effect is that, if the server uses the smaller of (1) its preferred block size and (2) the block size requested, all blocks for a body use the same block size.) 📏
- A Block2 Option in control usage in a request (e.g., GET):
- The NUM field in the Block2 Option gives the block number of the payload that is being requested to be returned in the response. 🎯
- In this case, the M bit has no function and MUST be set to zero. 0️⃣
- The block size given (SZX) suggests a block size (in the case of block number 0) or repeats the block size of previous blocks received (in the case of a non-zero block number). 💭
- A Block1 Option in control usage in a response (e.g., a 2.xx response for a PUT or POST request):
- The NUM field of the Block1 Option indicates what block number is being acknowledged. 💌
- If the M bit was set in the request, the server can choose whether to act on each block separately, with no memory, or whether to handle the request for the entire body atomically, or any mix of the two.
- If the M bit is also set in the response, it indicates that this response does not carry the final response code to the request, i.e., the server collects further blocks from the same endpoint and plans to implement the request atomically (e.g., acts only upon reception of the last block of payload). In this case, the response MUST NOT carry a Block2 Option. 🧺
- Conversely, if the M bit is unset even though it was set in the request, it indicates the block-wise request was enacted now specifically for this block, and the response carries the final response to this request (and to any previous ones with the M bit set in the response's Block1 Option in this sequence of block-wise transfers); the client is still expected to continue sending further blocks, the request method for which may or may not also be enacted per-block. (Note that the resource is now in a partially updated state; this approach is only appropriate where exposing such an intermediate state is acceptable. The client can reduce the window by quickly continuing to update the resource, or, in case of failure, restarting the update.) 🫣
- Finally, the SZX block size given in a control Block1 Option indicates the largest block size preferred by the server for transfers toward the resource that is the same or smaller than the one used in the initial exchange; the client SHOULD use this block size or a smaller one in all further requests in the transfer sequence, even if that means changing the block size (and possibly scaling the block number accordingly) from now on. 🌈
Using one or both Block options, a single REST operation can be split into multiple CoAP message exchanges. As specified in [RFC7252], each of these message exchanges uses their own CoAP Message ID. 🦋
The Content-Format Option sent with the requests or responses MUST reflect the Content-Format of the entire body. If blocks of a response body arrive with different Content-Format Options, it is up to the client how to handle this error (it will typically abort any ongoing block-wise transfer). If blocks of a request arrive at a server with mismatching Content-Format Options, the server MUST NOT assemble them into a single request; this usually leads to a 4.08 (Request Entity Incomplete, Section 2.9.2) error response on the mismatching block. Mismatched blocks are a whole vibe-killer 💀
2.4. Using the Block2 Option ✨
okay so when a request gets answered with a response carrying a Block2 Option with the M bit set, the requester is allowed to grab more blocks of the resource representation 💖 by sending further requests with the same options as the initial request, plus a Block2 Option saying which block number and block size it wants. In a request, the client MUST set the M bit of a Block2 Option to zero, and the server MUST ignore it on reception. 🫶
to influence the block size used in a response, the requester MAY also use the Block2 Option on the initial request. it gives the desired size, a block number of zero, and an M bit of zero. a server MUST use the block size indicated or a smaller size. any further block-wise requests for blocks beyond the first one MUST indicate the same block size that the server used in the response to the first request that gave a desired size using a Block2 Option. 🌸
once the Block2 Option is used by the requester and a first response has come back with a possibly adjusted block size, all further requests in a single block-wise transfer will ultimately converge on using the same size. the one exception is that there may not be enough content to fill the last block (the one returned with the M bit not set). (note that the client may start using the Block2 Option in a second request after a first request without a Block2 Option resulted in a Block2 Option in the response.) the server uses the block size indicated in the request option or a smaller size. but the requester MUST take note of the actual block size used in the response it receives to its initial request, and proceed to use it in subsequent requests. the server behavior MUST ensure that this client behavior results in the same block size for all responses in a sequence. the exceptions are the last one with the M bit not set, and possibly the first one if the initial request did not contain a Block2 Option. 🧚
block-wise transfers can be used to GET resources whose representations are entirely static (not changing over time at all, such as a schema describing a device), or for dynamically changing resources. in the latter case, the Block2 Option SHOULD be used in conjunction with the ETag Option ([RFC7252], Section 5.10.6), to make sure the blocks being reassembled are from the same version of the representation. the server SHOULD include an ETag Option in each response. if an ETag Option is available, the client MUST compare ETag Options when it reassembles the representation from the blocks being exchanged. if the ETag Options do not match in a GET transfer, the requester has the option of trying to retrieve fresh values for the blocks it retrieved first. 🦋
to minimize the resulting inefficiency, the server MAY cache the current value of a representation for an ongoing sequence of requests. (the server may identify the sequence by the combination of the requesting endpoint and the URI being the same in each block-wise request.) note well that this specification makes no requirement for the server to establish any state. however, servers that offer quickly changing resources may thereby make it impossible for a client to ever retrieve a consistent set of blocks 😭. clients that want to retrieve all blocks of a resource SHOULD strive to do so without undue delay. servers can fully expect to be free to discard any cached state after a period of EXCHANGE_LIFETIME ([RFC7252], Section 4.8.2) after the last access to the state. however, there is no requirement to always keep the state for that long. 💅
the Block2 Option provides no way for a single endpoint to perform multiple concurrently proceeding block-wise response payload transfer (e.g., GET) operations to the same resource. this is rarely a requirement, but as a workaround, a client may vary the cache key (e.g., by using one of several URIs accessing resources with the same semantics, or by varying a proxy-safe elective option). 🌈
2.5. Using the Block1 Option 🎀
in a request with a request payload (e.g., PUT or POST), the Block1 Option refers to the payload in the request. this is the descriptive usage. 🍓
in response to a request with a payload (e.g., a PUT or POST transfer), the block size given in the Block1 Option shows the block size preference of the server for this resource. this is the control usage. obviously, at this point the first block has already been sent by the client without any benefit of this knowledge 🙈. still, the client SHOULD heed the preference indicated and, for all further blocks, use the block size preferred by the server or a smaller one. note that any reduction in the block size may mean that the second request starts with a block number larger than one, because the first request already transferred multiple blocks counted in the smaller size.
to counter the effects of adaptation-layer fragmentation on packet-delivery probability, a client may want to give up retransmitting a request with a relatively large payload even before MAX_RETRANSMIT has been reached. it can then try restating the request as a block-wise transfer with a smaller payload. note that this new attempt is then a new message-layer transaction and requires a new Message ID. (because of the uncertainty about whether the request or the acknowledgement was lost, this strategy is useful mostly for idempotent requests.) 🧠
in a block-wise transfer of a request payload (e.g., a PUT or POST) that is intended to be implemented in an atomic fashion at the server, the actual creation or replacement takes place when the final block is received. that is a block with the M bit unset in the Block1 Option. in this case, all success responses to non-final blocks carry the response code 2.31 (Continue, Section 2.9.1). if not all previous blocks are available at the server when it processes the final block, the transfer fails, and error code 4.08 (Request Entity Incomplete, Section 2.9.2) MUST be returned. a server MAY also return a 4.08 error code for any (final or non-final) Block1 transfer that is not in sequence. so, clients that do not have specific mechanisms to handle this case SHOULD always start with block zero and send the following blocks in order. 🌷
one reason a client might run into a 4.08 error code is that the server has already timed out and discarded the partial request body it was assembling. clients SHOULD strive to send all blocks of a request without undue delay. servers can fully expect to be free to discard any partial request body once a period of EXCHANGE_LIFETIME ([RFC7252], Section 4.8.2) has elapsed after the most recent block was transferred. however, there is no requirement on a server to always keep the partial request body for that long. ⏳
the error code 4.13 (Request Entity Too Large) can be returned at any time by a server that does not currently have the resources to store blocks for a block-wise request payload transfer it would intend to implement in an atomic fashion. (note that a 4.13 response to a request that does not employ Block1 is a hint for the client to try sending Block1. and a 4.13 response with a smaller SZX in its Block1 Option than requested is a hint to try a smaller SZX.) 🫧
a block-wise transfer of a request payload that is implemented in a stateless fashion at the server is likely to leave the resource being operated on in an inconsistent state. that can happen while the transfer is still ongoing, or when the client does not complete the transfer. this characteristic is closer to that of remote file systems than to that of HTTP, where state is always kept on the server during a transfer. techniques well known from shared file access (e.g., client-specific temporary resources) can be used to mitigate this difference from HTTP. 🗂️
the Block1 Option provides no way for a single endpoint to perform multiple concurrently proceeding block-wise request payload transfer (e.g., PUT or POST) operations to the same resource. starting a new block-wise sequence of requests to the same resource, before an old sequence from the same endpoint has finished, simply overwrites the context the server may still be keeping. (this is probably exactly what one wants in this case -- the client may simply have restarted and lost its knowledge of the previous sequence.) 🔄
2.6. Combining Block-Wise Transfers with the Observe Option 👀
the Observe option gives a client a way to be notified about changes over time of a resource [RFC7641]. resources observed by clients may be larger than can be comfortably processed or transferred in one CoAP message. the following rules apply to the combination of block-wise transfers with notifications. 💜
observation relationships always apply to an entire resource. the Block2 Option does not provide a way to observe a single block of a resource. 🚫
as with basic GET transfers, the client can indicate its desired block size in a Block2 Option in the GET request that establishes or renews the observation relationship. if the server supports block-wise transfers, it SHOULD take note of the block size and apply it as a maximum size to all notifications/responses resulting from the GET request. this lasts until the client is removed from the list of observers, or until the entry in that list is updated by the server receiving a new GET request for the resource from the client. ⭐
when sending a 2.05 (Content) notification, the server only sends the first block of the representation. the client retrieves the rest of the representation as if it had caused this first response with a GET request. that means using additional GET requests with Block2 Options containing NUM values greater than zero. (this results in the transfer of the entire representation, even if only some of the blocks have changed with respect to a previous notification.) 🔁
as with other dynamically changing resources, the server SHOULD include an ETag Option in each response, so that the blocks being reassembled are from the same version of the representation. the reassembling client MUST compare the ETag Options (Section 2.4). even more so than for the general case of Block2, clients that want to retrieve all blocks of a resource they have been notified about with a first block SHOULD strive to do so without undue delay. 🏃♀️
see Section 3.4 for examples. 🎬
2.7. Combining Block1 and Block2 💞
in PUT and particularly in POST exchanges, both the request body and the response body may be large enough to need block-wise transfers. first, the Block1 transfer of the request body proceeds as usual. in the exchange of the last slice of this block-wise transfer, the response carries the first slice of the Block2 transfer (NUM is zero). to continue this Block2 transfer, the client keeps sending requests similar to the ones in the Block1 phase. the difference is that it leaves out the Block1 Options and includes a Block2 request option with a non-zero NUM. 🎀
Block2 transfers that retrieve the response body for a request that used Block1 MUST be performed in sequential order. 🌟
2.8. Combining Block2 with Multicast 📡💕
okay so a client can use the Block2 Option in a multicast GET request with NUM = 0 to help keep the response size in check 🫶
same deal for the server: a response to a multicast GET request can use a Block2 Option with NUM = 0 if the representation is big, or to shrink the response even more ✨
in both cases the client grabs any remaining blocks through unicast exchanges, and in those unicast requests the client SHOULD heed any block size preferences the server indicated in its response to the multicast request 💅
other uses of the Block options alongside multicast messages are for further study 🔮
2.9. Response Codes 🎀
beyond the response codes defined in [RFC7252], this spec defines two new response codes and extends the meaning of one 🌈
2.9.1. 2.31 Continue 🦋
this new success status code means the transfer of this block of the request body worked, and the server is like "send more blocks pls" 💖 but the final outcome of the whole block-wise request can't be figured out yet 🥹 no payload comes back with this one 🫧
2.9.2. 4.08 Request Entity Incomplete 😭
this new client error status code means the server hasn't gotten the blocks of the request body it needs to keep going 💀 maybe the client hasn't sent all of them, sent them in the wrong order, or sent them so long ago that the server already tossed them 🙈
(note that one reason the server might not have the blocks handy is a Content-Format mismatch, see Section 2.3 🎀 implementation note: a server can reject a Block1 transfer with this code when NUM != 0 and a different Content-Format is indicated than what's expected from the current state of the resource 🧚 if it does the transfer in a stateless fashion, it can match the Content-Format of the block against the existing resource 💜 if it does the transfer in an atomic fashion, it can match the block against the partially reassembled piece of representation that's going to replace the resource's state ✨)
2.9.3. 4.13 Request Entity Too Large 🐘
in Section 5.9.2.9 of [RFC7252], the response code 4.13 (Request Entity Too Large) is defined to be like HTTP 413 "Request Entity Too Large" 🌸 [RFC7252] also recommends that this response SHOULD include a Size1 Option (Section 4) to show the maximum size of request entity the server can handle and is willing to handle, unless the server can't make that info available 📏
this spec lets the server return this response code at any point during a Block1 transfer to say it doesn't currently have the resources to store blocks for a transfer it would want to do atomically 🥺 it also lets the server send a 4.13 to a request that doesn't use Block1, as a hint for the client to try Block1 🎀 finally, a 4.13 response to a request with a Block1 Option (control usage, see Section 2.3) where the response carries a smaller SZX in its Block1 Option is a hint to try that smaller SZX 💅✨
2.10. Caching Considerations 🗂️
this spec tries to leave a bunch of implementation strategies open for caches, especially the ones in caching proxies 🦋 for example, a cache is free to cache blocks individually, but it could also wait to get the complete representation before serving parts of it 🌷 partial caching may be more efficient in a cross-proxy (equivalent to a streaming HTTP proxy) 🚀 a cached block (partial cached response) can be used in place of a complete response to satisfy a block-wise request presented to a cache 💖 note that different blocks can have different Max-Age values, since they're transferred at different times ⏰ a response with a block updates the freshness of the complete representation 🫶 individual blocks can be validated, and validating a single block validates the complete representation 🔍 a response with a Block1 Option in control usage with the M bit set invalidates cached responses for the target URI 💀
a cache or proxy that combines responses (e.g., to split blocks in a request or increase the block size in a response, or a cross-proxy) may need to combine 2.31 and 2.01/2.04 responses 🧩 a stateless server may be responding with 2.01 only on the first Block1 block transferred, which dominates any 2.04 responses for later blocks 👑
If-None-Match only works correctly on Block1 requests with (NUM=0) and MUST NOT be used on Block1 requests with NUM != 0 🚫 (this one's important, bestie 😭)
- Examples 🧁
this section gives a bunch of short examples with message flows for a block-wise GET, and for a PUT or POST 📬 they show the basic operation, what happens with retransmissions, and examples of block size negotiation 🔁
in all these examples, a Block option is shown in a decomposed way: the kind of Block option (1 or 2) followed by a colon, then the block number (NUM), more bit (M), and block size exponent (2**(SZX+4)) separated by slashes 🧮 for example, a Block2 Option value of 33 would be shown as 2:2/0/32) and a Block1 Option value of 59 would be shown as 1:3/1/128 🌈
as in [RFC7252], "MID" is used as an abbreviation for "Message ID" 🫧
3.1. Block2 Examples ✨
okay bestie, let's look at the Block2 examples 🦋 The first one (Figure 2) is a GET split into three blocks. The server proposes a block size of 128, the client says yes 💅 The first two ACKs carry 128 bytes of payload each, and the third one carries anywhere from 1 to 128 bytes. ✨
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GET, /status, 2:1/0/128 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:1/1/128 |
| |
| CON [MID=1236], GET, /status, 2:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.05 Content, 2:2/0/128 |Figure 2: Simple Block-Wise GET
In the second example (Figure 3), the client sees the block-wise transfer coming 👀 maybe because of a size indication in the link-format description [RFC6690], so it sends its own block size proposal right away. Every ACK except the last one carries 64 bytes of payload, and the last one carries between 1 and 64 bytes. Main character planning, honestly 🌸
CLIENT SERVER
| |
| CON [MID=1234], GET, /status, 2:0/0/64 ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 |
| |
| CON [MID=1235], GET, /status, 2:1/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 |
: :
: ... :
: :
| CON [MID=1238], GET, /status, 2:4/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 |
| |
| CON [MID=1239], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 |Figure 3: Block-Wise GET with Early Negotiation
Now the third example (Figure 4) is giving drama 😭 The client is caught off guard by the need for a block-wise transfer, and it is not vibing with the size the server picked all by itself. Since it didn't send a size proposal at the start, the negotiation only changes the size from the second message exchange onward. The client already got the first and second 64-byte blocks inside that first 128-byte exchange, so it keeps asking for the third 64-byte block ("2/0/64") 🧚 None of this is understood by the server (and honestly it doesn't need to be), because the server just responds to the requests as well as it can. ngl, the server is very chill about it 💜
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
| |
| CON [MID=1236], GET, /status, 2:3/0/64 ------> |
| |
| <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 |
| |
| CON [MID=1237], GET, /status, 2:4/0/64 ------> |
| |
| <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 |
| |
| CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |Figure 4: Block-Wise GET with Late Negotiation
In all of these (and the ones coming up), retransmissions are handled by the CoAP message exchange layer, so they don't mess with the block operations. That's the vibe 🫶 Check Figures 5 and 6 for the proof ✨
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GE///////////////////////// |
| |
| (timeout) |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
: :
: ... :
: :
| CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |Figure 5: Block-Wise GET with Late Negotiation and Lost CON
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| //////////////////////////////////tent, 2:2/1/64 |
| |
| (timeout) |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
: :
: ... :
: :
| CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |Figure 6: Block-Wise GET with Late Negotiation and Lost ACK
3.2. Block1 Examples
The following examples demonstrate a PUT exchange 💖 A POST exchange looks the same, but it has different requirements on atomicity/idempotence. Note that, just like GET, the responses to requests with a more bit in the request Block1 Option are provisional and carry the response code 2.31 (Continue). Only the final response tells the client that the PUT succeeded 🎀
CLIENT SERVER
| |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |Figure 7: Simple Atomic Block-Wise PUT
okay so a stateless server that just builds or updates the resource in place (statelessly) can signal that by NOT setting the more bit in the response 🦋 (Figure 8). In this case, the response codes are valid separately for each block being updated 🌸 This is of course only an acceptable behavior for the server if the potential inconsistency present during the message exchange sequence doesn't cause problems, e.g., because the resource being created or changed is not yet, or not currently, in use 💅
CLIENT SERVER
| |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 |
| |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 |
| |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |Figure 8: Simple Stateless Block-Wise PUT
Finally 👑 a server receiving a block-wise PUT or POST may want to indicate a smaller block size preference (Figure 9). In this case, the client SHOULD continue with a smaller block size. If it does, it MUST adjust the block number so it counts properly in that smaller size 🧚
CLIENT SERVER
| |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/32 |
| |
| CON [MID=1235], PUT, /options, 1:4/1/32 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:4/1/32 |
| |
| CON [MID=1236], PUT, /options, 1:5/1/32 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:5/1/32 |
| |
| CON [MID=1237], PUT, /options, 1:6/0/32 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:6/0/32 |Figure 9: Simple Atomic Block-Wise PUT with Negotiation
3.3. Combining Block1 and Block2 🌈
Block options can be used in both directions of a single exchange ✨ The following example shows a block-wise POST request that gets a separate block-wise response 💜
CLIENT SERVER
| |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| |
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| |
| CON [MID=1236], POST, /soap, 1:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/128 |
| |
| CON [MID=1237], POST, /soap, 2:1/0/128 ------> |
| (no payload for requests with Block2 with NUM != 0) |
| (could also do late negotiation by requesting, |
| e.g., 2:2/0/64) |
| |
| <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 |
| |
| CON [MID=1238], POST, /soap, 2:2/0/128 ------> |
| |
| <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 |
| |
| CON [MID=1239], POST, /soap, 2:3/0/128 ------> |
| |
| <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 |Figure 10: Atomic Block-Wise POST with Block-Wise Response
This model does allow for early negotiation input to the Block2 block-wise transfer, as shown below 🍓
CLIENT SERVER
| |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| |
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| |
| CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 |
| |
| CON [MID=1237], POST, /soap, 2:1/0/64 ------> |
| (no payload for requests with Block2 with NUM != 0) |
| |
| <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 |
| |
| CON [MID=1238], POST, /soap, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 |
| |
| CON [MID=1239], POST, /soap, 2:3/0/64 ------> |
| |
| <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 |Figure 11: Atomic Block-Wise POST with Block-Wise Response, Early Negotiation
3.4. Combining Observe and Block2 ✨
okay so in this first example, the server first sends a direct response (Observe sequence number 62350) to the initial GET request 💅 the block-wise transfer that comes out of that is as in Figure 4, so we're skipping it 🙈 then the second transfer kicks off with a 2.05 notification that only carries the first block (Observe sequence number 62354), and the client goes on to grab the rest of the blocks 🫶
CLIENT SERVER
| |
+----->| Header: GET 0x41011636
| GET | Token: 0xfb
| | Uri-Path: status-icon
| | Observe: (empty)
| |
|<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62350
| | ETag: 6f00f38e
| | Payload: [128 bytes]
| |
| | (Usual GET transfer left out)
...
| | (Notification of first block)
| |
|<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62354
| | ETag: 6f00f392
| | Payload: [128 bytes]
| |
+- - ->| Header: 0x6000af9c
| |
| | (Retrieval of remaining blocks)
| |
+----->| Header: GET 0x41011637
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 1/0/128
| |
|<-----+ Header: 2.05 0x61451637
| 2.05 | Token: 0xfc
| | Block2: 1/1/128
| | ETag: 6f00f392
| | Payload: [128 bytes]
| |
+----->| Header: GET 0x41011638
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 2/0/128
| |
|<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc
| | Block2: 2/0/128
| | ETag: 6f00f392
| | Payload: [53 bytes]Figure 12: Observe Sequence with Block-Wise Response
(Note that the choice of token 0xfc in this example is arbitrary 🦋 the tokens are only shown to illustrate that the requests for additional blocks cannot make use of the token of the Observation relationship. As a general comment on tokens, there is no other mention of tokens in this document, as block-wise transfers handle tokens like any other CoAP exchange. As usual, the client is free to choose tokens for each exchange as it likes.)
In the following example, the client also uses early negotiation to limit the block size to 64 bytes 🎀
CLIENT SERVER
| |
+----->| Header: GET 0x41011636
| GET | Token: 0xfb
| | Uri-Path: status-icon
| | Observe: (empty)
| | Block2: 0/0/64
| |
|<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb
| | Block2: 0/1/64
| | Observe: 62350
| | ETag: 6f00f38e
| | Max-Age: 60
| | Payload: [64 bytes]
| |
| | (Usual GET transfer left out)
...
| | (Notification of first block)
| |
|<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb
| | Block2: 0/1/64
| | Observe: 62354
| | ETag: 6f00f392
| | Payload: [64 bytes]
| |
+- - ->| Header: 0x6000af9c
| |
| | (Retrieval of remaining blocks)
| |
+----->| Header: GET 0x41011637
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 1/0/64
| |
|<-----+ Header: 2.05 0x61451637
| 2.05 | Token: 0xfc
| | Block2: 1/1/64
| | ETag: 6f00f392
| | Payload: [64 bytes]
....
| |
+----->| Header: GET 0x41011638
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 4/0/64
| |
|<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc
| | Block2: 4/0/64
| | ETag: 6f00f392
| | Payload: [53 bytes]Figure 13: Observe Sequence with Early Negotiation
4. The Size2 and Size1 Options ✨
okay so when you're sending a big representation block by block, it's super helpful to know the total size early on 📏 some hint might come from the maximum size estimate attribute "sz" in a resource description [RFC6690]. but the size can change on the fly, so a fresher number can be really useful 🌸
this spec defines two CoAP options: Size1 for indicating the size of the representation transferred in requests, and Size2 for indicating the size of the representation transferred in responses. (Size1 was already defined in Section 5.10.9 of [RFC7252] to provide "size information about the resource representation in a request"; however, that section only details the narrow case of indicating in 4.13 responses the maximum size of request payload that the server is able and willing to handle. The present specification provides details about its use as a request option as well.) The Size2 Option may be used for two purposes:
- In a request, to ask the server to provide a size estimate along with the usual response ("size request"). For this usage, the value MUST be set to 0.
- In a response carrying a Block2 Option, to indicate the current estimate the server has of the total size of the resource representation, measured in bytes ("size indication").
Similarly, the Size1 Option may be used for two purposes:
- In a request carrying a Block1 Option, to indicate the current estimate the client has of the total size of the resource representation, measured in bytes ("size indication").
- In a 4.13 response, to indicate the maximum size that would have been acceptable [RFC7252], measured in bytes.
Apart from conveying or asking for size information, the Size options have no other effect on the processing of the request or response. If the client wants to minimize the size of the payload in the resulting response, it should add a Block2 Option to the request with a small block size (e.g., setting SZX=0).
The Size options are "elective", i.e., a client MUST be prepared for the server to ignore the size estimate request. Either Size option MUST NOT occur more than once in a single message. 🙅♀️
+-----+---+---+---+---+-------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+-------+--------+--------+---------+
| 60 | | | x | | Size1 | uint | 0-4 | (none) |
| | | | | | | | | |
| 28 | | | x | | Size2 | uint | 0-4 | (none) |
+-----+---+---+---+---+-------+--------+--------+---------+
Table 2: Size Option NumbersImplementation Notes:
- As a quality of implementation consideration, block-wise transfers for which the total size considerably exceeds the size of one block are expected to include size indications, whenever those can be provided without undue effort (preferably with the first block exchanged). If the size estimate does not change, the indication does not need to be repeated for every block. 💡
- The end of a block-wise transfer is governed by the M bits in the Block options, _not_ by exhausting the size estimates exchanged.
- As usual for an option of type uint, the value 0 is best expressed as an empty option (0 bytes). There is no default value for either Size option.
- The Size options are neither critical nor unsafe, and are marked as No-Cache-Key.
5. HTTP-Mapping Considerations ✨
okay so in this bit we give some quick examples of how the Block options might affect intermediaries that map between CoAP and HTTP 🌈
for mapping CoAP requests to HTTP, the intermediary may want to map the sequence of block-wise transfers into a single HTTP transfer. For example, for a GET request, the intermediary could perform the HTTP request once the first block has been requested and could then fulfill all further block requests out of its cache. A constrained implementation may not be able to cache the entire object and may use a combination of TCP flow control and (in particular if timeouts occur) HTTP range requests to obtain the information necessary for the next block transfer at the right time.
For PUT or POST requests, historically there was more variation in how HTTP servers might implement ranges; recently, [RFC7233] has defined that Range header fields received with a request method other than GET are not to be interpreted. So, in general, the CoAP-to-HTTP intermediary will have to try sending the payload of all the blocks of a block-wise transfer for these other methods within one HTTP request. If enough buffering is available, this request can be started when the last CoAP block is received. A constrained implementation may want to relieve its buffering by already starting to send the HTTP request at the time the first CoAP block is received; any HTTP 408 status code that indicates that the HTTP server became impatient with the resulting transfer can then be mapped into a CoAP 4.08 response code (similarly, 413 maps to 4.13). 🧚
For mapping HTTP to CoAP, the intermediary may want to map a single HTTP transfer into a sequence of block-wise transfers. If the HTTP client is too slow delivering a request body on a PUT or POST, the CoAP server might time out and return a 4.08 response code, which in turn maps well to an HTTP 408 status code (again, 4.13 maps to 413). HTTP range requests received on the HTTP side may be served out of a cache and/or mapped to GET requests that request a sequence of blocks that cover the range.
(Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, this difference is largely due to the different way the two protocols are mapped to transport. HTTP has an underlying TCP connection, which supplies connection state, so an HTTP 408 status code can immediately be used to indicate that a timeout occurred during transmitting a request through that active TCP connection. The CoAP 4.08 response code indicates one or more missing blocks, which may be due to timeouts or resource constraints; as there is no connection state, there is no way to deliver such a response immediately; instead, it is delivered on the next block transfer. Still, HTTP 408 is probably the best mapping back to HTTP, as the timeout is the most likely cause for a CoAP 4.08. Note that there is no way to distinguish a timeout from a missing block for a server without creating additional state, the need for which we want to avoid.) 🥺
6. IANA Considerations ✨
Okay bestie, IANA time 📋. This doc adds three option numbers to the "CoAP Option Numbers" registry that [RFC7252] set up, so Block2, Block1, and Size2 all get their official numbers 🔢.
+--------+--------+-----------+
| Number | Name | Reference |
+--------+--------+-----------+
| 23 | Block2 | RFC 7959 |
| | | |
| 27 | Block1 | RFC 7959 |
| | | |
| 28 | Size2 | RFC 7959 |
+--------+--------+-----------+
Table 3: CoAP Option NumbersIt also adds two response codes to the "CoAP Response Codes" registry from [RFC7252] 💅. 2.31 is Continue and 4.08 is Request Entity Incomplete, both pointing back to this RFC.
+------+---------------------------+-----------+
| Code | Description | Reference |
+------+---------------------------+-----------+
| 2.31 | Continue | RFC 7959 |
| | | |
| 4.08 | Request Entity Incomplete | RFC 7959 |
+------+---------------------------+-----------+
Table 4: CoAP Response Codes7. Security Considerations 🔥
Okay, serious moment, bestie 😭. Giving access to blocks within a resource can lead to surprising vulnerabilities. If requests aren't implemented atomically, an attacker might catch a race condition, or confuse a server into using a partially updated resource representation.
Partial transfers can also hide problematic data from Intrusion Detection Systems (IDSs). So it is RECOMMENDED that an IDS that analyzes resource representations transferred by CoAP implement the Block options so it can get access to entire resource representations 👀. Still, tricks like sending even-numbered blocks on one path and odd-numbered blocks on another, or sending blocks multiple times with different content so the IDS reads the temporal order differently than the server does, may stop an IDS from seeing the whole picture. These kinds of attacks are well understood from IP fragmentation and TCP segmentation, so CoAP doesn't add fundamentally new considerations 🧚.
Where access to a resource is only granted to clients using specific security associations, all blocks of that resource MUST be subject to the same security checks. It MUST NOT be possible for unprotected exchanges to influence blocks of an otherwise protected resource 🚫. Related to this, when object security is employed, PUT/POST should be implemented in the atomic fashion, unless the object security operation is performed on each access and the creation of unusable resources can be tolerated.
Future end-to-end security mechanisms that may be added to CoAP itself may have related security considerations too. This includes considerations about caching of blocks in clients and in proxies (see Sections 2.10 and 5 for different strategies in performing this caching). These security considerations will need to be described in the specifications of those mechanisms 💖.
A stateless server might be susceptible to an attack where the adversary sends a Block1 (e.g., PUT) block with a high block number. A naive implementation might exhaust its resources by creating a huge resource representation 💀.
Misleading size indications may be used by an attacker to induce buffer overflows in poor implementations, and the usual considerations apply 🙈.
7.1. Mitigating Resource Exhaustion Attacks
Certain block-wise requests may induce the server to create state. For example, a server might create a snapshot for the block-wise GET of a fast-changing resource, so all blocks come from the same version of that resource. Or it might create temporary resource representations that get collected until they're pressed into service by a final PUT or POST with the more bit unset 🧺. All mechanisms that induce a server to create state that cannot simply be cleaned up create opportunities for denial-of-service attacks.
Servers SHOULD avoid being subject to resource exhaustion based on state created by untrusted sources. But even if this is done, the mitigation may cause a denial-of-service to a legitimate request when it gets drowned out by other state-creating requests 😩. So wherever possible, servers should minimize the opportunities to create state for untrusted sources, for example by using stateless approaches.
Performing segmentation at the application layer is almost always better in this respect than at the transport layer or lower (IP fragmentation, adaptation-layer fragmentation). That's because there are application-layer semantics that can be used for mitigation, or because lower layers provide security associations that can prevent attacks. However, it is less common to apply timeouts and keepalive mechanisms at the application layer than at lower layers. Servers MAY want to clean up accumulated state by timing it out (cf. response code 4.08), and clients SHOULD be prepared to run block-wise transfers in an expedient way, to minimize the likelihood of running into such a timeout ⏰.
7.2. Mitigating Amplification Attacks
[RFC7252] discusses the susceptibility of CoAP endpoints for use in amplification attacks 📢.
A CoAP server can reduce the amount of amplification it provides to an attacker by offering large resource representations only in relatively small blocks. For example, for a 1000-byte resource, a 10-byte request might result in an 80-byte response (with a 64-byte block) instead of a 1016-byte response, which considerably reduces the amplification provided 📉.
8. References 📚
8.1. Normative References
These are the must-reads, the ones this doc leans on for real:
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>.8.2. Informative References
These are the background reads, great for going deeper 🤓:
[REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000,
<http://www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>.
[RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
over Low-Power Wireless Personal Area Networks (6LoWPANs):
Overview, Assumptions, Problem Statement, and Goals",
RFC 4919, DOI 10.17487/RFC4919, August 2007,
<http://www.rfc-editor.org/info/rfc4919>.
[RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
"Transmission of IPv6 Packets over IEEE 802.15.4
Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007,
<http://www.rfc-editor.org/info/rfc4944>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014,
<http://www.rfc-editor.org/info/rfc7228>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.
[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
"Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
RFC 7233, DOI 10.17487/RFC7233, June 2014,
<http://www.rfc-editor.org/info/rfc7233>.Acknowledgements 🫶
Okay, the shoutouts! A big chunk of this doc came out of discussions with the [RFC7252] authors and lots of CoRE WG conversations 💜.
Charles Palmer gave extensive editorial comments on an earlier draft, and some of them made it in ✍️. Esko Dijk reviewed a more recent version, which led to a bunch more editorial improvements, a solution to the 4.13 ambiguity problem, and the section about combining Block and multicast (Section 2.8). Markus Becker proposed getting rid of an ill-conceived default value for the Block2 and Block1 Options 🙌. Peter Bigot insisted on a more systematic coverage of the options and response code. Qin Wu provided a review for the IETF Operations directorate, and Goeran Selander commented on the security considerations 🛡️.
Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of the Size option, which is described in this doc. Klaus Hartke wrote some of the text describing the interaction of Block2 with Observe. Matthias Kovatsch provided a number of significant simplifications of the protocol 🧠.
The IESG reviewers provided very useful comments. Spencer Dawkins even suggested new text 🌟. He and Mirja Kuehlewind insisted on more explicit information about the layering of block-wise transfers on top of the base protocol. Ben Campbell helped untangle some MUST/SHOULD soup 🍝. Comments by Alexey Melnikov, as well as the Gen-ART review by Jouni Korhonen, resulted in further improvements to the text 💅.
Authors' Addresses 📮
Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Zach Shelby (editor)
ARM
150 Rose Orchard
San Jose, CA 95134
United States of America
Phone: +1-408-203-9434
Email: zach.shelby@arm.com📦 where this page comes from
- ietf: rfc7959 2016-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms