CoRE Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track Z. Shelby, Ed.
Expires: April 24, 2014 Sensinode
October 21, 2013
Blockwise transfers in CoAP
draft-ietf-core-block-14
Abstract
CoAP is a RESTful transfer protocol for constrained nodes and
networks. Basic CoAP messages work well for the small payloads we
expect from temperature sensors, light switches, and similar
building-automation devices. Occasionally, however, applications
will need to transfer larger payloads -- for instance, for
firmware updates. With HTTP, TCP does the grunt work of slicing
large payloads up into multiple packets and ensuring that they all
arrive and are handled in the right order.
CoAP is based on datagram transports such as UDP or DTLS, which
limits the maximum size of resource representations that can be
transferred without too much fragmentation. Although UDP supports
larger payloads through IP fragmentation, it is limited to 64 KiB
and, more importantly, doesn't really work well for constrained
applications and networks.
Instead of relying on IP fragmentation, this specification extends
basic CoAP with a pair of "Block" options, for transferring multiple
blocks of information from a resource representation in multiple
request-response pairs. In many important cases, the Block options
enable a server to be truly stateless: the server can handle each
block transfer separately, with no need for a connection setup or
other server-side memory of previous block transfers.
In summary, the Block options provide a minimal way to transfer
larger representations in a block-wise fashion.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Bormann & Shelby Expires April 24, 2014 [Page 1]
Internet-Draft Blockwise transfers in CoAP October 2013
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 24, 2014.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4
2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6
2.3. Block Options in Requests and Responses . . . . . . . . . 8
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11
2.6. Combining Blockwise Transfers with the Observe Option . . 12
2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13
2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13
2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14
2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14
2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14
2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 21
4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 24
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 25
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
7. Security Considerations . . . . . . . . . . . . . . . . . . . 28
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 28
Bormann & Shelby Expires April 24, 2014 [Page 2]
Internet-Draft Blockwise transfers in CoAP October 2013
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.1. Normative References . . . . . . . . . . . . . . . . . . 30
9.2. Informative References . . . . . . . . . . . . . . . . . 30
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
1. Introduction
The CoRE WG is tasked with standardizing an Application Protocol for
Constrained Networks/Nodes, CoAP. This protocol is intended to
provide RESTful [REST] services not unlike HTTP [RFC2616], while
reducing the complexity of implementation as well as the size of
packets exchanged in order to make these services useful in a highly
constrained network of themselves highly constrained nodes.
This objective requires restraint in a number of sometimes
conflicting ways:
o reducing implementation complexity in order to minimize code size,
o reducing message sizes in order to minimize the number of
fragments needed for each message (in turn to maximize the
probability of delivery of the message), the amount of
transmission power needed and the loading of the limited-bandwidth
channel,
o reducing requirements on the environment such as stable storage,
good sources of randomness or user interaction capabilities.
CoAP is based on datagram transports such as UDP, which limit the
maximum size of resource representations that can be transferred
without creating unreasonable levels of IP fragmentation. In
addition, not all resource representations will fit into a single
link layer packet of a constrained network, which may cause
adaptation layer fragmentation even if IP layer fragmentation is not
required. Using fragmentation (either at the adaptation layer or at
the IP layer) to enable the transport of larger representations is
possible up to the maximum size of the underlying datagram protocol
(such as UDP), but the fragmentation/reassembly process burdens the
lower layers with conversation state that is better managed in the
application layer.
The present specification defines a pair of CoAP options to enable
_block-wise_ access to resource representations. The Block options
provide a minimal way to transfer larger resource representations in
a block-wise fashion. The overriding objective is to avoid the need
for creating conversation state at the server for block-wise GET
Bormann & Shelby Expires April 24, 2014 [Page 3]
Internet-Draft Blockwise transfers in CoAP October 2013
requests. (It is impossible to fully avoid creating conversation
state for POST/PUT, if the creation/replacement of resources is to be
atomic; where that property is not needed, there is no need to create
server conversation state in this case, either.)
In summary, this specification adds a pair of Block options to CoAP
that can be used for block-wise transfers. Benefits of using these
options include:
o Transfers larger than what can be accommodated in constrained-
network link-layer packets can be performed in smaller blocks.
o No hard-to-manage conversation state is created at the adaptation
layer or IP layer for fragmentation.
o The transfer of each block is acknowledged, enabling
retransmission if required.
o Both sides have a say in the block size that actually will be
used.
o The resulting exchanges are easy to understand using packet
analyzer tools and thus quite accessible to debugging.
o If needed, the Block options can also be used (without changes) to
provide random access to power-of-two sized blocks within a
resource representation.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119, BCP 14
[RFC2119] and indicate requirement levels for compliant CoAP
implementations.
In this document, the term "byte" is used in its now customary sense
as a synonym for "octet".
Where bit arithmetic is explained, this document uses the notation
familiar from the programming language C, except that the operator
"**" stands for exponentiation.
2. Block-wise transfers
As discussed in the introduction, there are good reasons to limit the
size of datagrams in constrained networks:
o by the maximum datagram size (~ 64 KiB for UDP)
Bormann & Shelby Expires April 24, 2014 [Page 4]
Internet-Draft Blockwise transfers in CoAP October 2013
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
for 6LoWPAN [RFC4919])
When a resource representation is larger than can be comfortably
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
sent both with requests and with responses, this specification
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
content of a single CoAP message, i.e. a single block being
transferred, while the term "body" will be used for the entire
resource representation that is being transferred in a block-wise
fashion. The Content-Format option applies to the body, not to the
payload, in particular the boundaries between the blocks may be in
places that are not separating whole units in terms of the structure,
encoding, or content-coding used by the Content-Format.
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
implementation as simple as possible, the Block options support only
a small range of power-of-two block sizes, from 2**4 (16) to 2**10
(1024) bytes. As bodies often will not evenly divide into the power-
of-two block size chosen, the size need not be reached in the final
block (but even for the final block, the chosen power-of-two size
will still be indicated in the block size field of the Block option).
2.1. The Block2 and Block1 Options
+------+---+---+---+---+--------+--------+--------+---------+
| Type | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+--------+--------+--------+---------+
| 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) |
| | | | | | | | | |
| 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) |
+------+---+---+---+---+--------+--------+--------+---------+
Table 1: Block Option Numbers
Bormann & Shelby Expires April 24, 2014 [Page 5]
Internet-Draft Blockwise transfers in CoAP October 2013
Both Block1 and Block2 options can be present both in request and
response messages. In either case, the Block1 Option pertains to the
request payload, and the Block2 Option pertains to the response
payload.
Hence, for the methods defined in [I-D.ietf-core-coap], Block1 is
useful with the payload-bearing POST and PUT requests and their
responses. Block2 is useful with GET, POST, and PUT requests and
their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see
section "Payload" of [I-D.ietf-core-coap]).
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
block-wise transfer and describes how this block-wise payload forms
part of the entire body being transferred ("descriptive usage").
Where it is present in the opposite direction, it provides additional
control on how that payload will be formed or was processed ("control
usage").
Implementation of either Block option is intended to be optional.
However, when it is present in a CoAP message, it MUST be processed
(or the message rejected); therefore it is identified as a critical
option. It MUST NOT occur more than once.
2.2. Structure of a Block Option
Three items of information may need to be transferred in a Block
(Block1 or Block2) option:
o The size of the block (SZX);
o whether more blocks are following (M);
o the relative number of the block (NUM) within a sequence of blocks
with the given size.
The value of the Block Option is a variable-size (0 to 3 byte)
unsigned integer (uint, see Appendix A of [I-D.ietf-core-coap]).
This integer value encodes these three fields, see Figure 1. (Due to
the CoAP uint encoding rules, when all of NUM, M, and SZX happen to
be zero, a zero-byte integer will be sent.)
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| NUM |M| SZX |
+-+-+-+-+-+-+-+-+
Bormann & Shelby Expires April 24, 2014 [Page 6]
Internet-Draft Blockwise transfers in CoAP October 2013
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 1: Block option value
The block size is encoded using a three-bit unsigned integer (0 for
2**4 to 6 for 2**10 bytes), which we call the "SZX" ("size
exponent"); the actual block size is then "2**(SZX + 4)". SZX is
transferred in the three least significant bits of the option value
(i.e., "val & 7" where "val" is the value of the option).
The fourth least significant bit, the M or "more" bit ("val & 8"),
indicates whether more blocks are following or the current block-wise
transfer is the last block being transferred.
The option value divided by sixteen (the NUM field) is the sequence
number of the block currently being transferred, starting from zero.
The current transfer is therefore about the "size" bytes starting at
byte "NUM << (SZX + 4)".
Implementation note: As an implementation convenience, "(val & ~0xF)
<< (val & 7)", i.e., the option value with the last 4 bits masked
out, shifted to the left by the value of SZX, gives the byte
position of the block being transferred.
More specifically, within the option value of a Block1 or Block2
Option, the meaning of the option fields is defined as follows:
NUM: Block Number, indicating the block number being requested or
provided. Block number 0 indicates the first block of a body
(i.e., starting with the first byte of the body).
Bormann & Shelby Expires April 24, 2014 [Page 7]
Internet-Draft Blockwise transfers in CoAP October 2013
M: More Flag (not last block). For descriptive usage, this flag, if
unset, indicates that the payload in this message is the last
block in the body; when set it indicates that there are one or
more additional blocks available. When a Block2 Option is used in
a request to retrieve a specific block number ("control usage"),
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
atomicity, see below.)
SZX: Block Size. The block size is represented as three-bit
unsigned integer indicating the size of a block to the power of
two. Thus block size = 2**(SZX + 4). The allowed values of SZX
are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the
maximum is 2**(6+4) = 1024. The value 7 for SZX (which would
indicate a block size of 2048) is reserved, i.e. MUST NOT be sent
and MUST lead to a 4.00 Bad Request response code upon reception
in a request.
There is no default value for the Block1 and Block2 Options. Absence
of one of these options is equivalent to an option value of 0 with
respect to the value of NUM and M that could be given in the option,
i.e. it indicates that the current block is the first and only block
of the transfer (block number 0, M bit not set). However, in
contrast to the explicit value 0, which would indicate an SZX of 0
and thus a size value of 16 bytes, there is no specific explicit size
implied by the absence of the option -- the size is left
unspecified. (As for any uint, the explicit value 0 is efficiently
indicated by a zero-length option; this, therefore, is different in
semantics from the absence of the option.)
2.3. Block Options in Requests and Responses
The Block options are used in one of three roles:
o In descriptive usage, i.e., a Block2 Option in a response (such as
a 2.05 response for GET), or a Block1 Option in a request (a PUT
or POST):
* The NUM field in the option value describes what block number
is contained in the payload of this message.
* The M bit indicates whether further blocks need to be
transferred to complete the transfer of that body.
* The block size given by SZX MUST match the size of the payload
in bytes, if the M bit is set. (SZX does not govern the
payload size if M is unset). For Block2, if the request
suggested a larger value of SZX, the next request MUST move SZX
Bormann & Shelby Expires April 24, 2014 [Page 8]
Internet-Draft Blockwise transfers in CoAP October 2013
down to the size given in the response. (The effect is that,
if the server uses the smaller of (1) its preferred block size
and (2) the block size requested, all blocks for a body use the
same block size.)
o A Block2 Option in control usage in a request (e.g., GET):
* The NUM field in the Block2 Option gives the block number of
the payload that is being requested to be returned in the
response.
* In this case, the M bit has no function and MUST be set to
zero.
* The block size given (SZX) suggests a block size (in the case
of block number 0) or repeats the block size of previous blocks
received (in the case of a non-zero block number).
o A Block1 Option in control usage in a response (e.g., a 2.xx
response for a PUT or POST request):
* The NUM field of the Block1 Option indicates what block number
is being acknowledged.
* If the M bit was set in the request, the server can choose
whether to act on each block separately, with no memory, or
whether to handle the request for the entire body atomically,
or any mix of the two.
+ If the M bit is also set in the response, it indicates that
this response does not carry the final response code to the
request, i.e. the server collects further blocks from the
same endpoint and plans to implement the request atomically
(e.g., acts only upon reception of the last block of
payload). In this case, the response MUST NOT carry a
Block2 option.
+ Conversely, if the M bit is unset even though it was set in
the request, it indicates the block-wise request was enacted
now specifically for this block, and the response carries
the final response to this request (and to any previous ones
with the M bit set in the response's Block1 Option in this
sequence of block-wise transfers); the client is still
expected to continue sending further blocks, the request
method for which may or may not also be enacted per-block.
* Finally, the SZX block size given in a control Block1 Option
indicates the largest block size preferred by the server for
Bormann & Shelby Expires April 24, 2014 [Page 9]
Internet-Draft Blockwise transfers in CoAP October 2013
transfers toward the resource that is the same or smaller than
the one used in the initial exchange; the client SHOULD use
this block size or a smaller one in all further requests in the
transfer sequence, even if that means changing the block size
(and possibly scaling the block number accordingly) from now
on.
Using one or both Block options, a single REST operation can be split
into multiple CoAP message exchanges. As specified in
[I-D.ietf-core-coap], each of these message exchanges uses their own
CoAP Message ID.
2.4. Using the 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
the resource representation by sending further requests with the same
options and a Block2 Option giving the block 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 reception.
To influence the block size used in a response, the requester also
uses the Block2 Option, giving the desired size, a block number of
zero and an M bit of zero. A server MUST use the block size
indicated or a smaller size. Any further block-wise requests for
blocks beyond the first one MUST indicate the same block size that
was used by the server in the response for the first request that
gave a desired size using a Block2 Option.
Once the Block2 Option is used by the requester and a first response
has been received with a possibly adjusted block size, all further
requests in a single block-wise transfer SHOULD ultimately use the
same size, except that there may not be enough content to fill the
last block (the one returned with the M bit not set). (Note that the
client may start using the Block2 Option in a second request after a
first request without a Block2 Option resulted in a Block2 option in
the response.) The server SHOULD use the block size indicated in the
request option or a smaller size, but the requester MUST take note of
the actual block size used in the response it receives to its initial
request and proceed to use it in subsequent requests. The server
behavior MUST ensure that this client behavior results in the same
block size for all responses in a sequence (except for the last one
with the M bit not set, and possibly the first one if the initial
request did not contain a Block2 Option).
Block-wise transfers can be used to GET resources the representations
of which are entirely static (not changing over time at all, such as
in a schema describing a device), or for dynamically changing
Bormann & Shelby Expires April 24, 2014 [Page 10]
Internet-Draft Blockwise transfers in CoAP October 2013
resources. In the latter case, the Block2 Option SHOULD be used in
conjunction with the ETag Option, to ensure that the blocks being
reassembled are from the same version of the representation: The
server SHOULD include an ETag option in each response. If an ETag
option is available, the client's reassembler, when reassembling the
representation from the blocks being exchanged, MUST compare ETag
Options. If the ETag Options do not match in a GET transfer, the
requester has the option of attempting to retrieve fresh values for
the blocks it retrieved first. To minimize the resulting
inefficiency, the server MAY cache the current value of a
representation for an ongoing sequence of requests. (The server may
identify the sequence by the combination of the requesting end-point
and the URI being the same in each block-wise request.) Note well
that this specification makes no requirement for the server to
establish any state; however, servers that offer quickly changing
resources may thereby make it impossible for a client to ever
retrieve a consistent set of blocks.
2.5. Using the Block1 Option
In a request with a request payload (e.g., PUT or POST), the Block1
Option refers to the payload in the request (descriptive usage).
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
block size preference of the server for this resource (control
usage). Obviously, at this point the first block has already been
transferred by the client without benefit of this knowledge. Still,
the client SHOULD heed the preference indicated and, for all further
blocks, use the block size preferred by the server or a smaller one.
Note that any reduction in the block size may mean that the second
request starts with a block number larger than one, as the first
request already transferred multiple blocks as counted in the smaller
size.
To counter the effects of adaptation layer fragmentation on packet
delivery probability, a client may want to give up retransmitting a
request with a relatively large payload even before MAX_RETRANSMIT
has been reached, and try restating the request as a block-wise
transfer with a smaller payload. Note that this new attempt is then
a new message-layer transaction and requires a new Message ID.
(Because of the uncertainty whether the request or the
acknowledgement was lost, this strategy is useful mostly for
idempotent requests.)
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
server, the actual creation/replacement takes place at the time the
Bormann & Shelby Expires April 24, 2014 [Page 11]
Internet-Draft Blockwise transfers in CoAP October 2013
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
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
the final block, the transfer fails and error code 4.08 (Request
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
transfer that is not in sequence; clients that do not have specific
mechanisms to handle this case therefore SHOULD always start with
block zero and send the following blocks in order.
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
multiple concurrently proceeding block-wise request payload transfer
(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
sequence from the same endpoint was finished) simply overwrites the
context the server may still be keeping. (This is probably exactly
what one wants in this case - the client may simply have restarted
and lost its knowledge of the previous sequence.)
2.6. Combining Blockwise Transfers with the Observe Option
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
observed by clients may be larger than can be comfortably processed
or transferred in one CoAP message. The following rules apply to the
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
block size in a Block2 Option in the GET request establishing or
renewing the observation relationship. If the server supports
blockwise transfers, it SHOULD take note of the block size and apply
it as a maximum size to all notifications/responses resulting from
the GET request (until the client is removed from the list of
observers or the entry in that list is updated by the server
receiving a new GET request for the resource from the client).
Bormann & Shelby Expires April 24, 2014 [Page 12]
Internet-Draft Blockwise transfers in CoAP October 2013
When sending a 2.05 (Content) notification, the server only sends the
first block of the representation. The client retrieves the rest of
the representation as if it had caused this first response by a GET
request, i.e., by using additional GET requests with Block2 options
containing NUM values greater than zero. (This results in the
transfer of the entire representation, even if only some of the
blocks have changed with respect to a previous notification.)
As with other dynamically changing resources, to ensure that the
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.
2.7. Combining Block1 and Block2
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-
wise transfers. First, the Block1 transfer of the request body
proceeds as usual. In the exchange of the last slice of this block-
wise transfer, the response carries the first slice of the Block2
transfer (NUM is zero). To continue this Block2 transfer, the client
continues to send requests similar to the requests in the Block1
phase, but leaves out the Block1 options and includes a Block2
request option with non-zero NUM.
Block2 transfers that retrieve the response body for a request that
used Block1 MUST be performed in sequential order.
2.8. Combining Block2 with Multicast
A client can use the Block2 option in a multicast GET request with
NUM = 0 to aid in limiting the size of the response.
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.
Bormann & Shelby Expires April 24, 2014 [Page 13]
Internet-Draft Blockwise transfers in CoAP October 2013
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
Bormann & Shelby Expires April 24, 2014 [Page 14]
Internet-Draft Blockwise transfers in CoAP October 2013
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
the basic operation, the operation in the presence of
retransmissions, and examples for the operation of the block size
negotiation.
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
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
would be shown as 2:2/0/32), or a Block1 Option value of 59 would be
shown as 1:3/1/128.
3.1. Block2 Examples
The first example (Figure 2) shows a GET request that is split into
three blocks. The server proposes a block size of 128, and the
client agrees. The first two ACKs contain 128 bytes of payload each,
and third ACK contains between 1 and 128 bytes.
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GET, /status, 2:1/0/128 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:1/1/128 |
| |
| CON [MID=1236], GET, /status, 2:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.05 Content, 2:2/0/128 |
Figure 2: Simple blockwise GET
In the second example (Figure 3), the client anticipates the
blockwise transfer (e.g., because of a size indication in the link-
format description [RFC6690]) and sends a size proposal. All ACK
messages except for the last carry 64 bytes of payload; the last one
carries between 1 and 64 bytes.
CLIENT SERVER
| |
| CON [MID=1234], GET, /status, 2:0/0/64 ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 |
| |
Bormann & Shelby Expires April 24, 2014 [Page 15]
Internet-Draft Blockwise transfers in CoAP October 2013
| CON [MID=1235], GET, /status, 2:1/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 |
: :
: ... :
: :
| CON [MID=1238], GET, /status, 2:4/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 |
| |
| CON [MID=1239], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 |
Figure 3: Blockwise GET with early negotiation
In the third example (Figure 4), the client is surprised by the need
for a blockwise transfer, and unhappy with the size chosen
unilaterally by the server. As it did not send a size proposal
initially, the negotiation only influences the size from the second
message exchange onward. Since the client already obtained both the
first and second 64-byte block in the first 128-byte exchange, it
goes on requesting the third 64-byte block ("2/0/64"). None of this
is (or needs to be) understood by the server, which simply responds
to the requests as it best can.
Bormann & Shelby Expires April 24, 2014 [Page 16]
Internet-Draft Blockwise transfers in CoAP October 2013
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
| |
| CON [MID=1236], GET, /status, 2:3/0/64 ------> |
| |
| <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 |
| |
| CON [MID=1237], GET, /status, 2:4/0/64 ------> |
| |
| <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 |
| |
| CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 4: Blockwise GET with late negotiation
In all these (and the following) cases, retransmissions are handled
by the CoAP message exchange layer, so they don't influence the block
operations (Figure 5, Figure 6).
Bormann & Shelby Expires April 24, 2014 [Page 17]
Internet-Draft Blockwise transfers in CoAP October 2013
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GE///////////////////////// |
| |
| (timeout) |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
: :
: ... :
: :
| CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 5: Blockwise GET with late negotiation and lost CON
CLIENT SERVER
| |
| CON [MID=1234], GET, /status ------> |
| |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| //////////////////////////////////tent, 2:2/1/64 |
| |
| (timeout) |
| |
| CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
: :
: ... :
: :
| CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 6: Blockwise GET with late negotiation and lost ACK
3.2. Block1 Examples
Bormann & Shelby Expires April 24, 2014 [Page 18]
Internet-Draft Blockwise transfers in CoAP October 2013
The following examples demonstrate a PUT exchange; a POST exchange
looks the same, with different requirements on atomicity/idempotence.
Note that, similar to GET, the responses to the requests that have a
more bit in the request Block1 Option are provisional and carry the
response code 2.31 (Continue); only the final response tells the
client that the PUT did succeed.
CLIENT SERVER
| |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |
Figure 7: Simple atomic blockwise PUT
A stateless server that simply builds/updates the resource in place
(statelessly) may indicate this by not setting the more bit in the
response (Figure 8); in this case, the response codes are valid
separately for each block being updated. This is of course only an
acceptable behavior of the server if the potential inconsistency
present during the run of the message exchange sequence does not lead
to problems, e.g. because the resource being created or changed is
not yet or not currently in use.
CLIENT SERVER
| |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 |
| |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 |
| |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |
Figure 8: Simple stateless blockwise PUT
Bormann & Shelby Expires April 24, 2014 [Page 19]
Internet-Draft Blockwise transfers in CoAP October 2013
Finally, a server receiving a blockwise PUT or POST may want to
indicate a smaller block size preference (Figure 9). In this case,
the client SHOULD continue with a smaller block size; if it does, it
MUST adjust the block number to properly count in that smaller size.
CLIENT SERVER
| |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.04 Changed, 1:0/1/32 |
| |
| CON [MID=1235], PUT, /options, 1:4/1/32 ------> |
| |
| <------ ACK [MID=1235], 2.04 Changed, 1:4/1/32 |
| |
| CON [MID=1236], PUT, /options, 1:5/1/32 ------> |
| |
| <------ ACK [MID=1235], 2.04 Changed, 1:5/1/32 |
| |
| CON [MID=1237], PUT, /options, 1:6/0/32 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:6/0/32 |
Figure 9: Simple atomic blockwise PUT with negotiation
3.3. Combining Block1 and Block2
Block options may be used in both directions of a single exchange.
The following example demonstrates a blockwise POST request,
resulting in a separate blockwise response.
CLIENT SERVER
| |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| |
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| |
| CON [MID=1236], POST, /soap, 1:2/0/128 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/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) |
Bormann & Shelby Expires April 24, 2014 [Page 20]
Internet-Draft Blockwise transfers in CoAP October 2013
| |
| <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 |
| |
| CON [MID=1238], POST, /soap, 2:2/0/128 ------> |
| |
| <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 |
| |
| CON [MID=1239], POST, /soap, 2:3/0/128 ------> |
| |
| <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 |
Figure 10: Atomic blockwise POST with blockwise response
This model does provide for early negotiation input to the Block2
blockwise transfer, as shown below.
CLIENT SERVER
| |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| |
| CON [MID=1235], POST, /soap, 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 ------> |
| |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 |
| |
| CON [MID=1237], POST, /soap, 2:1/0/64 ------> |
| (no payload for requests with Block2 with NUM != 0) |
| |
| <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 |
| |
| CON [MID=1238], POST, /soap, 2:2/0/64 ------> |
| |
| <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 |
| |
| CON [MID=1239], POST, /soap, 2:3/0/64 ------> |
| |
| <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 |
Figure 11: Atomic blockwise POST with blockwise response, early
negotiation
3.4. Combining Observe and Block2
Bormann & Shelby Expires April 24, 2014 [Page 21]
Internet-Draft Blockwise transfers in CoAP October 2013
In the following example, the server first sends a direct response
(Observe sequence number 62350) to the initial GET request (the
resulting blockwise transfer is as in Figure 4 and has therefore been
left out). The second transfer is started by a 2.05 notification
that contains just the first block (Observe sequence number 62354);
the client then goes on to obtain the rest of the blocks.
CLIENT SERVER
| |
+----->| Header: GET 0x41011636
| GET | Token: 0xfb
| | Uri-Path: status-icon
| | Observe: (empty)
| |
|<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62350
| | ETag: 6f00f38e
| | Payload: [128 bytes]
| |
| | (Usual GET transfer left out)
...
| | (Notification of first block:)
| |
|<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62354
| | ETag: 6f00f392
| | Payload: [128 bytes]
| |
+- - ->| Header: 0x6000af9c
| |
| | (Retrieval of remaining blocks)
| |
+----->| Header: GET 0x41011637
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 1/0/128
| |
|<-----+ Header: 2.05 0x61451637
| 2.05 | Token: 0xfc
| | Block2: 1/1/128
| | ETag: 6f00f392
| | Payload: [128 bytes]
| |
+----->| Header: GET 0x41011638
Bormann & Shelby Expires April 24, 2014 [Page 22]
Internet-Draft Blockwise transfers in CoAP October 2013
| 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
In the following example, the client also uses early negotiation to
limit the block size to 64 bytes.
CLIENT SERVER
| |
+----->| Header: GET 0x41011636
| GET | Token: 0xfb
| | Uri-Path: status-icon
| | Observe: (empty)
| | Block2: 0/0/64
| |
|<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb
| | Block2: 0/1/64
| | Observe: 62350
| | ETag: 6f00f38e
| | Max-Age: 60
| | Payload: [64 bytes]
| |
| | (Usual GET transfer left out)
...
| | (Notification of first block:)
| |
|<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb
| | Block2: 0/1/64
| | Observe: 62354
| | ETag: 6f00f392
| | Payload: [64 bytes]
| |
+- - ->| Header: 0x6000af9c
| |
| | (Retrieval of remaining blocks)
| |
+----->| Header: GET 0x41011637
Bormann & Shelby Expires April 24, 2014 [Page 23]
Internet-Draft Blockwise transfers in CoAP October 2013
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 1/0/64
| |
|<-----+ Header: 2.05 0x61451637
| 2.05 | Token: 0xfc
| | Block2: 1/1/64
| | ETag: 6f00f392
| | Payload: [64 bytes]
....
| |
+----->| Header: GET 0x41011638
| GET | Token: 0xfc
| | Uri-Path: status-icon
| | Block2: 4/0/64
| |
|<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc
| | Block2: 4/0/64
| | ETag: 6f00f392
| | Payload: [53 bytes]
Figure 13: Observe sequence with early negotiation
4. The Size2 and Size1 Options
In many cases when transferring a large resource representation block
by block, it is advantageous to know the total size early in the
process. Some indication may be available from the maximum size
estimate attribute "sz" provided in a resource description [RFC6690].
However, the size may vary dynamically, so a more up-to-date
indication may be useful.
This specification defines two CoAP Options, Size1 for indicating the
size of the representation transferred in requests, and Size2 for
indicating the size of the representation transferred in responses.
The Size2 Option may be used for two purposes:
o in a request, to ask the server to provide a size estimate along
with the usual response ("size request"). For this usage, the
value MUST be set to 0.
o in a response carrying a Block2 Option, to indicate the current
estimate the server has of the total size of the resource
representation, measured in bytes ("size indication").
Similarly, the Size1 Option may be used for two purposes:
Bormann & Shelby Expires April 24, 2014 [Page 24]
Internet-Draft Blockwise transfers in CoAP October 2013
o in a request carrying a Block1 Option, to indicate the current
estimate the client has of the total size of the resource
representation, measured in bytes ("size indication").
o in a 4.13 response, to indicate the maximum size that would have
been acceptable [I-D.ietf-core-coap], measured in bytes.
Apart from conveying/asking for size information, the Size options
have no other effect on the processing of the request or response.
If the client wants to minimize the size of the payload in the
resulting response, it should add a Block2 option to the request with
a small block size (e.g., setting SZX=0).
The Size Options are "elective", i.e., a client MUST be prepared for
the server to ignore the size estimate request. The Size Options
MUST NOT occur more than once.
+------+---+---+---+---+-------+--------+--------+---------+
| Type | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+-------+--------+--------+---------+
| 60 | | | x | | Size1 | uint | 0-4 B | (none) |
| | | | | | | | | |
| 28 | | | x | | Size2 | uint | 0-4 B | (none) |
+------+---+---+---+---+-------+--------+--------+---------+
Table 2: Size Option Numbers
Implementation Notes:
o As a quality of implementation consideration, blockwise transfers
for which the total size considerably exceeds the size of one
block are expected to include size indications, whenever those can
be provided without undue effort (preferably with the first block
exchanged). If the size estimate does not change, the indication
does not need to be repeated for every block.
o The end of a blockwise transfer is governed by the M bits in the
Block Options, _not_ by exhausting the size estimates exchanged.
o As usual for an option of type uint, the value 0 is best expressed
as an empty option (0 bytes). There is no default value.
o The Size Options are neither critical nor unsafe, and are marked
as No-Cache-Key.
5. HTTP Mapping Considerations
Bormann & Shelby Expires April 24, 2014 [Page 25]
Internet-Draft Blockwise transfers in CoAP October 2013
In this subsection, we give some brief examples for the influence the
Block options might have on intermediaries that map between CoAP and
HTTP.
For mapping CoAP requests to HTTP, the intermediary may want to map
the sequence of block-wise transfers into a single HTTP transfer.
E.g., for a GET request, the intermediary could perform the HTTP
request once the first block has been requested and could then
fulfill all further block requests out of its cache. A constrained
implementation may not be able to cache the entire object and may use
a combination of TCP flow control and (in particular if timeouts
occur) HTTP range requests to obtain the information necessary for
the next block transfer at the right time.
For PUT or POST requests, there is more variation in how HTTP servers
might implement ranges. Some WebDAV servers do, but in general the
CoAP-to-HTTP intermediary will have to try sending the payload of all
the blocks of a block-wise transfer within one HTTP request. If
enough buffering is available, this request can be started when the
last CoAP block is received. A constrained implementation may want
to relieve its buffering by already starting to send the HTTP request
at the time the first CoAP block is received; any HTTP 408 status
code that indicates that the HTTP server became impatient with the
resulting transfer can then be mapped into a CoAP 4.08 response code
(similarly, 413 maps to 4.13).
For mapping HTTP to CoAP, the intermediary may want to map a single
HTTP transfer into a sequence of block-wise transfers. If the HTTP
client is too slow delivering a request body on a PUT or POST, the
CoAP server might time out and return a 4.08 response code, which in
turn maps well to an HTTP 408 status code (again, 4.13 maps to 413).
HTTP range requests received on the HTTP side may be served out of a
cache and/or mapped to GET requests that request a sequence of blocks
overlapping the range.
Bormann & Shelby Expires April 24, 2014 [Page 26]
Internet-Draft Blockwise transfers in CoAP October 2013
(Note that, while the semantics of CoAP 4.08 and HTTP 408 differ,
this difference is largely due to the different way the two protocols
are mapped to transport. HTTP has an underlying TCP connection,
which supplies connection state, so a HTTP 408 status code can
immediately be used to indicate that a timeout occurred during
transmitting a request through that active TCP connection. The CoAP
4.08 response code indicates one or more missing blocks, which may be
due to timeouts or resource constraints; as there is no connection
state, there is no way to deliver such a response immediately;
instead, it is delivered on the next block transfer. Still, HTTP 408
is probably the best mapping back to HTTP, as the timeout is the most
likely cause for a CoAP 4.08. Note that there is no way to
distinguish a timeout from a missing block for a server without
creating additional state, the need for which we want to avoid.)
6. IANA Considerations
This draft adds the following option numbers to the CoAP Option
Numbers registry of [I-D.ietf-core-coap]:
+--------+--------+-----------+
| Number | Name | Reference |
+--------+--------+-----------+
| 23 | Block2 | [RFCXXXX] |
| | | |
| 27 | Block1 | [RFCXXXX] |
| | | |
| 28 | Size2 | [RFCXXXX] |
| | | |
| 60 | Size1 | [RFCXXXX] |
+--------+--------+-----------+
Table 3: CoAP Option Numbers
This draft adds the following response code to the CoAP Response
Codes registry of [I-D.ietf-core-coap]:
+------+---------------------------+-----------+
| Code | Description | Reference |
+------+---------------------------+-----------+
| 2.31 | Continue | [RFCXXXX] |
| | | |
| 4.08 | Request Entity Incomplete | [RFCXXXX] |
+------+---------------------------+-----------+
Table 4: CoAP Response Codes
Bormann & Shelby Expires April 24, 2014 [Page 27]
Internet-Draft Blockwise transfers in CoAP October 2013
7. Security Considerations
Providing access to blocks within a resource may lead to surprising
vulnerabilities. Where requests are not implemented atomically, an
attacker may be able to exploit a race condition or confuse a server
by inducing it to use a partially updated resource representation.
Partial transfers may also make certain problematic data invisible to
intrusion detection systems; it is RECOMMENDED that an intrusion
detection system (IDS) that analyzes resource representations
transferred by CoAP implement the Block options to gain access to
entire resource representations. Still, approaches such as
transferring even-numbered blocks on one path and odd-numbered blocks
on another path, or even transferring blocks multiple times with
different content and obtaining a different interpretation of
temporal order at the IDS than at the server, may prevent an IDS from
seeing the whole picture. These kinds of attacks are well understood
from IP fragmentation and TCP segmentation; CoAP does not add
fundamentally new considerations.
Where access to a resource is only granted to clients making use of a
specific security association, all blocks of that resource MUST be
subject to the same security checks; it MUST NOT be possible for
unprotected exchanges to influence blocks of an otherwise protected
resource. As a related consideration, where object security is
employed, PUT/POST should be implemented in the atomic fashion,
unless the object security operation is performed on each access and
the creation of unusable resources can be tolerated.
A stateless server might be susceptible to an attack where the
adversary sends a Block1 (e.g., PUT) block with a high block number:
A naive implementation might exhaust its resources by creating a huge
resource representation.
Misleading size indications may be used by an attacker to induce
buffer overflows in poor implementations, for which the usual
considerations apply.
7.1. Mitigating Resource Exhaustion Attacks
Certain blockwise requests may induce the server to create state,
e.g. to create a snapshot for the blockwise GET of a fast-changing
resource to enable consistent access to the same version of a
resource for all blocks, or to create temporary resource
representations that are collected until pressed into service by a
final PUT or POST with the more bit unset. All mechanisms that
induce a server to create state that cannot simply be cleaned up
create opportunities for denial-of-service attacks. Servers SHOULD
avoid being subject to resource exhaustion based on state created by
Bormann & Shelby Expires April 24, 2014 [Page 28]
Internet-Draft Blockwise transfers in CoAP October 2013
untrusted sources. But even if this is done, the mitigation may
cause a denial-of-service to a legitimate request when it is drowned
out by other state-creating requests. Wherever possible, servers
should therefore minimize the opportunities to create state for
untrusted sources, e.g. by using stateless approaches.
Performing segmentation at the application layer is almost always
better in this respect than at the transport layer or lower (IP
fragmentation, adaptation layer fragmentation), e.g. because there is
application layer semantics that can be used for mitigation or
because lower layers provide security associations that can prevent
attacks. However, it is less common to apply timeouts and keepalive
mechanisms at the application layer than at lower layers. Servers
MAY want to clean up accumulated state by timing it out (cf. response
code 4.08), and clients SHOULD be prepared to run blockwise transfers
in an expedient way to minimize the likelihood of running into such a
timeout.
7.2. Mitigating Amplification Attacks
[I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points
for use in amplification attacks.
A CoAP server can reduce the amount of amplification it provides to
an attacker by offering large resource representations only in
relatively small blocks. With this, e.g., for a 1000 byte resource,
a 10-byte request might result in an 80-byte response (with a 64-byte
block) instead of a 1016-byte response, considerably reducing the
amplification provided.
8. Acknowledgements
Much of the content of this draft is the result of discussions with
the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions.
Charles Palmer provided extensive editorial comments to a previous
version of this draft, some of which the authors hope to have covered
in this version. Esko Dijk reviewed a more recent version, leading
to a number of further editorial improvements, a solution to the 4.13
ambiguity problem, and the section about combining Block and
multicast. Markus Becker proposed getting rid of an ill-conceived
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
the Size Option, which has informed this draft. Klaus Hartke wrote
some of the text describing the interaction of Block2 with Observe.
Bormann & Shelby Expires April 24, 2014 [Page 29]
Internet-Draft Blockwise transfers in CoAP October 2013
Matthias Kovatsch provided a number of significant simplifications of
the protocol.
9. References
9.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), June 2013.
[I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP", draft-ietf-
core-observe-11 (work in progress), October 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
9.2. Informative References
[REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>.
[RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
over Low-Power Wireless Personal Area Networks (6LoWPANs):
Overview, Assumptions, Problem Statement, and Goals", RFC
4919, August 2007.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012.
Authors' Addresses
Bormann & Shelby Expires April 24, 2014 [Page 30]
Internet-Draft Blockwise transfers in CoAP October 2013
Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Zach Shelby (editor)
Sensinode
Kidekuja 2
Vuokatti 88600
Finland
Phone: +358407796297
Email: zach@sensinode.com
Bormann & Shelby Expires April 24, 2014 [Page 31]
