draft-ietf-core-block-09.txt   draft-ietf-core-block-10.txt 
CoRE Working Group C. Bormann CoRE Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track Z. Shelby, Ed. Intended status: Standards Track Z. Shelby, Ed.
Expires: February 15, 2013 Sensinode Expires: April 24, 2013 Sensinode
August 14, 2012 October 21, 2012
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-09 draft-ietf-core-block-10
Abstract Abstract
CoAP is a RESTful transfer protocol for constrained nodes and CoAP is a RESTful transfer protocol for constrained nodes and
networks. Basic CoAP messages work well for the small payloads we networks. Basic CoAP messages work well for the small payloads we
expect from temperature sensors, light switches, and similar expect from temperature sensors, light switches, and similar
building-automation devices. Occasionally, however, applications building-automation devices. Occasionally, however, applications
will need to transfer larger payloads -- for instance, for firmware will need to transfer larger payloads -- for instance, for firmware
updates. With HTTP, TCP does the grunt work of slicing large updates. With HTTP, TCP does the grunt work of slicing large
payloads up into multiple packets and ensuring that they all arrive payloads up into multiple packets and ensuring that they all arrive
skipping to change at page 2, line 10 skipping to change at page 2, line 10
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 12 skipping to change at page 3, line 12
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6
2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7
2.3. Block Options in Requests and Responses . . . . . . . . . 9 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 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20 4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.1. Normative References . . . . . . . . . . . . . . . . . . . 28 9.1. Normative References . . . . . . . . . . . . . . . . . . . 28
9.2. Informative References . . . . . . . . . . . . . . . . . . 28 9.2. Informative References . . . . . . . . . . . . . . . . . . 28
Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 29 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
1. Introduction 1. Introduction
The CoRE WG is tasked with standardizing an Application Protocol for The CoRE WG is tasked with standardizing an Application Protocol for
Constrained Networks/Nodes, CoAP. This protocol is intended to Constrained Networks/Nodes, CoAP. This protocol is intended to
provide RESTful [REST] services not unlike HTTP [RFC2616], while provide RESTful [REST] services not unlike HTTP [RFC2616], while
reducing the complexity of implementation as well as the size of reducing the complexity of implementation as well as the size of
packets exchanged in order to make these services useful in a highly packets exchanged in order to make these services useful in a highly
constrained network of themselves highly constrained nodes. constrained network of themselves highly constrained nodes.
skipping to change at page 6, line 40 skipping to change at page 6, line 40
same size. The block size is not fixed by the protocol. To keep 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 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 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- (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 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 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). will still be indicated in the block size field of the Block option).
2.1. The Block Options 2.1. The Block Options
+------+----------+--------+--------+--------+---------------+ +------+---+---+---+---+--------+--------+--------+---------+
| Type | C/E | Name | Format | Length | Default | | Type | C | U | N | R | Name | Format | Length | Default |
+------+----------+--------+--------+--------+---------------+ +------+---+---+---+---+--------+--------+--------+---------+
| 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) | | 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) |
| | | | | | | | | | | | | | | | |
| 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) | | 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) |
+------+----------+--------+--------+--------+---------------+ +------+---+---+---+---+--------+--------+--------+---------+
Table 1: Block Option Numbers Table 1: Block Option Numbers
Both Block1 and Block2 options can be present both in request and Both Block1 and Block2 options can be present both in request and
response messages. In either case, the Block1 Option pertains to the response messages. In either case, the Block1 Option pertains to the
request payload, and the Block2 Option pertains to the response request payload, and the Block2 Option pertains to the response
payload. payload.
Hence, for the methods defined in [I-D.ietf-core-coap], Block1 is Hence, for the methods defined in [I-D.ietf-core-coap], Block1 is
useful with the payload-bearing POST and PUT requests and their useful with the payload-bearing POST and PUT requests and their
skipping to change at page 8, line 45 skipping to change at page 8, line 45
The option value divided by sixteen (the NUM field) is the sequence The option value divided by sixteen (the NUM field) is the sequence
number of the block currently being transferred, starting from zero. number of the block currently being transferred, starting from zero.
The current transfer is therefore about the "size" bytes starting at The current transfer is therefore about the "size" bytes starting at
byte "NUM << (SZX + 4)". byte "NUM << (SZX + 4)".
Implementation note: As an implementation convenience, "(val & ~0xF) Implementation note: As an implementation convenience, "(val & ~0xF)
<< (val & 7)", i.e. the option value with the last 4 bits masked << (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 out, shifted to the left by the value of SZX, gives the byte
position of the block being transferred. 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 More specifically, within the option value of a Block1 or Block2
Option, the meaning of the option fields is defined as follows: Option, the meaning of the option fields is defined as follows:
NUM: Block Number. The block number is a variable-size (4, 12, or NUM: Block Number. The block number is a variable-size (4, 12, or
20 bit) unsigned integer (uint, see Appendix A of 20 bit) unsigned integer (uint, see Appendix A of
[I-D.ietf-core-coap]) indicating the block number being requested [I-D.ietf-core-coap]) indicating the block number being requested
or provided. Block number 0 indicates the first block of a body. or provided. Block number 0 indicates the first block of a body.
M: More Flag (not last block). For descriptive usage, this flag, if M: More Flag (not last block). For descriptive usage, this flag, if
unset, indicates that the payload in this message is the last unset, indicates that the payload in this message is the last
skipping to change at page 9, line 28 skipping to change at page 9, line 23
SZX: Block Size. The block size is a three-bit unsigned integer 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 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., 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 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 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 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 lead to a 4.00 Bad Request response code upon reception in a
request. 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 2.3. Block Options in Requests and Responses
The Block options are used in one of three roles: 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 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 2.05 response for GET), or a Block1 Option in a request (e.g., PUT
or POST): or POST):
* The NUM field in the option value describes what block number * The NUM field in the option value describes what block number
is contained in the payload of this message. is contained in the payload of this message.
skipping to change at page 20, line 46 skipping to change at page 20, line 46
Apart from conveying/asking for size information, the Size option has Apart from conveying/asking for size information, the Size option has
no other effect on the processing of the request or response. If the 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 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 response, it should add a Block2 option to the request with a small
block size (e.g., setting SZX=0). block size (e.g., setting SZX=0).
The Size Option is "elective", i.e., a client MUST be prepared for 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 the server to ignore the size estimate request. The Size Option MUST
NOT occur more than once. NOT occur more than once.
+------+----------+------+--------+--------+---------+ +------+---+---+---+---+------+--------+--------+---------+
| Type | C/E | Name | Format | Length | Default | | Type | C | U | N | R | Name | Format | Length | Default |
+------+----------+------+--------+--------+---------+ +------+---+---+---+---+------+--------+--------+---------+
| 18 | Elective | Size | uint | 0-4 B | (none) | | 28 | - | - | N | - | Size | uint | 0-4 B | (none) |
+------+----------+------+--------+--------+---------+ +------+---+---+---+---+------+--------+--------+---------+
Implementation Notes: Implementation Notes:
o As a quality of implementation consideration, blockwise transfers o As a quality of implementation consideration, blockwise transfers
for which the total size considerably exceeds the size of one for which the total size considerably exceeds the size of one
block are expected to include size indications, whenever those can block are expected to include size indications, whenever those can
be provided without undue effort (preferably with the first block be provided without undue effort (preferably with the first block
exchanged). If the size estimate does not change, the indication exchanged). If the size estimate does not change, the indication
does not need to be repeated for every block. does not need to be repeated for every block.
o The end of a blockwise transfer is governed by the M bits in the o The end of a blockwise transfer is governed by the M bits in the
Block Options, _not_ by exhausting the size estimates exchanged. Block Options, _not_ by exhausting the size estimates exchanged.
o As usual for an option of type uint, the value 0 is best expressed 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. 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 5. HTTP Mapping Considerations
In this subsection, we give some brief examples for the influence the In this subsection, we give some brief examples for the influence the
Block options might have on intermediaries that map between CoAP and Block options might have on intermediaries that map between CoAP and
HTTP. HTTP.
For mapping CoAP requests to HTTP, the intermediary may want to map For mapping CoAP requests to HTTP, the intermediary may want to map
the sequence of block-wise transfers into a single HTTP transfer. the sequence of block-wise transfers into a single HTTP transfer.
E.g., for a GET request, the intermediary could perform the HTTP E.g., for a GET request, the intermediary could perform the HTTP
request once the first block has been requested and could then request once the first block has been requested and could then
skipping to change at page 24, line 13 skipping to change at page 24, line 13
creating additional state, the need for which we want to avoid.) creating additional state, the need for which we want to avoid.)
6. IANA Considerations 6. IANA Considerations
This draft adds the following option numbers to the CoAP Option This draft adds the following option numbers to the CoAP Option
Numbers registry of [I-D.ietf-core-coap]: Numbers registry of [I-D.ietf-core-coap]:
+--------+--------+-----------+ +--------+--------+-----------+
| Number | Name | Reference | | 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 Table 2: CoAP Option Numbers
This draft adds the following response code to the CoAP Response This draft adds the following response code to the CoAP Response
Codes registry of [I-D.ietf-core-coap]: Codes registry of [I-D.ietf-core-coap]:
+------+--------------------------------+-----------+ +------+--------------------------------+-----------+
| Code | Description | Reference | | Code | Description | Reference |
+------+--------------------------------+-----------+ +------+--------------------------------+-----------+
skipping to change at page 27, line 14 skipping to change at page 27, line 14
8. Acknowledgements 8. Acknowledgements
Much of the content of this draft is the result of discussions with 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. the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions.
Charles Palmer provided extensive editorial comments to a previous Charles Palmer provided extensive editorial comments to a previous
version of this draft, some of which the authors hope to have covered version of this draft, some of which the authors hope to have covered
in this version. Esko Dijk reviewed a more recent version, leading in this version. Esko Dijk reviewed a more recent version, leading
to a number of further editorial improvements as well as a solution 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 Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of
the Size Option, which has informed this draft. the Size Option, which has informed this draft.
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-core-coap] [I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank, Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)", "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 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
9.2. Informative References 9.2. Informative References
skipping to change at page 29, line 5 skipping to change at page 29, line 5
fielding_dissertation.pdf>. fielding_dissertation.pdf>.
[RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
over Low-Power Wireless Personal Area Networks (6LoWPANs): over Low-Power Wireless Personal Area Networks (6LoWPANs):
Overview, Assumptions, Problem Statement, and Goals", Overview, Assumptions, Problem Statement, and Goals",
RFC 4919, August 2007. RFC 4919, August 2007.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012. 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 Authors' Addresses
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org Email: cabo@tzi.org
 End of changes. 16 change blocks. 
45 lines changed or deleted 39 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/