--- 1/draft-ietf-core-block-09.txt 2012-10-21 14:14:29.429760522 +0200 +++ 2/draft-ietf-core-block-10.txt 2012-10-21 14:14:29.497759113 +0200 @@ -1,19 +1,19 @@ CoRE Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Standards Track Z. Shelby, Ed. -Expires: February 15, 2013 Sensinode - August 14, 2012 +Expires: April 24, 2013 Sensinode + October 21, 2012 Blockwise transfers in CoAP - draft-ietf-core-block-09 + draft-ietf-core-block-10 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 February 15, 2013. + This Internet-Draft will expire on April 24, 2013. 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,34 +69,33 @@ 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. Structure of a Block Option . . . . . . . . . . . . . . . 7 2.3. Block Options in Requests and Responses . . . . . . . . . 9 - 2.4. Using the Block Options . . . . . . . . . . . . . . . . . 10 + 2.4. Using the Block Options . . . . . . . . . . . . . . . . . 11 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 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 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 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. @@ -201,27 +200,27 @@ 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 Block Options - +------+----------+--------+--------+--------+---------------+ - | Type | C/E | Name | Format | Length | Default | - +------+----------+--------+--------+--------+---------------+ - | 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) | - | | | | | | | - | 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) | - +------+----------+--------+--------+--------+---------------+ + +------+---+---+---+---+--------+--------+--------+---------+ + | Type | C | U | N | R | Name | Format | Length | Default | + +------+---+---+---+---+--------+--------+--------+---------+ + | 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) | + | | | | | | | | | | + | 27 | C | U | - | - | Block1 | uint | 0-3 B | (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 [I-D.ietf-core-coap], Block1 is useful with the payload-bearing POST and PUT requests and their @@ -295,25 +294,20 @@ 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 block being transferred. - The default value of both the Block1 and the Block2 Option is zero, - indicating that the current block is the first and only block of the - transfer (block number 0, M bit not set); however, there is no - explicit size implied by this default value. - More specifically, within the option value of a Block1 or Block2 Option, the meaning of the option fields is defined as follows: NUM: Block Number. The block number is a variable-size (4, 12, or 20 bit) unsigned integer (uint, see Appendix A of [I-D.ietf-core-coap]) indicating the block number being requested or provided. Block number 0 indicates the first block of a body. M: More Flag (not last block). For descriptive usage, this flag, if unset, indicates that the payload in this message is the last @@ -326,20 +320,32 @@ SZX: Block Size. The block size is a three-bit unsigned integer indicating the size of a block to the power of two. Thus block size = 2**(SZX + 4). The allowed values of SZX are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the maximum is 2**(6+4) = 1024. The value 7 for SZX (which would indicate a block size of 2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00 Bad Request response code upon reception in a request. + 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. + (Note that, as for any uint, the 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 (e.g., a 2.05 response for GET), or a Block1 Option in a request (e.g., PUT or POST): * The NUM field in the option value describes what block number is contained in the payload of this message. @@ -794,41 +800,44 @@ 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). 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) | - +------+----------+------+--------+--------+---------+ + +------+---+---+---+---+------+--------+--------+---------+ + | Type | C | U | N | R | Name | Format | Length | Default | + +------+---+---+---+---+------+--------+--------+---------+ + | 28 | - | - | N | - | 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. + o Size is neither critical nor unsafe, and is 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 request once the first block has been requested and could then @@ -875,25 +884,25 @@ creating additional state, the need for which we want to avoid.) 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] | + | 23 | Block2 | [RFCXXXX] | | | | | - | 18 | Size | [RFCXXXX] | + | 28 | Size | [RFCXXXX] | | | | | - | 19 | Block1 | [RFCXXXX] | + | 27 | 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 | +------+--------------------------------+-----------+ @@ -982,33 +991,34 @@ 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. 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 as well as a solution - to the 4.13 ambiguity problem. + to the 4.13 ambiguity problem. Markus Becker proposed getting rid of + an ill-conceived default value for the Block2 and Block1 options. Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of the Size Option, which has informed this draft. 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-11 (work in progress), July 2012. + draft-ietf-core-coap-12 (work in progress), October 2012. [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 @@ -1019,36 +1029,20 @@ 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. [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, August 2012. -Appendix A. Historical Note - - (This appendix to be deleted by the RFC editor.) - - An earlier version of this draft used a single option: - - +------+----------+-------+--------+--------+---------------+ - | Type | C/E | Name | Format | Length | Default | - +------+----------+-------+--------+--------+---------------+ - | 13 | Critical | Block | uint | 1-3 B | 0 (see below) | - +------+----------+-------+--------+--------+---------------+ - - Note that this option number has since been reallocated in - [I-D.ietf-core-coap]; no backwards compatibility is provided after - July 1st, 2011. - Authors' Addresses Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Email: cabo@tzi.org