diff options
Diffstat (limited to 'rfc/draft-ietf-core-block-17.txt')
| -rw-r--r-- | rfc/draft-ietf-core-block-17.txt | 1848 |
1 files changed, 1848 insertions, 0 deletions
diff --git a/rfc/draft-ietf-core-block-17.txt b/rfc/draft-ietf-core-block-17.txt new file mode 100644 index 0000000..60bed7a --- /dev/null +++ b/rfc/draft-ietf-core-block-17.txt @@ -0,0 +1,1848 @@ + + + + +CoRE Working Group C. Bormann +Internet-Draft Universitaet Bremen TZI +Intended status: Standards Track Z. Shelby, Ed. +Expires: September 10, 2015 ARM + March 09, 2015 + + + Block-wise transfers in CoAP + draft-ietf-core-block-17 + +Abstract + + CoAP is a RESTful transfer protocol for constrained nodes and + networks. Basic CoAP messages work well for the small payloads we + expect from temperature sensors, light switches, and similar + building-automation devices. Occasionally, however, applications + will need to transfer larger payloads -- for instance, for firmware + updates. With HTTP, TCP does the grunt work of slicing large + payloads up into multiple packets and ensuring that they all arrive + and are handled in the right order. + + CoAP is based on datagram transports such as UDP or DTLS, which + limits the maximum size of resource representations that can be + transferred without too much fragmentation. Although UDP supports + larger payloads through IP fragmentation, it is limited to 64 KiB + and, more importantly, doesn't really work well for constrained + applications and networks. + + Instead of relying on IP fragmentation, this specification extends + basic CoAP with a pair of "Block" options, for transferring multiple + blocks of information from a resource representation in multiple + request-response pairs. In many important cases, the Block options + enable a server to be truly stateless: the server can handle each + block transfer separately, with no need for a connection setup or + other server-side memory of previous block transfers. + + In summary, the Block options provide a minimal way to transfer + larger representations in a block-wise fashion. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + + +Bormann & Shelby Expires September 10, 2015 [Page 1] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on September 10, 2015. + +Copyright Notice + + Copyright (c) 2015 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) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 5 + 2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5 + 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6 + 2.3. Block Options in Requests and Responses . . . . . . . . . 8 + 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10 + 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 12 + 2.6. Combining Block-wise Transfers with the Observe Option . 13 + 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 14 + 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 14 + 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14 + 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 15 + 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 15 + 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 15 + 2.10. Caching Considerations . . . . . . . . . . . . . . . . . 15 + 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 16 + 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 20 + 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 21 + 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 23 + 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 26 + 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 27 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 + + + +Bormann & Shelby Expires September 10, 2015 [Page 2] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 30 + 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 31 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 + 9.1. Normative References . . . . . . . . . . . . . . . . . . 31 + 9.2. Informative References . . . . . . . . . . . . . . . . . 32 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 + +1. Introduction + + The work on Constrained RESTful Environments (CoRE) aims at realizing + the REST architecture in a suitable form for the most constrained + nodes (such as microcontrollers with limited RAM and ROM [RFC7228]) + and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP + protocol is intended to provide RESTful [REST] services not unlike + HTTP [RFC7230], while reducing the complexity of implementation as + well as the size of packets exchanged in order to make these services + useful in a highly constrained network of themselves highly + constrained nodes. + + This objective requires restraint in a number of sometimes + conflicting ways: + + o reducing implementation complexity in order to minimize code size, + + o reducing message sizes in order to minimize the number of + fragments needed for each message (in turn to maximize the + probability of delivery of the message), the amount of + transmission power needed and the loading of the limited-bandwidth + channel, + + o reducing requirements on the environment such as stable storage, + good sources of randomness or user interaction capabilities. + + CoAP is based on datagram transports such as UDP, which limit the + maximum size of resource representations that can be transferred + without creating unreasonable levels of IP fragmentation. In + addition, not all resource representations will fit into a single + link layer packet of a constrained network, which may cause + adaptation layer fragmentation even if IP layer fragmentation is not + required. Using fragmentation (either at the adaptation layer or at + the IP layer) for the transport of larger representations would be + possible up to the maximum size of the underlying datagram protocol + (such as UDP), but the fragmentation/reassembly process burdens the + lower layers with conversation state that is better managed in the + application layer. + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 3] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + The present specification defines a pair of CoAP options to enable + _block-wise_ access to resource representations. The Block options + provide a minimal way to transfer larger resource representations in + a block-wise fashion. The overriding objective is to avoid the need + for creating conversation state at the server for block-wise GET + requests. (It is impossible to fully avoid creating conversation + state for POST/PUT, if the creation/replacement of resources is to be + atomic; where that property is not needed, there is no need to create + server conversation state in this case, either.) + + In summary, this specification adds a pair of Block options to CoAP + that can be used for block-wise transfers. Benefits of using these + options include: + + o Transfers larger than what can be accommodated in constrained- + network link-layer packets can be performed in smaller blocks. + + o No hard-to-manage conversation state is created at the adaptation + layer or IP layer for fragmentation. + + o The transfer of each block is acknowledged, enabling individual + retransmission if required. + + o Both sides have a say in the block size that actually will be + used. + + o The resulting exchanges are easy to understand using packet + analyzer tools and thus quite accessible to debugging. + + o 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. + + 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, the term "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. + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 4] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +2. Block-wise transfers + + As discussed in the introduction, there are good reasons to limit the + size of datagrams in constrained networks: + + o by the maximum datagram size (~ 64 KiB for UDP) + + o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6) + + o 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. As payloads can be + sent both with requests and with responses, this specification + provides two separate options for each direction of payload transfer. + In identifying these options, we use the number 1 to refer to the + transfer of the resource representation that pertains to the request, + and the number 2 to refer to the transfer of the resource + representation for the response. + + In the following, the term "payload" will be used for the actual + content of a single CoAP message, i.e. a single block being + transferred, while the term "body" will be used for the entire + resource representation that is being transferred in a block-wise + fashion. The Content-Format option applies to the body, not to the + payload, in particular the boundaries between the blocks may be in + places that are not separating whole units in terms of the structure, + encoding, or content-coding used by the Content-Format. + + In most cases, all blocks being transferred for a body (except for + the last one) will be of the same size. The block size is not fixed + by the protocol. To keep the implementation as simple as possible, + the Block options support only a small range of power-of-two block + sizes, from 2**4 (16) to 2**10 (1024) bytes. As bodies often will + not evenly divide into the power-of-two block size chosen, the size + need not be reached in the final block (but even for the final block, + the chosen power-of-two size will still be indicated in the block + size field of the Block option). + +2.1. The Block2 and Block1 Options + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 5] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + +-----+---+---+---+---+--------+--------+--------+---------+ + | 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 Numbers + + Both Block1 and Block2 options can be present both in request and + response messages. In either case, the Block1 Option pertains to the + request payload, and the Block2 Option pertains to the response + payload. + + Hence, 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, 2.05 -- see section "Payload" of + [RFC7252]). + + Where Block1 is present in a request or Block2 in a response (i.e., + in that message to the payload of which it pertains) it indicates a + block-wise transfer and describes how this specific block-wise + payload forms part of the entire body being transferred ("descriptive + usage"). Where it is present in the opposite direction, it provides + additional control on how that payload will be formed or was + processed ("control usage"). + + Implementation of either Block option is intended to be optional. + However, when it is present in a CoAP message, it MUST be processed + (or the message rejected); therefore it is identified as a critical + option. It MUST NOT occur more than once. + +2.2. Structure of a Block Option + + Three items of information may need to be transferred in a Block + (Block1 or Block2) option: + + o The size of the block (SZX); + + o whether more blocks are following (M); + + o 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]). This integer + + + +Bormann & Shelby Expires September 10, 2015 [Page 6] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + value encodes these three fields, see Figure 1. (Due to the CoAP + uint encoding rules, when all of NUM, M, and SZX happen to be zero, a + zero-byte integer will be sent.) + + 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 value + + The block size is encoded using a three-bit unsigned integer (0 for + 2**4 to 6 for 2**10 bytes), which we call the "SZX" ("size + exponent"); the actual block size is then "2**(SZX + 4)". SZX is + transferred in the three least significant bits of the option value + (i.e., "val & 7" where "val" is the value of the option). + + The fourth least significant bit, the M or "more" bit ("val & 8"), + indicates whether more blocks are following or the current block-wise + transfer is the last block being transferred. + + The option value divided by sixteen (the NUM field) is the sequence + number of the block currently being transferred, starting from zero. + 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. + + More specifically, within the option value of a Block1 or Block2 + Option, the meaning of the option fields is defined as follows: + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 7] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 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. + + 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: + + o 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. + + + + +Bormann & Shelby Expires September 10, 2015 [Page 8] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + * 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.) + + o 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. + + * 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). + + o 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 + + + + +Bormann & Shelby Expires September 10, 2015 [Page 9] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + expected to continue sending further blocks, the request + method for which may or may not also be enacted per-block. + + * 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. + +2.4. Using the Block2 Option + + When a request is answered with a response carrying a Block2 Option + with the M bit set, the requester may retrieve additional blocks of + the resource representation by sending further requests with the same + options as the initial request and a Block2 Option giving the block + number and block size desired. 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, giving 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 was used by the server in the response for 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 been received with a possibly adjusted block size, all further + requests in a single block-wise transfer SHOULD ultimately use the + same size, except that there may not be enough content to fill the + + + +Bormann & Shelby Expires September 10, 2015 [Page 10] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 SHOULD use 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 (except for 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 the representations + of which are entirely static (not changing over time at all, such as + in 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, to ensure that 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's reassembler, when reassembling the + representation from the blocks being exchanged, MUST compare ETag + Options. If the ETag Options do not match in a GET transfer, the + requester has the option of attempting 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 end-point + 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 as 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). + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 11] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +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 (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 indicates the + block size preference of the server for this resource (control + usage). Obviously, at this point the first block has already been + transferred by the client without 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, as the first + request already transferred multiple blocks as 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, and 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 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/replacement takes place at the time the + final block, i.e. a block with the M bit unset in the Block1 Option, + is received. 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 at the time of processing + 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; clients that do not have specific + mechanisms to handle this case therefore SHOULD always start with + block zero and send the following blocks in order. + + One reason that a client might encounter a 4.08 error code is that + the server has already timed out and discarded the partial request + body being assembled. 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 when a period of EXCHANGE_LIFETIME + ([RFC7252], Section 4.8.2) has elapsed after the most recent block + + + + +Bormann & Shelby Expires September 10, 2015 [Page 12] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + was transferred; however, there is no requirement on a server to + always keep the partial request body for as 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 that 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.) + + 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 was 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 provides a way for a client to be notified about + changes over time of a resource [I-D.ietf-core-observe]. 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 establishing or + renewing 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 (until the client is removed from the list of observers or + 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 by a GET + request, i.e., by 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.) + + + +Bormann & Shelby Expires September 10, 2015 [Page 13] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + As with other dynamically changing resources, to ensure that the + blocks being reassembled are from the same version of the + representation, the server SHOULD include an ETag option in each + response, and 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 require the use of 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 + continues to send requests similar to the requests in the Block1 + phase, but leaves out the Block1 options and includes a Block2 + request option with 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 + + A client can use the Block2 option in a multicast GET request with + NUM = 0 to aid in limiting the size of the response. + + Similarly, a response to a multicast GET request can use a Block2 + option with NUM = 0 if the representation is large, or to further + limit the size of the response. + + In both cases, the client retrieves any further blocks using unicast + exchanges; in the unicast requests, the client SHOULD heed any block + size preferences indicated by the server in the response to the + multicast request. + + Other uses of the Block options in conjunction with multicast + messages are for further study. + +2.9. Response Codes + + Two response codes are defined by this specification beyond those + already defined in [RFC7252], and another response code is extended + in its meaning. + + + +Bormann & Shelby Expires September 10, 2015 [Page 14] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +2.9.1. 2.31 Continue + + This new success status code indicates that the transfer of this + block of the request body was successful and that the server + encourages sending further blocks, but that a final outcome of the + whole block-wise request cannot yet be determined. No payload is + returned with this response code. + +2.9.2. 4.08 Request Entity Incomplete + + This new client error status code indicates that the server has not + received the blocks of the request body that it needs to proceed. + The client has not sent all blocks, not sent them in the order + required by the server, or has sent them long enough ago that the + server has already discarded them. + +2.9.3. 4.13 Request Entity Too Large + + In [RFC7252], section 5.9.2.9, 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 indicate the maximum size of request entity the + server is able and willing to handle, unless the server is not in a + position to make this information available. + + The present specification allows the server to return this response + code at any time during a Block1 transfer to indicate that it does + not currently have the resources to store blocks for a transfer that + it would intend to implement in an atomic fashion. It also allows + the server to return a 4.13 response to a request that does not + employ Block1 as a hint for the client to try sending 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 specification attempts to leave a variety of implementation + strategies open for caches, in particular those in caching proxies. + E.g., a cache is free to cache blocks individually, but also could + wait to obtain the complete representation before it serves 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 that is presented to a cache. Note that + different blocks can have different Max-Age values, as they are + transferred at different times. A response with a block updates the + freshness of the complete representation. Individual blocks can be + + + +Bormann & Shelby Expires September 10, 2015 [Page 15] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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. + +3. Examples + + This section gives a number of short examples with message flows for + a block-wise GET, and for a PUT or POST. These examples demonstrate + the basic operation, the operation in the presence of + retransmissions, and examples for the operation of the block size + negotiation. + + In all these examples, a Block option is shown in a decomposed way + indicating the kind of Block option (1 or 2) followed by a colon, and + then the block number (NUM), more bit (M), and block size exponent + (2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 + would be shown as 2:2/0/32), or a Block1 Option value of 59 would be + shown as 1:3/1/128. + +3.1. Block2 Examples + + The first example (Figure 2) shows a GET request that is split into + three blocks. The server proposes a block size of 128, and the + client agrees. The first two ACKs contain 128 bytes of payload each, + and third ACK contains between 1 and 128 bytes. + + + + + + + + + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 16] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 anticipates the block- + wise transfer (e.g., because of a size indication in the link-format + description [RFC6690]) and sends a block size proposal. All ACK + messages except for the last carry 64 bytes of payload; the last one + carries between 1 and 64 bytes. + + 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 + + In the third example (Figure 4), the client is surprised by the need + for a block-wise transfer, and unhappy with the size chosen + unilaterally by the server. As it did not send a size proposal + initially, the negotiation only influences the size from the second + + + +Bormann & Shelby Expires September 10, 2015 [Page 17] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + message exchange onward. Since the client already obtained both the + first and second 64-byte block in the first 128-byte exchange, it + goes on requesting the third 64-byte block ("2/0/64"). None of this + is (or needs to be) understood by the server, which simply responds + to the requests as it best can. + + 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 these (and the following) cases, retransmissions are handled + by the CoAP message exchange layer, so they don't influence the block + operations (Figure 5, Figure 6). + + + + + + + + + + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 18] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 19] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +3.2. Block1 Examples + + The following examples demonstrate a PUT exchange; a POST exchange + looks the same, with different requirements on atomicity/idempotence. + Note that, similar to GET, the responses to the requests that have 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 did succeed. + + 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 + + A stateless server that simply builds/updates the resource in place + (statelessly) may indicate this 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 of the server if the potential inconsistency + present during the run of the message exchange sequence does not lead + to problems, e.g. because the resource being created or changed is + not yet or not currently in use. + + + + + + + + + + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 20] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 to properly count 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 may be used in both directions of a single exchange. + The following example demonstrates a block-wise POST request, + resulting in a separate block-wise response. + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 21] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 provide for early negotiation input to the Block2 + block-wise transfer, as shown below. + + + + + + + + + + + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 22] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 + + In the following example, the server first sends a direct response + (Observe sequence number 62350) to the initial GET request (the + resulting block-wise transfer is as in Figure 4 and has therefore + been left out). The second transfer is started by a 2.05 + notification that contains just the first block (Observe sequence + number 62354); the client then goes on to obtain the rest of the + blocks. + + CLIENT SERVER + | | + +----->| Header: GET 0x41011636 + | GET | Token: 0xfb + | | Uri-Path: status-icon + | | Observe: (empty) + | | + |<-----+ Header: 2.05 0x61451636 + + + +Bormann & Shelby Expires September 10, 2015 [Page 23] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + | 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 examples is arbitrary; + tokens are just shown in this example to illustrate that the requests + + + +Bormann & Shelby Expires September 10, 2015 [Page 24] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + 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 + + + +Bormann & Shelby Expires September 10, 2015 [Page 25] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + | | 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 + + In many cases when transferring a large resource representation block + by block, it is advantageous to know the total size early in the + process. Some indication may be available from the maximum size + estimate attribute "sz" provided in a resource description [RFC6690]. + However, the size may vary dynamically, so a more up-to-date + indication may be useful. + + This specification 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 is already defined in [RFC7252] for 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 Size2 Option may be used for two purposes: + + o 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. + + o 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: + + o 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"). + + + +Bormann & Shelby Expires September 10, 2015 [Page 26] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + o in a 4.13 response, to indicate the maximum size that would have + been acceptable [RFC7252], measured in bytes. + + Apart from conveying/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. The Size Options + MUST NOT occur more than once. + + +-----+---+---+---+---+-------+--------+--------+---------+ + | 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 Numbers + + Implementation Notes: + + o 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. + + o The end of a block-wise transfer is governed by the M bits in the + Block Options, _not_ by exhausting the size estimates exchanged. + + o 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. + + o The Size Options are neither critical nor unsafe, and are marked + as No-Cache-Key. + +5. HTTP Mapping Considerations + + In this subsection, we give some brief examples for the influence the + Block options might have on intermediaries that map between CoAP and + HTTP. + + + + +Bormann & Shelby Expires September 10, 2015 [Page 27] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + For mapping CoAP requests to HTTP, the intermediary may want to map + the sequence of block-wise transfers into a single HTTP transfer. + E.g., 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 + overlapping 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 a 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.) + + + + +Bormann & Shelby Expires September 10, 2015 [Page 28] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +6. IANA Considerations + + This draft adds the following option numbers to the CoAP Option + Numbers registry of [RFC7252]: + + +--------+--------+-----------+ + | Number | Name | Reference | + +--------+--------+-----------+ + | 23 | Block2 | [RFCXXXX] | + | | | | + | 27 | Block1 | [RFCXXXX] | + | | | | + | 28 | Size2 | [RFCXXXX] | + +--------+--------+-----------+ + + Table 3: CoAP Option Numbers + + This draft adds the following response code to the CoAP Response + Codes registry of [RFC7252]: + + +------+---------------------------+-----------+ + | Code | Description | Reference | + +------+---------------------------+-----------+ + | 2.31 | Continue | [RFCXXXX] | + | | | | + | 4.08 | Request Entity Incomplete | [RFCXXXX] | + +------+---------------------------+-----------+ + + Table 4: CoAP Response Codes + +7. Security Considerations + + Providing access to blocks within a resource may lead to surprising + vulnerabilities. Where requests are not implemented atomically, an + attacker may be able to exploit a race condition or confuse a server + by inducing it to use a partially updated resource representation. + Partial transfers may also make certain problematic data invisible to + intrusion detection systems; it is RECOMMENDED that an intrusion + detection system (IDS) that analyzes resource representations + transferred by CoAP implement the Block options to gain access to + entire resource representations. Still, approaches such as + transferring even-numbered blocks on one path and odd-numbered blocks + on another path, or even transferring blocks multiple times with + different content and obtaining a different interpretation of + temporal order at the IDS than at the server, may prevent an IDS from + seeing the whole picture. These kinds of attacks are well understood + from IP fragmentation and TCP segmentation; CoAP does not add + fundamentally new considerations. + + + +Bormann & Shelby Expires September 10, 2015 [Page 29] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + Where access to a resource is only granted to clients making use of + 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. As a related consideration, where 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. + + 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, for which the usual + considerations apply. + +7.1. Mitigating Resource Exhaustion Attacks + + Certain block-wise requests may induce the server to create state, + e.g. to create a snapshot for the block-wise GET of a fast-changing + resource to enable consistent access to the same version of a + resource for all blocks, or to create temporary resource + representations that are collected until 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 is drowned + out by other state-creating requests. Wherever possible, servers + should therefore minimize the opportunities to create state for + untrusted sources, e.g. 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), for instance because + there is 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. + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 30] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +7.2. Mitigating Amplification Attacks + + [RFC7252] discusses the susceptibility of CoAP end-points 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. With this, e.g., 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, considerably reducing the + amplification provided. + +8. Acknowledgements + + Much of the content of this draft is the result of discussions with + the [RFC7252] authors, and via many CoRE WG discussions. + + Charles Palmer provided extensive editorial comments to a previous + version of this draft, some of which the authors hope to have covered + in this version. Esko Dijk reviewed a more recent version, leading + to a number of further editorial improvements, a solution to the 4.13 + ambiguity problem, and the section about combining Block and + multicast. 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. + + Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of + the Size Option, which has informed this draft. 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. + +9. References + +9.1. Normative References + + [I-D.ietf-core-observe] + Hartke, K., "Observing Resources in CoAP", draft-ietf- + core-observe-16 (work in progress), December 2014. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, June 2014. + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 31] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + +9.2. Informative References + + [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, August 2007. + + [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, + "Transmission of IPv6 Packets over IEEE 802.15.4 + Networks", RFC 4944, September 2007. + + [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link + Format", RFC 6690, August 2012. + + [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for + Constrained-Node Networks", RFC 7228, May 2014. + + [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol + (HTTP/1.1): Message Syntax and Routing", RFC 7230, June + 2014. + + [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext + Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, + June 2014. + +Authors' Addresses + + Carsten Bormann + Universitaet Bremen TZI + Postfach 330440 + Bremen D-28359 + Germany + + Phone: +49-421-218-63921 + Email: cabo@tzi.org + + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 32] + +Internet-Draft Block-wise transfers in CoAP March 2015 + + + Zach Shelby (editor) + ARM + 150 Rose Orchard + San Jose, CA 95134 + USA + + Phone: +1-408-203-9434 + Email: zach.shelby@arm.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Bormann & Shelby Expires September 10, 2015 [Page 33] |