--- 1/draft-ietf-core-block-11.txt 2013-06-27 15:14:23.449136065 +0100 +++ 2/draft-ietf-core-block-12.txt 2013-06-27 15:14:23.521137738 +0100 @@ -1,30 +1,30 @@ CoRE Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Standards Track Z. Shelby, Ed. -Expires: October 01, 2013 Sensinode - March 30, 2013 +Expires: December 29, 2013 Sensinode + June 27, 2013 Blockwise transfers in CoAP - draft-ietf-core-block-11 + draft-ietf-core-block-12 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 -\u002D 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. + 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 @@ -35,79 +35,79 @@ 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. The present revision -11 fixes one example and adds the text and examples about the Block/Observe interaction, taken from -observe. It also adds a couple of formatting bugs from the new xml2rfc. The "grand rewrite" is next. -Status of This Memo +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/. 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 October 01, 2013. + This Internet-Draft will expire on December 29, 2013. Copyright Notice Copyright (c) 2013 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 Block 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 . . . . . . . . . . . . . . . . . 11 - 2.6. Combining Blockwise Transfers with the Observe Option . . 12 - 2.7. Block2 and Initiative . . . . . . . . . . . . . . . . . . 13 - 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 13 - 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 16 - 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 18 - 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 20 - 4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 23 - 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 24 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 - 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 26 - 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 27 - 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 - 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 - 9.1. Normative References . . . . . . . . . . . . . . . . . . 28 - 9.2. Informative References . . . . . . . . . . . . . . . . . 28 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6 + 2.1. The Block 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 Blockwise Transfers with the Observe Option . . 13 + 2.7. Block2 and Initiative . . . . . . . . . . . . . . . . . . 14 + 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15 + 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18 + 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20 + 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . . 22 + 4. The Size Options . . . . . . . . . . . . . . . . . . . . . . . 26 + 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 28 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 + 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 31 + 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 32 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 34 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 34 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35 1. Introduction The CoRE WG is tasked with standardizing an Application Protocol for Constrained Networks/Nodes, CoAP. This protocol is intended to provide RESTful [REST] services not unlike HTTP [RFC2616], 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. @@ -233,21 +233,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 [I-D.ietf-core-coap], 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 -\u002D see + their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see section "Payload" of [I-D.ietf-core-coap]). (As a memory aid: Block_1_ pertains to the payload of the _1st_ part of the request-response exchange, i.e. the request, and Block_2_ pertains to the payload of the _2nd_ part of the request-response exchange, i.e. the response.) 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 block-wise payload forms @@ -343,24 +343,24 @@ 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 -\u002D 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.) + 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 @@ -1004,84 +1002,89 @@ | | Block2: 2/0/64 | | Observe: 62444 | | Max-Age: 60 | | Payload: [27 bytes] | | +- - ->| Header: 0x6000afa0 | | Figure 13: Observe sequence with early negotiation -4. The Size Option +4. The Size 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. - The Size Option may be used for three purposes: + 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. + + 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. + 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. - - In the latter two cases ("size indication"), the value of the option - is the current estimate, measured in bytes. + representation, measured in bytes ("size indication"). - A size request can be easily distinguished from a size indication, as - the third case is not useful for a GET or DELETE, and an actual size - indication of 0 would either be overridden by the actual size of the - payload for a PUT or POST or would not be useful. + o in a 4.13 response, to indicate the maximum size that would have + been acceptable [I-D.ietf-core-coap], measured in bytes. - Apart from conveying/asking for size information, the Size option has - 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). + 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 Option is "elective", i.e., a client MUST be prepared for - the server to ignore the size estimate request. The Size Option MUST - NOT occur more than once. + 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. - +------+---+---+---+---+------+--------+--------+---------+ + +------+---+---+---+---+-------+--------+--------+---------+ | Type | C | U | N | R | Name | Format | Length | Default | - +------+---+---+---+---+------+--------+--------+---------+ - | 28 | - | - | N | - | Size | uint | 0-4 B | (none) | - +------+---+---+---+---+------+--------+--------+---------+ + +------+---+---+---+---+-------+--------+--------+---------+ + | 60 | | | x | | Size1 | uint | 0-4 B | (none) | + | | | | | | | | | | + | 28 | | | x | | Size2 | uint | 0-4 B | (none) | + +------+---+---+---+---+-------+--------+--------+---------+ + + Table 2: Size Option Numbers Implementation Notes: o As a quality of implementation consideration, blockwise 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 blockwise 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. - o Size is neither critical nor unsafe, and is marked as No-Cache- - Key. + 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. 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 @@ -1131,37 +1134,39 @@ 6. IANA Considerations This draft adds the following option numbers to the CoAP Option Numbers registry of [I-D.ietf-core-coap]: +--------+--------+-----------+ | Number | Name | Reference | +--------+--------+-----------+ | 23 | Block2 | [RFCXXXX] | | | | | - | 28 | Size | [RFCXXXX] | - | | | | | 27 | Block1 | [RFCXXXX] | + | | | | + | 28 | Size2 | [RFCXXXX] | + | | | | + | 60 | Size1 | [RFCXXXX] | +--------+--------+-----------+ - Table 2: CoAP Option Numbers + Table 3: CoAP Option Numbers This draft adds the following response code to the CoAP Response Codes registry of [I-D.ietf-core-coap]: +------+--------------------------------+-----------+ | Code | Description | Reference | +------+--------------------------------+-----------+ | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | +------+--------------------------------+-----------+ - Table 3: CoAP Response Codes + 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 @@ -1204,29 +1210,29 @@ 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), e.g. because there - is application layer semantics that can be used for mitigation or + fragmentation, adaptation layer fragmentation), e.g. 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 blockwise - transfers in an expedient way to minimize the likelihood of running - into such a timeout. + MAY want to clean up accumulated state by timing it out (cf. response + code 4.08), and clients SHOULD be prepared to run blockwise transfers + in an expedient way to minimize the likelihood of running into such a + timeout. 7.2. Mitigating Amplification Attacks [I-D.ietf-core-coap] 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 @@ -1248,46 +1254,47 @@ 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. 9. References 9.1. Normative References [I-D.ietf-core-coap] Shelby, Z., Hartke, K., and C. Bormann, "Constrained - Application Protocol (CoAP)", draft-ietf-core-coap-14 - (work in progress), March 2013. + Application Protocol (CoAP)", draft-ietf-core-coap-17 + (work in progress), May 2013. [I-D.ietf-core-observe] - Hartke, K., "Observing Resources in CoAP", draft-ietf- - core-observe-08 (work in progress), February 2013. + Hartke, K., "Observing Resources in CoAP", + draft-ietf-core-observe-08 (work in progress), + February 2013. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 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, . [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. + Overview, Assumptions, Problem Statement, and Goals", + RFC 4919, August 2007. [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, August 2012. Authors' Addresses Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359