draft-ietf-core-block-15.txt   draft-ietf-core-block-16.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: January 5, 2015 ARM Expires: April 30, 2015 ARM
July 04, 2014 October 27, 2014
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-15 draft-ietf-core-block-16
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 January 5, 2015. This Internet-Draft will expire on April 30, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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 2, line 35 skipping to change at page 2, line 35
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 . . . . . . . . . . . . . . . . . . . . 5 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 5
2.1. The Block2 and Block1 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 . . . . . . . . . . . . . . . . . 10 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 12
2.6. Combining Blockwise Transfers with the Observe Option . . 12 2.6. Combining Blockwise Transfers with the Observe Option . . 13
2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 14
2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 14
2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14
2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 15
2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 15
2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 15
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.10. Caching Considerations . . . . . . . . . . . . . . . . . 15
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 19 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 16
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 20
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 22 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 21
4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 25 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 23
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 26 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 26
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 27
7. Security Considerations . . . . . . . . . . . . . . . . . . . 28 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 29 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 30
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 31
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31
9.1. Normative References . . . . . . . . . . . . . . . . . . 30 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.2. Informative References . . . . . . . . . . . . . . . . . 30 9.1. Normative References . . . . . . . . . . . . . . . . . . 31
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 9.2. Informative References . . . . . . . . . . . . . . . . . 32
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32
1. Introduction 1. Introduction
The work on Constrained RESTful Environments (CoRE) aims at realizing The work on Constrained RESTful Environments (CoRE) aims at realizing
the REST architecture in a suitable form for the most constrained the REST architecture in a suitable form for the most constrained
nodes (such as microcontrollers with limited RAM and ROM [RFC7228]) nodes (such as microcontrollers with limited RAM and ROM [RFC7228])
and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP
protocol is intended to provide RESTful [REST] services not unlike protocol is intended to provide RESTful [REST] services not unlike
HTTP [RFC7230], while reducing the complexity of implementation as HTTP [RFC7230], while reducing the complexity of implementation as
well as the size of packets exchanged in order to make these services well as the size of packets exchanged in order to make these services
skipping to change at page 10, line 20 skipping to change at page 10, line 20
the one used in the initial exchange; the client SHOULD use the one used in the initial exchange; the client SHOULD use
this block size or a smaller one in all further requests in the this block size or a smaller one in all further requests in the
transfer sequence, even if that means changing the block size transfer sequence, even if that means changing the block size
(and possibly scaling the block number accordingly) from now (and possibly scaling the block number accordingly) from now
on. on.
Using one or both Block options, a single REST operation can be split Using one or both Block options, a single REST operation can be split
into multiple CoAP message exchanges. As specified in [RFC7252], into multiple CoAP message exchanges. As specified in [RFC7252],
each of these message exchanges uses their own CoAP Message ID. each of these message exchanges uses their own CoAP Message ID.
The Content-Format Option sent with the requests or responses MUST
reflect the content-format of the entire body. If blocks of a
response body arrive with different content-format options, it is up
to the client how to handle this error (it will typically abort any
ongoing block-wise transfer). If blocks of a request arrive at a
server with mismatching content-format options, the server MUST NOT
assemble them into a single request; this usually leads to a 4.08
(Request Entity Incomplete, Section 2.9.2) error response on the
mismatching block.
2.4. Using the Block2 Option 2.4. Using the Block2 Option
When a request is answered with a response carrying a Block2 Option When a request is answered with a response carrying a Block2 Option
with the M bit set, the requester may retrieve additional blocks of with the M bit set, the requester may retrieve additional blocks of
the resource representation by sending further requests with the same the resource representation by sending further requests with the same
options as the initial request and a Block2 Option giving the block options as the initial request and a Block2 Option giving the block
number and block size desired. In a request, the client MUST set the number and block size desired. In a request, the client MUST set the
M bit of a Block2 Option to zero and the server MUST ignore it on M bit of a Block2 Option to zero and the server MUST ignore it on
reception. reception.
skipping to change at page 11, line 26 skipping to change at page 11, line 35
Options. If the ETag Options do not match in a GET transfer, the Options. If the ETag Options do not match in a GET transfer, the
requester has the option of attempting to retrieve fresh values for requester has the option of attempting to retrieve fresh values for
the blocks it retrieved first. To minimize the resulting the blocks it retrieved first. To minimize the resulting
inefficiency, the server MAY cache the current value of a inefficiency, the server MAY cache the current value of a
representation for an ongoing sequence of requests. (The server may representation for an ongoing sequence of requests. (The server may
identify the sequence by the combination of the requesting end-point identify the sequence by the combination of the requesting end-point
and the URI being the same in each block-wise request.) Note well and the URI being the same in each block-wise request.) Note well
that this specification makes no requirement for the server to that this specification makes no requirement for the server to
establish any state; however, servers that offer quickly changing establish any state; however, servers that offer quickly changing
resources may thereby make it impossible for a client to ever resources may thereby make it impossible for a client to ever
retrieve a consistent set of blocks. retrieve a consistent set of blocks. Clients that want to retrieve
all blocks of a resource SHOULD strive to do so without undue delay.
Servers can fully expect to be free to discard any cached state after
a period of EXCHANGE_LIFETIME ([RFC7252], Section 4.8.2) after the
last access to the state, however, there is no requirement to always
keep the state for as long.
The Block2 option provides no way for a single endpoint to perform
multiple concurrently proceeding block-wise response payload transfer
(e.g., GET) operations to the same resource. This is rarely a
requirement, but as a workaround, a client may vary the cache key
(e.g., by using one of several URIs accessing resources with the same
semantics, or by varying a proxy-safe elective option).
2.5. Using the Block1 Option 2.5. Using the Block1 Option
In a request with a request payload (e.g., PUT or POST), the Block1 In a request with a request payload (e.g., PUT or POST), the Block1
Option refers to the payload in the request (descriptive usage). Option refers to the payload in the request (descriptive usage).
In response to a request with a payload (e.g., a PUT or POST In response to a request with a payload (e.g., a PUT or POST
transfer), the block size given in the Block1 Option indicates the transfer), the block size given in the Block1 Option indicates the
block size preference of the server for this resource (control block size preference of the server for this resource (control
usage). Obviously, at this point the first block has already been usage). Obviously, at this point the first block has already been
skipping to change at page 12, line 21 skipping to change at page 12, line 46
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, Section 2.9.1). If not all carry the response code 2.31 (Continue, Section 2.9.1). If not all
previous blocks are available at the server at the time of processing previous blocks are available at the server at the time of processing
the final block, the transfer fails and error code 4.08 (Request the final block, the transfer fails and error code 4.08 (Request
Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY
also return a 4.08 error code for any (final or non-final) Block1 also return a 4.08 error code for any (final or non-final) Block1
transfer that is not in sequence; clients that do not have specific transfer that is not in sequence; clients that do not have specific
mechanisms to handle this case therefore SHOULD always start with mechanisms to handle this case therefore SHOULD always start with
block zero and send the following blocks in order. block zero and send the following blocks in order.
One reason that a client might encounter a 4.08 error code is that
the server has already timed out and discarded the partial request
body being assembled. Clients SHOULD strive to send all blocks of a
request without undue delay. Servers can fully expect to be free to
discard any partial request body when a period of EXCHANGE_LIFETIME
([RFC7252], Section 4.8.2) has elapsed after the most recent block
was transferred; however, there is no requirement on a server to
always keep the partial request body for as long.
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
multiple concurrently proceeding block-wise request payload transfer multiple concurrently proceeding block-wise request payload transfer
skipping to change at page 13, line 18 skipping to change at page 14, line 4
observers or the entry in that list is updated by the server observers or the entry in that list is updated by the server
receiving a new GET request for the resource from the client). receiving a new GET request for the resource from the client).
When sending a 2.05 (Content) notification, the server only sends the When sending a 2.05 (Content) notification, the server only sends the
first block of the representation. The client retrieves the rest of first block of the representation. The client retrieves the rest of
the representation as if it had caused this first response by a GET the representation as if it had caused this first response by a GET
request, i.e., by using additional GET requests with Block2 options request, i.e., by using additional GET requests with Block2 options
containing NUM values greater than zero. (This results in the containing NUM values greater than zero. (This results in the
transfer of the entire representation, even if only some of the transfer of the entire representation, even if only some of the
blocks have changed with respect to a previous notification.) blocks have changed with respect to a previous notification.)
As with other dynamically changing resources, to ensure that the As with other dynamically changing resources, to ensure that the
blocks being reassembled are from the same version of the blocks being reassembled are from the same version of the
representation, the server SHOULD include an ETag option in each representation, the server SHOULD include an ETag option in each
response, and the reassembling client MUST compare the ETag options response, and the reassembling client MUST compare the ETag options
(Section 2.4). (Section 2.4). Even more so than for the general case of Block2,
clients that want to retrieve all blocks of a resource they have been
notified about with a first block SHOULD strive to do so without
undue delay.
See Section 3.4 for examples. See Section 3.4 for examples.
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
skipping to change at page 15, line 5 skipping to change at page 15, line 40
The present specification allows the server to return this response The present specification allows the server to return this response
code at any time during a Block1 transfer to indicate that it does 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 not currently have the resources to store blocks for a transfer that
it would intend to implement in an atomic fashion. It also allows 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 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. 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 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 usage, see Section 2.3) where the response carries a smaller SZX in
its Block1 option is a hint to try that smaller SZX. its Block1 option is a hint to try that smaller SZX.
2.10. Caching Considerations
This specification attempts to leave a variety of implementation
strategies open for caches, in particular those in caching proxies.
E.g., a cache is free to cache blocks individually, but also could
wait to obtain the complete representation before it serves parts of
it. Partial caching may be more efficient in a cross-proxy
(equivalent to a streaming HTTP proxy). A cached block (partial
cached response) can be used in place of a complete response to
satisfy a block-wise request that is presented to a cache. Note that
different blocks can have different Max-Age values, as they are
transferred at different times. A response with a block updates the
freshness of the complete representation. Individual blocks can be
validated, and validating a single block validates the complete
representation. A response with a Block1 Option in control usage
with the M bit set invalidates cached responses for the target URI.
A cache or proxy that combines responses (e.g., to split blocks in a
request or increase the block size in a response, or a cross-proxy)
may need to combine 2.31 and 2.01/2.04 responses; a stateless server
may be responding with 2.01 only on the first Block1 block
transferred, which dominates any 2.04 responses for later blocks.
If-None-Match only works correctly on Block1 requests with (NUM=0)
and MUST NOT be used on Block1 requests with NUM != 0.
3. Examples 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
skipping to change at page 23, line 48 skipping to change at page 24, line 48
| | Block2: 2/0/128 | | Block2: 2/0/128
| | | |
|<-----+ Header: 2.05 0x61451638 |<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc | 2.05 | Token: 0xfc
| | Block2: 2/0/128 | | Block2: 2/0/128
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [53 bytes] | | Payload: [53 bytes]
Figure 12: Observe sequence with blockwise response Figure 12: Observe sequence with blockwise response
(Note that the choice of token 0xfc in this examples is arbitrary;
tokens are just shown in this example to illustrate that the requests
for additional blocks cannot make use of the token of the Observation
relationship. As a general comment on tokens, there is no other
mention of tokens in this document, as blockwise transfers handle
tokens like any other CoAP exchange. As usual the client is free to
choose tokens for each exchange as it likes.)
In the following example, the client also uses early negotiation to In the following example, the client also uses early negotiation to
limit the block size to 64 bytes. limit the block size to 64 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
+----->| Header: GET 0x41011636 +----->| Header: GET 0x41011636
| GET | Token: 0xfb | GET | Token: 0xfb
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Observe: (empty) | | Observe: (empty)
| | Block2: 0/0/64 | | Block2: 0/0/64
 End of changes. 12 change blocks. 
30 lines changed or deleted 98 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/