--- 1/draft-ietf-core-block-07.txt 2012-02-15 18:13:58.750702953 +0100 +++ 2/draft-ietf-core-block-08.txt 2012-02-15 18:13:58.798671394 +0100 @@ -1,19 +1,19 @@ CoRE Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Standards Track Z. Shelby, Ed. -Expires: July 30, 2012 Sensinode - January 27, 2012 +Expires: August 18, 2012 Sensinode + February 15, 2012 Blockwise transfers in CoAP - draft-ietf-core-block-07 + draft-ietf-core-block-08 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,21 +45,21 @@ 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 July 30, 2012. + This Internet-Draft will expire on August 18, 2012. Copyright Notice Copyright (c) 2012 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 @@ -69,31 +69,32 @@ the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6 2.2. Using the Block Options . . . . . . . . . . . . . . . . . 10 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 4. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 20 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 - 6.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 23 - 6.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 24 - 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 - 8.1. Normative References . . . . . . . . . . . . . . . . . . . 26 - 8.2. Informative References . . . . . . . . . . . . . . . . . . 26 - Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 27 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 + 4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20 + 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 + 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25 + 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 28 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 28 + Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 29 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 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. @@ -475,21 +476,24 @@ In a blockwise 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. If not all previous blocks are available at the server at this time, the transfer fails and error code 4.08 (Request Entity Incomplete) MUST be returned. 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. + 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 the Block1 than requested is a + hint to try a smaller SZX.) If multiple concurrently proceeding block-wise request payload transfer (e.g., PUT or POST) operations are possible, the requester SHOULD use the Token Option to clearly separate the different sequences. In this case, when reassembling the representation from the blocks being exchanged to enable atomic processing, the reassembler MUST compare any Token Options present (and, as usual, taking an absent Token Option to default to the empty Token). If atomic processing is not desired, there is no need to process the Token Option (but it is still returned in the response as usual). @@ -524,23 +528,23 @@ | <------ 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 blockwise GET In the second example (Figure 3), the client anticipates the blockwise transfer (e.g., because of a size indication in the link- - format description) and sends a size proposal. All ACK messages - except for the last carry 64 bytes of payload; the last one carries - between 1 and 64 bytes. + format description [I-D.ietf-core-link-format]) and sends a 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 | @@ -746,21 +750,77 @@ | <------ CON [MID=4714], 2.01 Created, 37a, 2/2/1/128 | | | | ACK [MID=4714], 0, 2/2/1/128 ------> | | | | <------ CON [MID=4715], 2.01 Created, 37a, 2/3/0/128 | | | | ACK [MID=4715], 0, 2/3/0/128 ------> | Figure 10: Atomic blockwise POST with separate blockwise response -4. HTTP Mapping Considerations +4. The Size Option + + 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 + [I-D.ietf-core-link-format]. 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: + + o in a request, to ask the server to provide a size estimate in the + 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. + + o in a request carrying a Block1 Option, to indicate the current + estimate the client has of the total size of the resource + representation. + + 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. + + In the latter two cases ("size indication"), the value of the option + is the current estimate, measured in bytes. + + 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. + + +------+----------+------+--------+--------+---------+ + | Type | C/E | Name | Format | Length | Default | + +------+----------+------+--------+--------+---------+ + | 18 | Elective | Size | uint | 0-4 B | (none) | + +------+----------+------+--------+--------+---------+ + + 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. + +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 request once the first block has been requested and could then fulfill all further block requests out of its cache. A constrained @@ -798,47 +858,49 @@ 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.) -5. IANA Considerations +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 | +--------+--------+-----------+ | 17 | Block2 | [RFCXXXX] | | | | | + | 18 | Size | [RFCXXXX] | + | | | | | 19 | Block1 | [RFCXXXX] | +--------+--------+-----------+ Table 2: 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 -6. Security Considerations +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 @@ -852,21 +914,25 @@ Where access to a resource is only granted to clients making use of a specific security association, 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. -6.1. Mitigating Resource Exhaustion Attacks + 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 blockwise requests may induce the server to create state, e.g. to create a snapshot for the blockwise 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 @@ -881,60 +947,68 @@ 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. -6.2. Mitigating Amplification Attacks +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 block) instead of a 1016-byte response, considerably reducing the amplification provided. -7. Acknowledgements +8. Acknowledgements Much of the content of this draft is the result of discussions with the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. 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. -8. References + Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of + the Size Option, which has informed this draft. -8.1. Normative References +9. References + +9.1. Normative References [I-D.ietf-core-coap] Shelby, Z., Hartke, K., Bormann, C., and B. Frank, "Constrained Application Protocol (CoAP)", draft-ietf-core-coap-08 (work in progress), October 2011. [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. -8.2. Informative References +9.2. Informative References + + [I-D.ietf-core-link-format] + Shelby, Z., "CoRE Link Format", + draft-ietf-core-link-format-11 (work in progress), + January 2012. [REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 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. Appendix A. Historical Note