draft-ietf-core-block-13.txt   draft-ietf-core-block-14.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: April 23, 2014 Sensinode Expires: April 24, 2014 Sensinode
October 20, 2013 October 21, 2013
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-13 draft-ietf-core-block-14
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 will need to transfer larger payloads -- for instance, for
firmware updates. With HTTP, TCP does the grunt work of slicing firmware updates. With HTTP, TCP does the grunt work of slicing
large payloads up into multiple packets and ensuring that they all large payloads up into multiple packets and ensuring that they all
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 April 23, 2014. This Internet-Draft will expire on April 24, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
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 . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4
2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 5 2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6
2.3. Block Options in Requests and Responses . . . . . . . . . 8 2.3. Block Options in Requests and Responses . . . . . . . . . 8
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 9 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11
2.6. Combining Blockwise Transfers with the Observe Option . . 12 2.6. Combining Blockwise Transfers with the Observe Option . . 12
2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13
2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 14 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 16 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 18 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 19 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4. The Size Options . . . . . . . . . . . . . . . . . . . . . . 22 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 23 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20
7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 21
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 26 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 24
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 26 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 25
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 7. Security Considerations . . . . . . . . . . . . . . . . . . . 28
9.1. Normative References . . . . . . . . . . . . . . . . . . 27 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 28
9.2. Informative References . . . . . . . . . . . . . . . . . 28 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.1. Normative References . . . . . . . . . . . . . . . . . . 30
9.2. Informative References . . . . . . . . . . . . . . . . . 30
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 5, line 33 skipping to change at page 5, line 37
In most cases, all blocks being transferred for a body will be of the In most cases, all blocks being transferred for a body will be of the
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 Block2 and Block1 Options
+------+---+---+---+---+--------+--------+--------+---------+ +------+---+---+---+---+--------+--------+--------+---------+
| Type | C | U | N | R | Name | Format | Length | Default | | Type | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+--------+--------+--------+---------+ +------+---+---+---+---+--------+--------+--------+---------+
| 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) | | 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) |
| | | | | | | | | | | | | | | | | | | |
| 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) | | 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) |
+------+---+---+---+---+--------+--------+--------+---------+ +------+---+---+---+---+--------+--------+--------+---------+
Table 1: Block Option Numbers Table 1: Block Option Numbers
skipping to change at page 11, line 40 skipping to change at page 12, line 6
a new message-layer transaction and requires a new Message ID. a new message-layer transaction and requires a new Message ID.
(Because of the uncertainty whether the request or the (Because of the uncertainty whether the request or the
acknowledgement was lost, this strategy is useful mostly for acknowledgement was lost, this strategy is useful mostly for
idempotent requests.) idempotent requests.)
In a blockwise transfer of a request payload (e.g., a PUT or POST) 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 that is intended to be implemented in an atomic fashion at the
server, the actual creation/replacement takes place at the time 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, final block, i.e. a block with the M bit unset in the Block1 Option,
is received. In this case, all success responses to non-final blocks is received. In this case, all success responses to non-final blocks
carry the response code 2.31 (Continue). If not all previous blocks carry the response code 2.31 (Continue, Section 2.9.1). If not all
are available at the server at the time of processing the final previous blocks are available at the server at the time of processing
block, the transfer fails and error code 4.08 (Request Entity the final block, the transfer fails and error code 4.08 (Request
Incomplete) MUST be returned. A server MAY also return a 4.08 error Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY
code for any (final or non-final) Block1 transfer that is not in also return a 4.08 error code for any (final or non-final) Block1
sequence; clients that do not have specific mechanisms to handle this transfer that is not in sequence; clients that do not have specific
case therefore SHOULD always start with block zero and send the mechanisms to handle this case therefore SHOULD always start with
following blocks in order. block zero and send the following blocks in order.
The error code 4.13 (Request Entity Too Large) can be returned at any 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 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 blocks for a block-wise request payload transfer that it would intend
to implement in an atomic fashion. (Note that a 4.13 response to a to implement in an atomic fashion. (Note that a 4.13 response to a
request that does not employ Block1 is a hint for the client to try 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 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.) option than requested is a hint to try a smaller SZX.)
The Block1 option provides no way for a single endpoint to perform The Block1 option provides no way for a single endpoint to perform
skipping to change at page 13, line 16 skipping to change at page 13, line 30
2.7. Combining Block1 and Block2 2.7. Combining Block1 and Block2
In PUT and particularly in POST exchanges, both the request body and In PUT and particularly in POST exchanges, both the request body and
the response body may be large enough to require the use of block- the response body may be large enough to require the use of block-
wise transfers. First, the Block1 transfer of the request body wise transfers. First, the Block1 transfer of the request body
proceeds as usual. In the exchange of the last slice of this block- proceeds as usual. In the exchange of the last slice of this block-
wise transfer, the response carries the first slice of the Block2 wise transfer, the response carries the first slice of the Block2
transfer (NUM is zero). To continue this Block2 transfer, the client transfer (NUM is zero). To continue this Block2 transfer, the client
continues to send requests similar to the requests in the Block1 continues to send requests similar to the requests in the Block1
phase, bute leaves out the Block1 options and includes a Block2 phase, but leaves out the Block1 options and includes a Block2
request option with non-zero NUM. request option with non-zero NUM.
Block2 transfers that retrieve the response body for a request that Block2 transfers that retrieve the response body for a request that
used Block1 MUST be performed in sequential order. used Block1 MUST be performed in sequential order.
2.8. Combining Block2 with Multicast 2.8. Combining Block2 with Multicast
A client can use the Block2 option in a multicast GET request with A client can use the Block2 option in a multicast GET request with
NUM = 0 to aid in limiting the size of the response. NUM = 0 to aid in limiting the size of the response.
skipping to change at page 13, line 39 skipping to change at page 14, line 5
limit the size of the response. limit the size of the response.
In both cases, the client retrieves any further blocks using unicast In both cases, the client retrieves any further blocks using unicast
exchanges; in the unicast requests, the client SHOULD heed any block exchanges; in the unicast requests, the client SHOULD heed any block
size preferences indicated by the server in the response to the size preferences indicated by the server in the response to the
multicast request. multicast request.
Other uses of the Block options in conjunction with multicast Other uses of the Block options in conjunction with multicast
messages are for further study. messages are for further study.
3. Examples 2.9. Response Codes
Two response codes are defined by this specification beyond those
already defined in [I-D.ietf-core-coap], and another response code is
extended in its meaning.
TODO: Add or appropriate useful response codes for Block2 problems
(overshoot beyond end of representation, unsupported out-of-order
access).
2.9.1. 2.31 Continue
This new success status code indicates that the transfer of this
block of the request body was successful and that the serve
encourages sending further blocks, but that a final outcome of the
whole block-wise request cannot yet be determined. No payload is
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.
2.9.3. 4.13 Request Entity Too Large
In [I-D.ietf-core-coap], 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". [I-D.ietf-core-coap] 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
the server to return a 4.13 response to a request that does not
employ Block1 as a hint for the client to try sending Block1.
Finally, a 4.13 response to a request with a Block1 option (control
usage, see Section 2.3) where the response carries a smaller SZX in
its Block1 option is a hint to try that smaller SZX.
3. Examples
This section gives a number of short examples with message flows for This section gives a number of short examples with message flows for
a block-wise GET, and for a PUT or POST. These examples demonstrate a block-wise GET, and for a PUT or POST. These examples demonstrate
the basic operation, the operation in the presence of the basic operation, the operation in the presence of
retransmissions, and examples for the operation of the block size retransmissions, and examples for the operation of the block size
negotiation. negotiation.
In all these examples, a Block option is shown in a decomposed way In all these examples, a Block option is shown in a decomposed way
indicating the kind of Block option (1 or 2) followed by a colon, and indicating the kind of Block option (1 or 2) followed by a colon, and
then the block number (NUM), more bit (M), and block size exponent then the block number (NUM), more bit (M), and block size exponent
(2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 (2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33
skipping to change at page 22, line 21 skipping to change at page 24, line 28
| | Block2: 4/0/64 | | Block2: 4/0/64
| | | |
|<-----+ Header: 2.05 0x61451638 |<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc | 2.05 | Token: 0xfc
| | Block2: 4/0/64 | | Block2: 4/0/64
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [53 bytes] | | Payload: [53 bytes]
Figure 13: Observe sequence with early negotiation Figure 13: Observe sequence with early negotiation
4. The Size Options 4. The Size2 and Size1 Options
In many cases when transferring a large resource representation block In many cases when transferring a large resource representation block
by block, it is advantageous to know the total size early in the by block, it is advantageous to know the total size early in the
process. Some indication may be available from the maximum size process. Some indication may be available from the maximum size
estimate attribute "sz" provided in a resource description [RFC6690]. estimate attribute "sz" provided in a resource description [RFC6690].
However, the size may vary dynamically, so a more up-to-date However, the size may vary dynamically, so a more up-to-date
indication may be useful. indication may be useful.
This specification defines two CoAP Options, Size1 for indicating the This specification defines two CoAP Options, Size1 for indicating the
size of the representation transferred in requests, and Size2 for size of the representation transferred in requests, and Size2 for
skipping to change at page 27, line 26 skipping to change at page 29, line 45
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, a solution to the 4.13 to a number of further editorial improvements, a solution to the 4.13
ambiguity problem, and the section about combining Block and ambiguity problem, and the section about combining Block and
multicast. Markus Becker proposed getting rid of an ill-conceived multicast. Markus Becker proposed getting rid of an ill-conceived
default value for the Block2 and Block1 options. default value for the Block2 and Block1 options. Peter Bigot
insisted on a more systematic coverage of the options and response
code.
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. Klaus Hartke wrote the Size Option, which has informed this draft. Klaus Hartke wrote
some of the text describing the interaction of Block2 with Observe. some of the text describing the interaction of Block2 with Observe.
Matthias Kovatsch provided a number of significant simplifications of Matthias Kovatsch provided a number of significant simplifications of
the protocol. the protocol.
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., and C. Bormann, "Constrained Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18 Application Protocol (CoAP)", draft-ietf-core-coap-18
 End of changes. 14 change blocks. 
35 lines changed or deleted 87 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/