draft-ietf-core-block-04.txt   draft-ietf-core-block-05.txt 
CoRE Working Group C. Bormann CoRE Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track Z. Shelby, Ed. Intended status: Standards Track Z. Shelby, Ed.
Expires: January 12, 2012 Sensinode Expires: July 16, 2012 Sensinode
July 11, 2011 January 13, 2012
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-04 draft-ietf-core-block-05
Abstract Abstract
CoAP is a RESTful transfer protocol for constrained nodes and CoAP is a RESTful transfer protocol for constrained nodes and
networks. CoAP is based on datagram transport, which limits the networks. Basic CoAP messages work well for the small payloads we
maximum size of resource representations that can be transferred expect from temperature sensors, light switches, and similar
without too much fragmentation. The Block options provide a minimal building-automation devices. Occasionally, however, applications
way to transfer larger representations in a block-wise fashion. 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 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 January 12, 2012. This Internet-Draft will expire on July 16, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 5 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6
2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 5 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6
2.2. Using the Block Options . . . . . . . . . . . . . . . . . 7 2.2. Using the Block Options . . . . . . . . . . . . . . . . . 10
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1. HTTP Mapping Considerations . . . . . . . . . . . . . . . 15 4. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 19
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22
5.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 18 6.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 22
5.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 19 6.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 23
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 24
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.1. Normative References . . . . . . . . . . . . . . . . . . . 21 8.1. Normative References . . . . . . . . . . . . . . . . . . . 25
7.2. Informative References . . . . . . . . . . . . . . . . . . 21 8.2. Informative References . . . . . . . . . . . . . . . . . . 25
Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 22 Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27
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 4, line 36 skipping to change at page 5, line 36
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119, BCP 14 document are to be interpreted as described in RFC 2119, BCP 14
[RFC2119] and indicate requirement levels for compliant CoAP [RFC2119] and indicate requirement levels for compliant CoAP
implementations. implementations.
In this document, the term "byte" is used in its now customary sense In this document, the term "byte" is used in its now customary sense
as a synonym for "octet". as a synonym for "octet".
Where bit arithmetic is explained, this document uses the notation Where bit arithmetic is explained, this document uses the notation
familiar from the programming language C, except that the operator familiar from the programming language C, except that the operator
"^" stands for exponentiation. "**" stands for exponentiation.
2. Block-wise transfers 2. Block-wise transfers
As discussed in the introduction, there are good reasons to limit the
size datagrams in constrained networks:
o by the maximum datagram size (~ 64 KiB for UDP)
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)
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 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.
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; still this size will be given as the block size even for the
final block.
2.1. The Block Options 2.1. The Block Options
+------+----------+--------+--------+--------+---------------+ +------+----------+--------+--------+--------+---------------+
| Type | C/E | Name | Format | Length | Default | | Type | C/E | Name | Format | Length | Default |
+------+----------+--------+--------+--------+---------------+ +------+----------+--------+--------+--------+---------------+
| 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) | | 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) |
| | | | | | | | | | | | | |
| 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) | | 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) |
+------+----------+--------+--------+--------+---------------+ +------+----------+--------+--------+--------+---------------+
Table 1: Block Option Numbers Table 1: Block Option Numbers
The Block1 Option pertains to request payloads (the _first_ part of Both Block1 and Block2 options can be present both in request and
the request-response exchange, hence Block1), and the Block2 Option response messages. In either case, the Block1 Option pertains to the
pertains to response payloads (the _second_ part of the request- request payload, and the Block2 Option pertains to the response
response exchange). (Note that either option can be used in both payload.
requests and responses, see more below.)
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]).
(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.,
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. 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
(or the message rejected); therefore it is identified as a critical (or the message rejected); therefore it is identified as a critical
option. option.
The size of the blocks is not fixed by the protocol. To keep the Three items of information may need to be transferred in a Block
implementation as simple as possible, the Block options support a option:
small range of power-of-two block sizes, from 2^4 (16) to 2^10 (1024)
bytes. One of these seven values can be encoded in three bits (0 for
2^4 to 6 for 2^10 bytes), which we call the "SZX" (size exponent);
the actual block size is then "1 << (SZX + 4)". (The actual size of
the final block in a block-wise transfer may be less than or equal to
the power-of-two block size.)
When a resource representation is larger than can be comfortably o The size of the block (SZX);
transferred in a single UDP datagram, a Block option can be used to
indicate a block-wise transfer. The value of the option is a 1-, 2- o whether more blocks are following (M);
or 3-byte integer, the four least significant bits of which indicate
the size and whether the current block-wise transfer is the last o the relative number of the block (NUM) within a sequence of blocks
block being transferred (indicated by the M or "more" bit). The with the given size.
option value divided by sixteen (the NUM field) is the number of the
block currently being transferred, starting from zero. The current The value of the option is a 1-, 2- or 3-byte integer which encodes
transfer is therefore about the "size" bytes starting at byte "block these three fields, see Figure 1.
number << (SZX + 4)" (although the power-of-two size need not be
reached in the final block). The default value of each of the Block
options is zero, indicating that the current block is the first
(block number 0) and only (M bit not set) block of the transfer;
however, there is no explicit size implied by this default value.
0 0
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| NUM |M| SZX | | NUM |M| SZX |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
0 1 0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
skipping to change at page 6, line 25 skipping to change at page 8, line 25
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 1 2 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 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 | | NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 1: Block option value Figure 1: Block option value
(Note that, as an implementation convenience, the option value with The block size is encoded as 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)". (Note that, 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, the last 4 bits masked out, shifted to the left by the value of SZX,
gives the byte position of the block.) gives the byte position of the block.)
The default value of both the Block1 and the Block2 Option is zero,
indicating that the current block is the first and only block of the
transfer (block number 0, M bit not set); however, there is no
explicit size implied by this default value.
More specifically, within the option value of a Block1 or Block2
Option, the meaning of the option fields is defined as follows:
NUM: Block Number. The block number is a variable-size (4, 12, or NUM: Block Number. The block number is a variable-size (4, 12, or
20 bit) unsigned integer (uint, see Appendix A of 20 bit) unsigned integer (uint, see Appendix A of
[I-D.ietf-core-coap]) indicating the block number being requested [I-D.ietf-core-coap]) indicating the block number being requested
or provided. Block number 0 indicates the first block of a or provided. Block number 0 indicates the first block of a body.
representation.
M: More Flag (not last block). This flag, if unset, indicates that M: More Flag (not last block). For descriptive usage, this flag, if
this block is the last in a representation. When set it indicates unset, indicates that the payload in this message is the last
that there are one or more additional blocks available. When a block in the body; when set it indicates that there are one or
Block2 Option is used in a request to retrieve a specific block more additional blocks available. When a Block2 Option is used in
number, the M bit MUST be sent as zero and ignored on reception. a request to retrieve a specific block number ("control usage"),
(In a Block1 Option in a response, the M flag is used to indicate 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.) atomicity, see below.)
SZX: Block Size. The block size is a three-bit unsigned integer SZX: Block Size. The block size is a three-bit unsigned integer
indicating the size of a block to the power of two. Thus block indicating the size of a block to the power of two. Thus block
size = 2^(SZX + 4). The allowed values of SZX are 0 to 6, i.e., size = 2**(SZX + 4). The allowed values of SZX are 0 to 6, i.e.,
the minimum block size is 2^(0+4) = 16 and the maximum is 2^(6+4) the minimum block size is 2**(0+4) = 16 and the maximum is
= 1024. The value 7 for SZX (which would indicate a block size of 2**(6+4) = 1024. The value 7 for SZX (which would indicate a
2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00 block size of 2048) is reserved, i.e. MUST NOT be sent and MUST
Bad Request response code upon reception in a request. lead to a 4.00 Bad Request response code upon reception in a
request.
The Block options are used in one of three roles: The Block options are used in one of three roles:
o In a request (e.g., GET), the Block2 Option gives the block number o In descriptive usage, i.e. a Block2 Option in a response (e.g., a
requested to be returned in the response and suggests a block size 2.05 response for GET), or a Block1 Option in a request (e.g., PUT
(in the case of block number 0) or echoes the block size of or POST):
previous blocks received (in the case of block numbers other than
0). In this case, the M bit has no function and MUST be set to
zero.
o A Block2 Option in a response (e.g., for GET), or a Block1 Option * The NUM field in the option value describes what block number
in a request (e.g., PUT or POST), describes what block number is is contained in the payload of this message.
contained in the payload of this message, and whether further
blocks are required to complete the transfer of that body (M bit).
If the M bit is set, the size of the payload body in bytes MUST
indeed be the power of two given by the block size. With certain
exceptions given below, all blocks for a REST transfer MUST use
the same block size, except for the last block (M bit not set).
o In a response, the Block1 Option indicates what block number is * The M bit indicates whether further blocks are required to
being acknowledged (e.g., for a PUT or POST request). In this complete the transfer of that body.
case, if the M bit is set it indicates that this response does not
carry the final response to the request; this can occur when the M * The block size given by SZX MUST match the size of the payload
bit was set in the request and the server implements the request in bytes, if the M bit is set. (The block size given is
atomically (i.e., acts only upon reception of the last block of irrelevant if M is unset). For Block2, if the request
payload). Conversely, if the M bit is unset, it indicates the suggested a larger value of SZX, the next request MUST move SZX
block-wise request was enacted now, and the response carries the down to the size given here. (The effect is that, if the
final response to this request (and to any previous ones with the server uses the smaller of its preferred block size and the one
M bit set in the response's Block1 Option in this sequence of requested, all blocks for a body use the same block size.)
block-wise transfers). Finally, the block size given in such a
Block1 Option indicates the largest block size preferred by the o A Block2 Option in control usage in a request (e.g., GET):
server for transfers toward the resource that is the same or
smaller than the one used in the initial exchange; the client * The NUM field in the Block2 Option gives the block number of
SHOULD use this block size or a smaller one in all further the payload that is being requested to be returned in the
requests in the transfer sequence. 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 block numbers other than 0).
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 and plans to implement the request atomically
(e.g., acts only upon reception of the last block of payload).
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
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.
2.2. Using the Block Options 2.2. Using the Block Options
Using one or both Block options, a single REST operation can be split Using one or both Block options, a single REST operation can be split
into multiple CoAP message exchanges. Each of these message into multiple CoAP message exchanges. As specified in
exchanges uses their own CoAP Message ID. [I-D.ietf-core-coap], each of these message exchanges uses their own
CoAP Message ID.
When a request is answered with a response carrying a Block2 Option When a request is answered with a response carrying a Block2 Option
with the M bit set, the requester may retrieve additional blocks of with the M bit set, the requester may retrieve additional blocks of
the resource representation by sending further requests with the same the resource representation by sending further requests with the same
options and a Block2 Option giving the block number and block size 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 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. Option to zero and the server MUST ignore it on reception.
To influence the block size used in a response, the requester also To influence the block size used in a response, the requester also
uses the Block2 Option, giving the desired size, a block number of uses the Block2 Option, giving the desired size, a block number of
skipping to change at page 8, line 38 skipping to change at page 11, line 45
resources. In the latter case, the Block2 Option SHOULD be used in resources. In the latter case, the Block2 Option SHOULD be used in
conjunction with the ETag Option, to ensure that the blocks being conjunction with the ETag Option, to ensure that the blocks being
reassembled are from the same version of the representation: The reassembled are from the same version of the representation: The
server SHOULD include an ETag option in each response. If an ETag server SHOULD include an ETag option in each response. If an ETag
option is available, the client's reassembler, when reassembling the option is available, the client's reassembler, when reassembling the
representation from the blocks being exchanged, MUST compare ETag representation from the blocks being exchanged, MUST compare ETag
Options. If the ETag Options do not match in a GET transfer, the Options. If the ETag Options do not match in a GET transfer, the
requester has the option of attempting to retrieve fresh values for requester has the option of attempting to retrieve fresh values for
the blocks it retrieved first. To minimize the resulting the blocks it retrieved first. To minimize the resulting
inefficiency, the server MAY cache the current value of a inefficiency, the server MAY cache the current value of a
representation for an ongoing sequence of requests, but there is no representation for an ongoing sequence of requests. The client MAY
requirement for the server to establish any state. The client MAY
facilitate identifying the sequence by using the Token Option with a facilitate identifying the sequence by using the Token Option with a
non-default value. non-default value. 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.
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 body in the request. 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. Obviously, at block size preference of the server for this resource (control
this point the first block has already been transferred by the client usage). Obviously, at this point the first block has already been
without benefit of this knowledge. Still, the client SHOULD heed the transferred by the client without benefit of this knowledge. Still,
preference and use the block size preferred by the server or a the client SHOULD heed the preference and, for all further blocks,
smaller one. Note that any reduction in the block size may mean that use the block size preferred by the server or a smaller one. Note
the second request starts with a block number larger than one, as the that any reduction in the block size may mean that the second request
first request already transferred multiple blocks as counted in the starts with a block number larger than one, as the first request
smaller size. 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) 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. If not all previous blocks are available at the server
at this time, the transfer fails and error code 4.08 (Request Entity at this time, the transfer fails and error code 4.08 (Request Entity
Incomplete) MUST be returned. The error code 4.13 (Request Entity Incomplete) MUST be returned. The error code 4.13 (Request Entity
Too Large) can be returned at any time by a server that does not 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 currently have the resources to store blocks for a block-wise request
skipping to change at page 10, line 15 skipping to change at page 13, line 15
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
separating the kind of Block option (1 or 2), block number (NUM), separating the kind of Block option (1 or 2), block number (NUM),
more bit (M), and block size exponent (2^(SZX+4)) by slashes. E.g., more bit (M), and block size exponent (2**(SZX+4)) by slashes. E.g.,
a Block2 Option value of 33 would be shown as 2/2/0/32), or a Block1 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. Option value of 59 would be shown as 1/3/1/128.
The first example (Figure 2) shows a GET request that is split into 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 three blocks. The server proposes a block size of 128, and the
client agrees. The first two ACKs contain 128 bytes of payload each, client agrees. The first two ACKs contain 128 bytes of payload each,
and third ACK contains between 1 and 128 bytes. and third ACK contains between 1 and 128 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], GET, /status ------> | | CON [MID=1234], GET, /status ------> |
| | | |
| <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 |
| | | |
| CON [MID=1235], GET, /status, 2/1/0/128 ------> | | CON [MID=1235], GET, /status, 2/1/0/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.05 Content, 2/1/1/128 | | <------ ACK [MID=1235], 2.05 Content, 2/1/1/128 |
| | | |
| CON [MID=1236], GET, /status, 2/2/0/128 ------> | | CON [MID=1236], GET, /status, 2/2/0/128 ------> |
| | | |
| <------ ACK [MID=1236], 2.05 Content, 2/2/0/128 | | <------ ACK [MID=1236], 2.05 Content, 2/2/0/128 |
skipping to change at page 15, line 25 skipping to change at page 19, line 5
| CON [MID=1236], PUT, /options, v17, 1/5/1/32 ------> | | CON [MID=1236], PUT, /options, v17, 1/5/1/32 ------> |
| | | |
| <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 | | <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 |
| | | |
| CON [MID=1237], PUT, /options, v17, 1/6/0/32 ------> | | CON [MID=1237], PUT, /options, v17, 1/6/0/32 ------> |
| | | |
| <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 | | <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 |
Figure 9: Simple atomic blockwise PUT with negotiation Figure 9: Simple atomic blockwise PUT with negotiation
3.1. HTTP Mapping Considerations 4. HTTP Mapping Considerations
In this subsection, we give some brief examples for the influence the In this subsection, we give some brief examples for the influence the
Block options might have on intermediaries that map between CoAP and Block options might have on intermediaries that map between CoAP and
HTTP. HTTP.
For mapping CoAP requests to HTTP, the intermediary may want to map For mapping CoAP requests to HTTP, the intermediary may want to map
the block-wise transfer into a single HTTP transfer. E.g., for a GET the sequence of block-wise transfers into a single HTTP transfer.
request, the intermediary could perform the HTTP request once the E.g., for a GET request, the intermediary could perform the HTTP
first block has been requested and could then fulfill all further request once the first block has been requested and could then
block requests out of its cache. A constrained implementation may fulfill all further block requests out of its cache. A constrained
not be able to cache the entire object and may use a combination of implementation may not be able to cache the entire object and may use
TCP flow control and (in particular if timeouts occur) HTTP range a combination of TCP flow control and (in particular if timeouts
requests to obtain the information necessary for the next block occur) HTTP range requests to obtain the information necessary for
transfer at the right time. the next block transfer at the right time.
For PUT or POST requests, there is more variation in how HTTP servers For PUT or POST requests, there is more variation in how HTTP servers
might implement ranges. Some WebDAV servers do, but in general the might implement ranges. Some WebDAV servers do, but in general the
CoAP-to-HTTP intermediary will have to try sending the payload of all 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 the blocks of a block-wise transfer within one HTTP request. If
enough buffering is available, this request can be started when the enough buffering is available, this request can be started when the
last CoAP block is received. A constrained implementation may want last CoAP block is received. A constrained implementation may want
to relieve its buffering by already starting to send the HTTP request 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 at the time the first CoAP block is received; any HTTP 408 status
code that indicates that the HTTP server became impatient with the code that indicates that the HTTP server became impatient with the
resulting transfer can then be mapped into a CoAP 4.08 response code resulting transfer can then be mapped into a CoAP 4.08 response code
(similarly, 413 maps to 4.13). (similarly, 413 maps to 4.13).
For mapping HTTP to CoAP, the intermediary may want to map a single For mapping HTTP to CoAP, the intermediary may want to map a single
HTTP transfer into a block-wise transfer. If the HTTP client is too HTTP transfer into a sequence of block-wise transfers. If the HTTP
slow delivering a request body on a PUT or POST, the CoAP server client is too slow delivering a request body on a PUT or POST, the
might time out and return a 4.08 response code, which in turn maps CoAP server might time out and return a 4.08 response code, which in
well to an HTTP 408 status code (again, 4.13 maps to 413). HTTP turn maps well to an HTTP 408 status code (again, 4.13 maps to 413).
range requests received on the HTTP side may be served out of a cache HTTP range requests received on the HTTP side may be served out of a
and/or mapped to GET requests that request a sequence of blocks cache and/or mapped to GET requests that request a sequence of blocks
overlapping the range. overlapping the range.
(Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, (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 this difference is largely due to the different way the two protocols
are mapped to transport. HTTP has an underlying TCP connection, are mapped to transport. HTTP has an underlying TCP connection,
which supplies connection state, so a HTTP 408 status code can which supplies connection state, so a HTTP 408 status code can
immediately be used to indicate that a timeout occurred during immediately be used to indicate that a timeout occurred during
transmitting a request through that active TCP connection. The CoAP transmitting a request through that active TCP connection. The CoAP
4.08 response code indicates one or more missing blocks, which may be 4.08 response code indicates one or more missing blocks, which may be
due to timeouts or resource constraints; as there is no connection due to timeouts or resource constraints; as there is no connection
state, there is no way to deliver such a response immediately; state, there is no way to deliver such a response immediately;
instead, it is delivered on the next block transfer. Still, HTTP 408 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 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 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 distinguish a timeout from a missing block for a server without
creating additional state, the need for which we want to avoid.) creating additional state, the need for which we want to avoid.)
4. IANA Considerations 5. IANA Considerations
This draft adds the following option number to the CoAP Option This draft adds the following option numbers to the CoAP Option
Numbers registry of [I-D.ietf-core-coap]: Numbers registry of [I-D.ietf-core-coap]:
+--------+--------+-----------+ +--------+--------+-----------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+--------+-----------+ +--------+--------+-----------+
| 17 | Block2 | [RFCXXXX] | | 17 | Block2 | [RFCXXXX] |
| | | | | | | |
| 19 | Block1 | [RFCXXXX] | | 19 | Block1 | [RFCXXXX] |
+--------+--------+-----------+ +--------+--------+-----------+
skipping to change at page 18, line 5 skipping to change at page 22, line 5
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] | | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] |
+------+--------------------------------+-----------+ +------+--------------------------------+-----------+
Table 3: CoAP Response Codes Table 3: CoAP Response Codes
5. Security Considerations 6. 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
intrusion detection systems; it is RECOMMENDED that an intrusion intrusion detection systems; it is RECOMMENDED that an intrusion
detection system (IDS) that analyzes resource representations detection system (IDS) that analyzes resource representations
transferred by CoAP implement the Block options to gain access to transferred by CoAP implement the Block options to gain access to
entire resource representations. Still, approaches such as entire resource representations. Still, approaches such as
skipping to change at page 18, line 33 skipping to change at page 22, line 33
Where access to a resource is only granted to clients making use of a Where access to a resource is only granted to clients making use of a
specific security association, all blocks of that resource MUST be specific security association, all blocks of that resource MUST be
subject to the same security checks; it MUST NOT be possible for subject to the same security checks; it MUST NOT be possible for
unprotected exchanges to influence blocks of an otherwise protected unprotected exchanges to influence blocks of an otherwise protected
resource. As a related consideration, where object security is resource. As a related consideration, where object security is
employed, PUT/POST should be implemented in the atomic fashion, employed, PUT/POST should be implemented in the atomic fashion,
unless the object security operation is performed on each access and unless the object security operation is performed on each access and
the creation of unusable resources can be tolerated. the creation of unusable resources can be tolerated.
5.1. Mitigating Resource Exhaustion Attacks 6.1. Mitigating Resource Exhaustion Attacks
Certain blockwise requests may induce the server to create state, Certain blockwise requests may induce the server to create state,
e.g. to create a snapshot for the blockwise GET of a fast-changing 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 to enable consistent access to the same version of a
resource for all blocks, or to create temporary resource resource for all blocks, or to create temporary resource
representations that are collected until pressed into service by a representations that are collected until pressed into service by a
final PUT or POST with the more bit unset. All mechanisms that final PUT or POST with the more bit unset. All mechanisms that
induce a server to create state that cannot simply be cleaned up induce a server to create state that cannot simply be cleaned up
create opportunities for denial-of-service attacks. Servers SHOULD create opportunities for denial-of-service attacks. Servers SHOULD
avoid being subject to resource exhaustion based on state created by avoid being subject to resource exhaustion based on state created by
skipping to change at page 19, line 13 skipping to change at page 23, line 13
fragmentation, adaptation layer fragmentation), e.g. because there is fragmentation, adaptation layer fragmentation), e.g. because there is
application layer semantics that can be used for mitigation or application layer semantics that can be used for mitigation or
because lower layers provide security associations that can prevent because lower layers provide security associations that can prevent
attacks. However, it is less common to apply timeouts and keepalive attacks. However, it is less common to apply timeouts and keepalive
mechanisms at the application layer than at lower layers. Servers mechanisms at the application layer than at lower layers. Servers
MAY want to clean up accumulated state by timing it out (cf. response 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 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 in an expedient way to minimize the likelihood of running into such a
timeout. timeout.
5.2. Mitigating Amplification Attacks 6.2. Mitigating Amplification Attacks
[I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points
for use in amplification attacks. for use in amplification attacks.
A CoAP server can reduce the amount of amplification it provides to A CoAP server can reduce the amount of amplification it provides to
an attacker by offering large resource representations only in an attacker by offering large resource representations only in
relatively small blocks. With this, e.g., for a 1000 byte resource, 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 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 block) instead of a 1016-byte response, considerably reducing the
amplification provided. amplification provided.
6. Acknowledgements 7. 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.
Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. Tokens were suggested by Gilman Tolle and refined by Klaus Hartke.
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. in this version.
7. References 8. References
7.1. Normative References 8.1. Normative References
[I-D.ietf-core-coap] [I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank, Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)", "Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-07 (work in progress), July 2011. draft-ietf-core-coap-08 (work in progress), October 2011.
[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.
7.2. Informative References 8.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", 2000. Network-based Software Architectures", 2000.
Appendix A. Historical Note Appendix A. Historical Note
(This appendix to be deleted by the RFC editor.)
An earlier version of this draft used a single option: An earlier version of this draft used a single option:
+------+----------+-------+--------+--------+---------------+ +------+----------+-------+--------+--------+---------------+
| Type | C/E | Name | Format | Length | Default | | Type | C/E | Name | Format | Length | Default |
+------+----------+-------+--------+--------+---------------+ +------+----------+-------+--------+--------+---------------+
| 13 | Critical | Block | uint | 1-3 B | 0 (see below) | | 13 | Critical | Block | uint | 1-3 B | 0 (see below) |
+------+----------+-------+--------+--------+---------------+ +------+----------+-------+--------+--------+---------------+
Note that this option number has since been reallocated in Note that this option number has since been reallocated in
[I-D.ietf-core-coap]; no backwards compatibility is provided after [I-D.ietf-core-coap]; no backwards compatibility is provided after
 End of changes. 40 change blocks. 
138 lines changed or deleted 265 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/