--- 1/draft-ietf-core-block-19.txt 2016-04-29 04:16:07.572074064 -0700 +++ 2/draft-ietf-core-block-20.txt 2016-04-29 04:16:07.648075966 -0700 @@ -1,19 +1,19 @@ CoRE Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Standards Track Z. Shelby, Ed. -Expires: September 22, 2016 ARM - March 21, 2016 +Expires: October 31, 2016 ARM + April 29, 2016 Block-wise transfers in CoAP - draft-ietf-core-block-19 + draft-ietf-core-block-20 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 @@ -45,70 +45,70 @@ 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/. 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 22, 2016. + This Internet-Draft will expire on October 31, 2016. 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) 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.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 6 + 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7 + 2.3. Block Options in Requests and Responses . . . . . . . . . 9 + 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 11 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.8. Combining Block2 with Multicast . . . . . . . . . . . . . 15 + 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 15 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 + 2.10. Caching Considerations . . . . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . 28 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 - 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 30 - 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 31 - 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 - 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 - 9.1. Normative References . . . . . . . . . . . . . . . . . . 32 - 9.2. Informative References . . . . . . . . . . . . . . . . . 32 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 + 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 17 + 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 21 + 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 22 + 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 24 + 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 27 + 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 29 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 + 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 31 + 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 32 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 + 9.1. Normative References . . . . . . . . . . . . . . . . . . 33 + 9.2. Informative References . . . . . . . . . . . . . . . . . 33 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 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 @@ -145,20 +145,40 @@ 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.) + Block-wise transfers are realized as combinations of exchanges, each + of which is performed according to the CoAP base protocol [RFC7252]. + Each 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]; additional security considerations then + apply to the transfers as a whole, see Section 7). The present + specification minimizes the constraints it adds to those base + exchanges; however, not all variants of using CoAP are very useful + inside a block-wise transfer (e.g., 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, the present specification also does not remove any of the + constraints posed by the base specification it is strictly layered on + top of; e.g., back-to-back packets are limited by 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 cannot + send/solicit more traffic than a client could be sending to the same + server without the block-wise mode. + 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. @@ -211,33 +231,39 @@ and the number 2 ("Block2", "Size2") 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. + 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 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). + the last one) will be of 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 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 + +-----+---+---+---+---+--------+--------+--------+---------+ | 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 @@ -242,21 +268,21 @@ 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 + bearing responses (2.01, 2.02, 2.04, 2.05 -- see Section 5.5 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"). @@ -416,20 +442,25 @@ 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. @@ -460,47 +491,47 @@ 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 - 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 + requests in a single block-wise transfer will ultimately converge on + using the same size, except 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 (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 + conjunction with the ETag Option ([RFC7252], Section 5.10.6), 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, 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 @@ -571,21 +602,21 @@ 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 + 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 [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. @@ -667,23 +699,26 @@ 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. + (Note that one reason for not having the necessary blocks at hand may + be a Content-Format mismatch, see Section 2.3.) + 2.9.3. 4.13 Request Entity Too Large - In [RFC7252], section 5.9.2.9, the response code 4.13 (Request Entity + 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 @@ -1405,20 +1440,28 @@ insisted on a more systematic coverage of the options and response code. Qin Wu provided a review for the IETF Operational 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 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. + The IESG reviewers provided very useful comments. Spencer Dawkins + even suggested new text. Mirja Kuehlewind and he insisted on being + more explicit about the layering of block-wise transfers on top of + the base protocol. Ben Campbell helped untangling some MUST/SHOULD + soup. Comments by Alexey Melnikov, as well as the gen-art review by + Jouni Korhonen and the ops-dir review by Qin Wu, caused further + improvements to the text. + 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained