draft-ietf-core-block-12.txt   draft-ietf-core-block-13.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: December 29, 2013 Sensinode Expires: April 23, 2014 Sensinode
June 27, 2013 October 20, 2013
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-12 draft-ietf-core-block-13
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
updates. With HTTP, TCP does the grunt work of slicing large firmware updates. With HTTP, TCP does the grunt work of slicing
payloads up into multiple packets and ensuring that they all arrive large payloads up into multiple packets and ensuring that they all
and are handled in the right order. arrive and are handled in the right order.
CoAP is based on datagram transports such as UDP or DTLS, which CoAP is based on datagram transports such as UDP or DTLS, which
limits the maximum size of resource representations that can be limits the maximum size of resource representations that can be
transferred without too much fragmentation. Although UDP supports transferred without too much fragmentation. Although UDP supports
larger payloads through IP fragmentation, it is limited to 64 KiB larger payloads through IP fragmentation, it is limited to 64 KiB
and, more importantly, doesn't really work well for constrained and, more importantly, doesn't really work well for constrained
applications and networks. applications and networks.
Instead of relying on IP fragmentation, this specification extends Instead of relying on IP fragmentation, this specification extends
basic CoAP with a pair of "Block" options, for transferring multiple basic CoAP with a pair of "Block" options, for transferring multiple
blocks of information from a resource representation in multiple blocks of information from a resource representation in multiple
request-response pairs. In many important cases, the Block options request-response pairs. In many important cases, the Block options
enable a server to be truly stateless: the server can handle each enable a server to be truly stateless: the server can handle each
block transfer separately, with no need for a connection setup or block transfer separately, with no need for a connection setup or
other server-side memory of previous block transfers. other server-side memory of previous block transfers.
In summary, the Block options provide a minimal way to transfer In summary, the Block options provide a minimal way to transfer
larger representations in a block-wise fashion. larger representations in a block-wise fashion.
The present revision -11 fixes one example and adds the text and Status of This Memo
examples about the Block/Observe interaction, taken from -observe.
It also adds a couple of formatting bugs from the new xml2rfc. The
"grand rewrite" is next.
Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 December 29, 2013. This Internet-Draft will expire on April 23, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4
2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 5
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6
2.3. Block Options in Requests and Responses . . . . . . . . . 9 2.3. Block Options in Requests and Responses . . . . . . . . . 8
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 11 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 9
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 12 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11
2.6. Combining Blockwise Transfers with the Observe Option . . 13 2.6. Combining Blockwise Transfers with the Observe Option . . 12
2.7. Block2 and Initiative . . . . . . . . . . . . . . . . . . 14 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 14
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 16
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . . 22 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 18
4. The Size Options . . . . . . . . . . . . . . . . . . . . . . . 26 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 19
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 28 4. The Size Options . . . . . . . . . . . . . . . . . . . . . . 22
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 23
7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 31 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 32 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 26
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 26
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27
9.1. Normative References . . . . . . . . . . . . . . . . . . . 34 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.2. Informative References . . . . . . . . . . . . . . . . . . 34 9.1. Normative References . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35 9.2. Informative References . . . . . . . . . . . . . . . . . 28
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
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 22 skipping to change at page 5, line 10
o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6) o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6)
o by the desire to avoid adaptation layer fragmentation (60-80 bytes o by the desire to avoid adaptation layer fragmentation (60-80 bytes
for 6LoWPAN [RFC4919]) for 6LoWPAN [RFC4919])
When a resource representation is larger than can be comfortably When a resource representation is larger than can be comfortably
transferred in the payload of a single CoAP datagram, a Block option transferred in the payload of a single CoAP datagram, a Block option
can be used to indicate a block-wise transfer. As payloads can be can be used to indicate a block-wise transfer. As payloads can be
sent both with requests and with responses, this specification sent both with requests and with responses, this specification
provides two separate options for each direction of payload transfer. provides two separate options for each direction of payload transfer.
In identifying these options, we use the number 1 to refer to the
transfer of the resource representation that pertains to the request,
and the number 2 to refer to the transfer of the resource
representation for the response.
In the following, the term "payload" will be used for the actual In the following, the term "payload" will be used for the actual
content of a single CoAP message, i.e. a single block being content of a single CoAP message, i.e. a single block being
transferred, while the term "body" will be used for the entire transferred, while the term "body" will be used for the entire
resource representation that is being transferred in a block-wise resource representation that is being transferred in a block-wise
fashion. The Content-Format option applies to the body, not to the fashion. The Content-Format option applies to the body, not to the
payload, in particular the boundaries between the blocks may in payload, in particular the boundaries between the blocks may be in
places that are not whole units in terms of the structure, encoding, places that are not separating whole units in terms of the structure,
or content-coding used by the Content-Format. encoding, or content-coding used by the Content-Format.
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).
skipping to change at page 7, line 16 skipping to change at page 6, line 7
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
responses. Block2 is useful with GET, POST, and PUT requests and responses. Block2 is useful with GET, POST, and PUT requests and
their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see
section "Payload" of [I-D.ietf-core-coap]). section "Payload" of [I-D.ietf-core-coap]).
(As a memory aid: Block_1_ pertains to the payload of the _1st_ part
of the request-response exchange, i.e. the request, and Block_2_
pertains to the payload of the _2nd_ part of the request-response
exchange, i.e. the response.)
Where Block1 is present in a request or Block2 in a response (i.e., Where Block1 is present in a request or Block2 in a response (i.e.,
in that message to the payload of which it pertains) it indicates a in that message to the payload of which it pertains) it indicates a
block-wise transfer and describes how this block-wise payload forms block-wise transfer and describes how this block-wise payload forms
part of the entire body being transferred ("descriptive usage"). part of the entire body being transferred ("descriptive usage").
Where it is present in the opposite direction, it provides additional Where it is present in the opposite direction, it provides additional
control on how that payload will be formed or was processed ("control control on how that payload will be formed or was processed ("control
usage"). usage").
Implementation of either Block option is intended to be optional. Implementation of either Block option is intended to be optional.
However, when it is present in a CoAP message, it MUST be processed However, when it is present in a CoAP message, it MUST be processed
skipping to change at page 9, line 19 skipping to change at page 7, line 52
a request to retrieve a specific block number ("control usage"), a request to retrieve a specific block number ("control usage"),
the M bit MUST be sent as zero and ignored on reception. (In a the M bit MUST be sent as zero and ignored on reception. (In a
Block1 Option in a response, the M flag is used to indicate Block1 Option in a response, the M flag is used to indicate
atomicity, see below.) atomicity, see below.)
SZX: Block Size. The block size is represented as three-bit SZX: Block Size. The block size is represented as three-bit
unsigned integer indicating the size of a block to the power of unsigned integer indicating the size of a block to the power of
two. Thus block size = 2**(SZX + 4). The allowed values of SZX 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 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 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 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 and MUST lead to a 4.00 Bad Request response code upon reception
in a request. in a request.
There is no default value for the Block1 and Block2 Options. Absence 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 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, 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 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 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 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 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. implied by the absence of the option -- the size is left
(As for any uint, the explicit value 0 is efficiently indicated by a unspecified. (As for any uint, the explicit value 0 is efficiently
zero-length option; this, therefore, is different in semantics from indicated by a zero-length option; this, therefore, is different in
the absence of the option.) 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 (such as o In descriptive usage, i.e., a Block2 Option in a response (such as
a 2.05 response for GET), or a Block1 Option in a request (a PUT a 2.05 response for GET), or a Block1 Option in a request (a 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
skipping to change at page 12, line 34 skipping to change at page 11, line 18
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
transferred by the client without benefit of this knowledge. Still, transferred by the client without benefit of this knowledge. Still,
the client SHOULD heed the preference and, for all further blocks, the client SHOULD heed the preference indicated and, for all further
use the block size preferred by the server or a smaller one. Note blocks, use the block size preferred by the server or a smaller one.
that any reduction in the block size may mean that the second request Note that any reduction in the block size may mean that the second
starts with a block number larger than one, as the first request request starts with a block number larger than one, as the first
already transferred multiple blocks as counted in the smaller size. request already transferred multiple blocks as counted in the smaller
size.
To counter the effects of adaptation layer fragmentation on packet To counter the effects of adaptation layer fragmentation on packet
delivery probability, a client may want to give up retransmitting a delivery probability, a client may want to give up retransmitting a
request with a relatively large payload even before MAX_RETRANSMIT request with a relatively large payload even before MAX_RETRANSMIT
has been reached, and try restating the request as a block-wise has been reached, and try restating the request as a block-wise
transfer with a smaller payload. Note that this new attempt is then transfer with a smaller payload. Note that this new attempt is then
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. If not all previous blocks are available at the server is received. In this case, all success responses to non-final blocks
at this time, the transfer fails and error code 4.08 (Request Entity carry the response code 2.31 (Continue). If not all previous blocks
Incomplete) MUST be returned. The error code 4.13 (Request Entity are available at the server at the time of processing the final
Too Large) can be returned at any time by a server that does not block, the transfer fails and error code 4.08 (Request Entity
currently have the resources to store blocks for a block-wise request Incomplete) MUST be returned. A server MAY also return a 4.08 error
payload transfer that it would intend to implement in an atomic code for any (final or non-final) Block1 transfer that is not in
fashion. (Note that a 4.13 response to a request that does not sequence; clients that do not have specific mechanisms to handle this
employ Block1 is a hint for the client to try sending Block1, and a case therefore SHOULD always start with block zero and send the
4.13 response with a smaller SZX in its Block1 option than requested following blocks in order.
is a hint to try a smaller SZX.)
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. (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 its Block1
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
(e.g., PUT or POST) operations to the same resource. Starting a new (e.g., PUT or POST) operations to the same resource. Starting a new
block-wise sequence of requests to the same resource (before an old block-wise sequence of requests to the same resource (before an old
sequence from the same endpoint was finished) simply overwrites the sequence from the same endpoint was finished) simply overwrites the
context the server may still be keeping. (This is probably exactly context the server may still be keeping. (This is probably exactly
what one wants in this case - the client may simply have restarted what one wants in this case - the client may simply have restarted
and lost its knowledge of the previous sequence.) and lost its knowledge of the previous sequence.)
2.6. Combining Blockwise Transfers with the Observe Option 2.6. Combining Blockwise Transfers with the Observe Option
The Observe Option provides a way for a client to be notified about The Observe Option provides a way for a client to be notified about
changes over time of a resource [I-D.ietf-core-observe]. Resources changes over time of a resource [I-D.ietf-core-observe]. Resources
observed by clients may be larger than can be comfortably processed observed by clients may be larger than can be comfortably processed
or transferred in one CoAP message. The following rules apply to the or transferred in one CoAP message. The following rules apply to the
combination of blockwise transfers with notifications. combination of blockwise transfers with notifications.
Observation relationships always apply to an entire resource; the
Block2 option does not provide a way to observe a single block of a
resource.
As with basic GET transfers, the client can indicate its desired As with basic GET transfers, the client can indicate its desired
block size in a Block2 Option in the GET request. If the server block size in a Block2 Option in the GET request establishing or
supports blockwise transfers, it SHOULD take note of the block size renewing the observation relationship. If the server supports
and apply it as a maximum size to all notifications/responses blockwise transfers, it SHOULD take note of the block size and apply
resulting from the GET request (until the client is removed from the it as a maximum size to all notifications/responses resulting from
list of observers or the server receives a new GET request for the the GET request (until the client is removed from the list of
resource from the client). observers or the entry in that list is updated by the server
receiving a new GET request for the resource from the client).
When sending a 2.05 (Content) notification, the server always sends When sending a 2.05 (Content) notification, the server only sends the
all blocks of the representation, suitably sequenced by its first block of the representation. The client retrieves the rest of
congestion control mechanism, even if only some of the blocks have the representation as if it had caused this first response by a GET
changed with respect to a previous notification. The server performs request, i.e., by using additional GET requests with Block2 options
the blockwise transfer by making use of the Block2 Option in each containing NUM values greater than zero. (This results in the
block. When reassembling representations that are transmitted in transfer of the entire representation, even if only some of the
multiple blocks, the client MUST NOT combine blocks carrying blocks have changed with respect to a previous notification.)
different Observe Option values.
Blockwise transfers of notifications MUST use Confirmable messages As with other dynamically changing resources, to ensure that the
and MUST NOT use Non-confirmable messages. blocks being reassembled are from the same version of the
representation, the server SHOULD include an ETag option in each
response, and the reassembling client MUST compare the ETag options
(Section 2.4).
See Section 3.4 for examples. See Section 3.4 for examples.
2.7. Block2 and Initiative 2.7. Combining Block1 and Block2
In a basic block-wise GET request, it is the job of the client to In PUT and particularly in POST exchanges, both the request body and
initiate each further block transfer. We say that the "initiative" the response body may be large enough to require the use of block-
is with the client. If no buffering of a snapshot of the resource is wise transfers. First, the Block1 transfer of the request body
required, the server can stay entirely stateless. This is proceeds as usual. In the exchange of the last slice of this block-
particularly useful for very simple servers for which all resources wise transfer, the response carries the first slice of the Block2
that are big enough to merit block-wise transfer are static (such as transfer (NUM is zero). To continue this Block2 transfer, the client
the links in "/.well-known/core"). continues to send requests similar to the requests in the Block1
phase, bute leaves out the Block1 options and includes a Block2
request option with non-zero NUM.
However, when Block2 is combined with Observe or Block1, this simple Block2 transfers that retrieve the response body for a request that
approach no longer works very well. Therefore, the presence of an used Block1 MUST be performed in sequential order.
Observe or Block1 option in combination with a Block2 option is said
to reverse the initiative: From then on, it is the job of the server
to provide additional responses that complete the blockwise transfer
of the notification (Observe) or response to a block-wise PUT or POST
transfer (Block1). As all these additional responses are in response
to the single request that caused them, they all carry the token of
this request: The GET with an Observe option, or the PUT/POST with a
Block1 option.
(For the request side of block-wise transfers that use the Block1 2.8. Combining Block2 with Multicast
option, it is of course always the initiative of the client to send
the next block - which is quite natural, as the client has to A client can use the Block2 option in a multicast GET request with
generate them and therefore knows when it is time to send the next NUM = 0 to aid in limiting the size of the response.
block.)
Similarly, a response to a multicast GET request can use a Block2
option with NUM = 0 if the representation is large, or to further
limit the size of the response.
In both cases, the client retrieves any further blocks using unicast
exchanges; in the unicast requests, the client SHOULD heed any block
size preferences indicated by the server in the response to the
multicast request.
Other uses of the Block options in conjunction with multicast
messages are for further study.
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
skipping to change at page 18, line 35 skipping to change at page 16, line 47
| | | |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 6: Blockwise GET with late negotiation and lost ACK Figure 6: Blockwise GET with late negotiation and lost ACK
3.2. Block1 Examples 3.2. Block1 Examples
The following examples demonstrate a PUT exchange; a POST exchange The following examples demonstrate a PUT exchange; a POST exchange
looks the same, with different requirements on atomicity/idempotence. looks the same, with different requirements on atomicity/idempotence.
Note that, similar to GET, the responses to the requests that have a Note that, similar to GET, the responses to the requests that have a
more bit in the request Block1 Option are provisional; only the final more bit in the request Block1 Option are provisional and carry the
response tells the client that the PUT succeeded. response code 2.31 (Continue); only the final response tells the
client that the PUT did succeed.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> | | CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| | | |
| <------ ACK [MID=1234], 2.04 Changed, 1:0/1/128 | | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| | | |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> | | CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.04 Changed, 1:1/1/128 | | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| | | |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> | | CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| | | |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |
Figure 7: Simple atomic blockwise PUT Figure 7: Simple atomic blockwise PUT
A stateless server that simply builds/updates the resource in place A stateless server that simply builds/updates the resource in place
(statelessly) may indicate this by not setting the more bit in the (statelessly) may indicate this by not setting the more bit in the
response (Figure 8); in this case, the response codes are valid response (Figure 8); in this case, the response codes are valid
skipping to change at page 21, line 9 skipping to change at page 18, line 32
3.3. Combining Block1 and Block2 3.3. Combining Block1 and Block2
Block options may be used in both directions of a single exchange. Block options may be used in both directions of a single exchange.
The following example demonstrates a blockwise POST request, The following example demonstrates a blockwise POST request,
resulting in a separate blockwise response. resulting in a separate blockwise response.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> | | CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| | | |
| <------ ACK [MID=1234], 2.01 Created, 1:0/1/128 | | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| | | |
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> | | CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.01 Created, 1:1/1/128 | | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| | | |
| CON [MID=1236], POST, /soap, 1:2/0/128 ------> | | CON [MID=1236], POST, /soap, 1:2/0/128 ------> |
| | | |
| <------ ACK [MID=1236], 2.01 Created, 2:0/1/128, 1:2/0/128 | | <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/128 |
| |
| (initiative changes to server) |
| | | |
| <------ CON [MID=4713], 2.01 Created, 2:1/1/128 | | CON [MID=1237], POST, /soap, 2:1/0/128 ------> |
| (no payload for requests with Block2 with NUM != 0) |
| (could also do late negotiation by requesting e.g. 2:2/0/64) |
| | | |
| ACK [MID=4713], 0 ------> | | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 |
| | | |
| <------ CON [MID=4714], 2.01 Created, 2:2/1/128 | | CON [MID=1238], POST, /soap, 2:2/0/128 ------> |
| | | |
| ACK [MID=4714], 0 ------> | | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 |
| | | |
| <------ CON [MID=4715], 2.01 Created, 2:3/0/128 | | CON [MID=1239], POST, /soap, 2:3/0/128 ------> |
| | | |
| ACK [MID=4715], 0 ------> | | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 |
Figure 10: Atomic blockwise POST with separate blockwise response Figure 10: Atomic blockwise POST with blockwise response
This model does provide for early negotiation input to the Block2 This model does provide for early negotiation input to the Block2
blockwise transfer, as shown below. (However, there is no way to blockwise transfer, as shown below.
provide late negotiation with server initiative.)
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> | | CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| | | |
| <------ ACK [MID=1234], 2.01 Created, 1:0/1/128 | | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| | | |
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> | | CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.01 Created, 1:1/1/128 | | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| | | |
| CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> | | CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> |
| | | |
| <------ ACK [MID=1236], 2.01 Created, 1:2/0/128, 2:0/1/64 | | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 |
| | | |
| (initiative changes to server) | | CON [MID=1237], POST, /soap, 2:1/0/64 ------> |
| | | (no payload for requests with Block2 with NUM != 0) |
| <------ CON [MID=4713], 2.01 Created, 2:1/1/64 | | |
| | | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 |
| ACK [MID=4713], 0 ------> | | |
| | | CON [MID=1238], POST, /soap, 2:2/0/64 ------> |
| <------ CON [MID=4714], 2.01 Created, 2:2/1/64 | | |
| | | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 |
| ACK [MID=4714], 0 ------> | | |
| | | CON [MID=1239], POST, /soap, 2:3/0/64 ------> |
| <------ CON [MID=4715], 2.01 Created, 2:3/0/64 | | |
| | | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 |
| ACK [MID=4715], 0 ------> |
Figure 11: Atomic blockwise POST with separate blockwise response, Figure 11: Atomic blockwise POST with blockwise response, early
early negotiation negotiation
3.4. Combining Observe and Block2 3.4. Combining Observe and Block2
In the following example, the server sends two notifications of two In the following example, the server first sends a direct response
blocks each. The first notification is a direct response to the GET (Observe sequence number 62350) to the initial GET request (the
request; the first block therefore can be sent piggy-backed in the resulting blockwise transfer is as in Figure 4 and has therefore been
ACK. The Observe Option indicates that the initiative has switched left out). The second transfer is started by a 2.05 notification
to the server. that contains just the first block (Observe sequence number 62354);
the client then goes on to obtain the rest of the blocks.
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)
| | | |
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/128 | | Block2: 0/1/128
| | Observe: 62354 | | Observe: 62350
| | Max-Age: 60 | | ETag: 6f00f38e
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
| | (initiative changes to server) | | (Usual GET transfer left out)
...
| | (Notification of first block:)
| | | |
|<-----+ Header: 2.05 0x4145af9c |<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 1/0/128 | | Block2: 0/1/128
| | Observe: 62354 | | Observe: 62354
| | Max-Age: 60 | | ETag: 6f00f392
| | Payload: [27 bytes] | | Payload: [128 bytes]
| | | |
+- - ->| Header: 0x6000af9c +- - ->| Header: 0x6000af9c
| | | |
|<-----+ Header: 2.05 0x4145af9d | | (Retrieval of remaining blocks)
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62444
| | Max-Age: 60
| | Payload: [128 bytes]
| |
+- - ->| Header: 0x6000af9d
| | | |
|<-----+ Header: 2.05 0x4145af9e +----->| Header: GET 0x41011637
| 2.05 | Token: 0xfb | GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 1/0/128 | | Block2: 1/0/128
| | Observe: 62444
| | Max-Age: 60
| | Payload: [27 bytes]
| | | |
+- - ->| Header: 0x6000af9e |<-----+ Header: 2.05 0x61451637
| 2.05 | Token: 0xfc
| | Block2: 1/1/128
| | ETag: 6f00f392
| | Payload: [128 bytes]
| | | |
+----->| Header: GET 0x41011638
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 2/0/128
| |
|<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc
| | Block2: 2/0/128
| | ETag: 6f00f392
| | Payload: [53 bytes]
Figure 12: Observe sequence with blockwise response Figure 12: Observe sequence with blockwise response
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
| | | |
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/64 | | Block2: 0/1/64
| | Observe: 62354 | | Observe: 62350
| | Max-Age: 60 | | ETag: 6f00f38e
| | Payload: [64 bytes] | | Max-Age: 60
| | | | Payload: [64 bytes]
| | (initiative changes to server) | |
| | | | (Usual GET transfer left out)
|<-----+ Header: 2.05 0x4145af9c ...
| 2.05 | Token: 0xfb | | (Notification of first block:)
| | Block2: 1/1/64 | |
| | Observe: 62354 |<-----+ Header: 2.05 0x4145af9c
| | Max-Age: 60 | 2.05 | Token: 0xfb
| | Payload: [64 bytes] | | Block2: 0/1/64
| | | | Observe: 62354
+- - ->| Header: 0x6000af9c | | ETag: 6f00f392
| | | | Payload: [64 bytes]
|<-----+ Header: 2.05 0x4145af9d | |
| 2.05 | Token: 0xfb +- - ->| Header: 0x6000af9c
| | Block2: 2/0/64 | |
| | Observe: 62354 | | (Retrieval of remaining blocks)
| | Max-Age: 60 | |
| | Payload: [27 bytes] +----->| Header: GET 0x41011637
| | | GET | Token: 0xfc
+- - ->| Header: 0x6000af9d | | Uri-Path: status-icon
| | | | Block2: 1/0/64
|<-----+ Header: 2.05 0x4145af9e | |
| 2.05 | Token: 0xfb |<-----+ Header: 2.05 0x61451637
| | Block2: 0/1/64 | 2.05 | Token: 0xfc
| | Observe: 62444 | | Block2: 1/1/64
| | Max-Age: 60 | | ETag: 6f00f392
| | Payload: [128 bytes] | | Payload: [64 bytes]
| | ....
+- - ->| Header: 0x6000af9e | |
| | +----->| Header: GET 0x41011638
|<-----+ Header: 2.05 0x4145af9f | GET | Token: 0xfc
| 2.05 | Token: 0xfb | | Uri-Path: status-icon
| | Block2: 1/1/64 | | Block2: 4/0/64
| | Observe: 62444 | |
| | Max-Age: 60 |<-----+ Header: 2.05 0x61451638
| | Payload: [128 bytes] | 2.05 | Token: 0xfc
| | | | Block2: 4/0/64
+- - ->| Header: 0x6000af9f | | ETag: 6f00f392
| | | | Payload: [53 bytes]
|<-----+ Header: 2.05 0x4145afa0
| 2.05 | Token: 0xfb
| | Block2: 2/0/64
| | Observe: 62444
| | Max-Age: 60
| | Payload: [27 bytes]
| |
+- - ->| Header: 0x6000afa0
| |
Figure 13: Observe sequence with early negotiation Figure 13: Observe sequence with early negotiation
4. The Size Options 4. The Size 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
skipping to change at page 30, line 27 skipping to change at page 25, line 22
| 28 | Size2 | [RFCXXXX] | | 28 | Size2 | [RFCXXXX] |
| | | | | | | |
| 60 | Size1 | [RFCXXXX] | | 60 | Size1 | [RFCXXXX] |
+--------+--------+-----------+ +--------+--------+-----------+
Table 3: CoAP Option Numbers Table 3: 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 |
+------+--------------------------------+-----------+ +------+---------------------------+-----------+
| 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | | 2.31 | Continue | [RFCXXXX] |
+------+--------------------------------+-----------+ | | | |
| 4.08 | Request Entity Incomplete | [RFCXXXX] |
+------+---------------------------+-----------+
Table 4: CoAP Response Codes Table 4: CoAP Response Codes
7. Security Considerations 7. Security Considerations
Providing access to blocks within a resource may lead to surprising Providing access to blocks within a resource may lead to surprising
vulnerabilities. Where requests are not implemented atomically, an vulnerabilities. Where requests are not implemented atomically, an
attacker may be able to exploit a race condition or confuse a server attacker may be able to exploit a race condition or confuse a server
by inducing it to use a partially updated resource representation. by inducing it to use a partially updated resource representation.
Partial transfers may also make certain problematic data invisible to Partial transfers may also make certain problematic data invisible to
skipping to change at page 33, line 13 skipping to change at page 27, line 23
amplification provided. amplification provided.
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, a solution to the 4.13
to the 4.13 ambiguity problem. Markus Becker proposed getting rid of ambiguity problem, and the section about combining Block and
an ill-conceived default value for the Block2 and Block1 options. multicast. 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. 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
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-17 Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), May 2013. (work in progress), June 2013.
[I-D.ietf-core-observe] [I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP", Hartke, K., "Observing Resources in CoAP", draft-ietf-
draft-ietf-core-observe-08 (work in progress), core-observe-11 (work in progress), October 2013.
February 2013.
[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
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation, Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000, <http:// University of California, Irvine, 2000, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/ www.ics.uci.edu/~fielding/pubs/dissertation/
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
RFC 4919, August 2007. 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.
Authors' Addresses Authors' Addresses
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
 End of changes. 54 change blocks. 
254 lines changed or deleted 272 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/