draft-ietf-core-block-21.txt   rfc7959.txt 
CoRE Working Group C. Bormann Internet Engineering Task Force (IETF) C. Bormann
Internet-Draft Universitaet Bremen TZI Request for Comments: 7959 Universitaet Bremen TZI
Updates: 7252 (if approved) Z. Shelby, Ed. Updates: 7252 Z. Shelby, Ed.
Intended status: Standards Track ARM Category: Standards Track ARM
Expires: January 9, 2017 July 08, 2016 ISSN: 2070-1721 August 2016
Block-wise transfers in CoAP Block-Wise Transfers in the Constrained Application Protocol (CoAP)
draft-ietf-core-block-21
Abstract Abstract
CoAP is a RESTful transfer protocol for constrained nodes and The Constrained Application Protocol (CoAP) is a RESTful transfer
networks. Basic CoAP messages work well for the small payloads we protocol for constrained nodes and networks. Basic CoAP messages
expect from temperature sensors, light switches, and similar work well for small payloads from sensors and actuators; however,
building-automation devices. Occasionally, however, applications applications will need to transfer larger payloads occasionally --
will need to transfer larger payloads -- for instance, for firmware for instance, for firmware updates. In contrast to HTTP, where TCP
updates. With HTTP, TCP does the grunt work of slicing large does the grunt work of segmenting and resequencing, CoAP is based on
payloads up into multiple packets and ensuring that they all arrive datagram transports such as UDP or Datagram Transport Layer Security
and are handled in the right order. (DTLS). These transports only offer fragmentation, which is even
more problematic in constrained nodes and networks, limiting the
CoAP is based on datagram transports such as UDP or DTLS, which maximum size of resource representations that can practically be
limits the maximum size of resource representations that can be transferred.
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 Instead of relying on IP fragmentation, this specification extends
basic CoAP with a pair of "Block" options, for transferring multiple basic CoAP with a pair of "Block" options for transferring multiple
blocks of information from a resource representation in multiple blocks of information from a resource representation in multiple
request-response pairs. In many important cases, the Block options request-response pairs. In many important cases, the Block options
enable a server to be truly stateless: the server can handle each enable a server to be truly stateless: the server can handle each
block transfer separately, with no need for a connection setup or block transfer separately, with no need for a connection setup or
other server-side memory of previous block transfers. other server-side memory of previous block transfers. Essentially,
the Block options provide a minimal way to transfer larger
In summary, the Block options provide a minimal way to transfer representations in a block-wise fashion.
larger representations in a block-wise fashion.
A CoAP implementation that does not support these options generally A CoAP implementation that does not support these options generally
is limited in the size of the representations that can be exchanged. is limited in the size of the representations that can be exchanged,
There is therefore an expectation that the Block options are very so there is an expectation that the Block options will be widely used
widely implemented in CoAP implementations, which is why this in CoAP implementations. Therefore, this specification updates
specification is listed as "updating" RFC 7252. RFC 7252.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on January 9, 2017. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7959.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . 6 2. Block-Wise Transfers . . . . . . . . . . . . . . . . . . . . 6
2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 7 2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 7
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 8
2.3. Block Options in Requests and Responses . . . . . . . . . 9 2.3. Block Options in Requests and Responses . . . . . . . . . 10
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 11 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 12
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 13 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 14
2.6. Combining Block-wise Transfers with the Observe Option . 14 2.6. Combining Block-Wise Transfers with the Observe Option . 15
2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 15 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 16
2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 15 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 16
2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 16 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 17
2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 16 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 17
2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 16 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 17
2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 16 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 17
2.10. Caching Considerations . . . . . . . . . . . . . . . . . 18
2.10. Caching Considerations . . . . . . . . . . . . . . . . . 17 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 19
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 18 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 23
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 22 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 25
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 23 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 26
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 25 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 29
4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 28 5. HTTP-Mapping Considerations . . . . . . . . . . . . . . . . . 31
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 30 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 7. Security Considerations . . . . . . . . . . . . . . . . . . . 33
7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 33
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 32 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 34
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 33 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 8.1. Normative References . . . . . . . . . . . . . . . . . . 34
8.1. Normative References . . . . . . . . . . . . . . . . . . 33 8.2. Informative References . . . . . . . . . . . . . . . . . 35
8.2. Informative References . . . . . . . . . . . . . . . . . 33 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 36
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35
1. Introduction 1. Introduction
The work on Constrained RESTful Environments (CoRE) aims at realizing The work on Constrained RESTful Environments (CoRE) aims at realizing
the REST architecture in a suitable form for the most constrained the Representational State Transfer (REST) architecture in a suitable
nodes (such as microcontrollers with limited RAM and ROM [RFC7228]) form for the most constrained nodes (such as microcontrollers with
and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP limited RAM and ROM [RFC7228]) and networks (such as IPv6 over Low-
protocol is intended to provide RESTful [REST] services not unlike Power Wireless Personal Area Networks (6LoWPANs) [RFC4944])
HTTP [RFC7230], while reducing the complexity of implementation as [RFC7252]. The CoAP protocol is intended to provide RESTful [REST]
well as the size of packets exchanged in order to make these services services not unlike HTTP [RFC7230], while reducing the complexity of
useful in a highly constrained network of themselves highly implementation as well as the size of packets exchanged in order to
make these services useful in a highly constrained network of highly
constrained nodes. constrained nodes.
This objective requires restraint in a number of sometimes This objective requires restraint in a number of sometimes
conflicting ways: conflicting ways:
o reducing implementation complexity in order to minimize code size, o reducing implementation complexity in order to minimize code size,
o reducing message sizes in order to minimize the number of o reducing message sizes in order to minimize the number of
fragments needed for each message (in turn to maximize the fragments needed for each message (to maximize the probability of
probability of delivery of the message), the amount of delivery of the message), the amount of transmission power needed,
transmission power needed and the loading of the limited-bandwidth and the loading of the limited-bandwidth channel,
channel,
o reducing requirements on the environment such as stable storage, o reducing requirements on the environment such as stable storage,
good sources of randomness or user interaction capabilities. good sources of randomness, or user-interaction capabilities.
CoAP is based on datagram transports such as UDP, which limit the Because CoAP is based on datagram transports such as UDP or Datagram
maximum size of resource representations that can be transferred Transport Layer Security (DTLS), the maximum size of resource
without creating unreasonable levels of IP fragmentation. In representations that can be transferred without too much
addition, not all resource representations will fit into a single fragmentation is limited. In addition, not all resource
link layer packet of a constrained network, which may cause representations will fit into a single link-layer packet of a
adaptation layer fragmentation even if IP layer fragmentation is not constrained network, which may cause adaptation layer fragmentation
required. Using fragmentation (either at the adaptation layer or at even if IP-layer fragmentation is not required. Using fragmentation
the IP layer) for the transport of larger representations would be (either at the adaptation layer or at the IP layer) for the transport
possible up to the maximum size of the underlying datagram protocol of larger representations would be possible up to the maximum size of
(such as UDP), but the fragmentation/reassembly process burdens the the underlying datagram protocol (such as UDP), but the
lower layers with conversation state that is better managed in the fragmentation/reassembly process burdens the lower layers with
application layer. conversation state that is better managed in the application layer.
The present specification defines a pair of CoAP options to enable The present specification defines a pair of CoAP options to enable
_block-wise_ access to resource representations. The Block options block-wise access to resource representations. The Block options
provide a minimal way to transfer larger resource representations in provide a minimal way to transfer larger resource representations in
a block-wise fashion. The overriding objective is to avoid the need a block-wise fashion. The overriding objective is to avoid the need
for creating conversation state at the server for block-wise GET for creating conversation state at the server for block-wise GET
requests. (It is impossible to fully avoid creating conversation requests. (It is impossible to fully avoid creating conversation
state for POST/PUT, if the creation/replacement of resources is to be 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 atomic; where that property is not needed, there is no need to create
server conversation state in this case, either.) server conversation state in this case, either.)
Block-wise transfers are realized as combinations of exchanges, each Block-wise transfers are realized as combinations of exchanges, each
of which is performed according to the CoAP base protocol [RFC7252]. of which is performed according to the CoAP base protocol [RFC7252].
Each exchange in such a combination is governed by the specifications Each exchange in such a combination is governed by the specifications
in [RFC7252], including the congestion control specifications in [RFC7252], including the congestion control specifications
(Section 4.7 of [RFC7252]) and the security considerations (Section 4.7 of [RFC7252]) and the security considerations
(Section 11 of [RFC7252]; additional security considerations then (Section 11 of [RFC7252]; additional security considerations then
apply to the transfers as a whole, see Section 7). The present apply to the transfers as a whole, see Section 7). The present
specification minimizes the constraints it adds to those base specification minimizes the constraints it adds to those base
exchanges; however, not all variants of using CoAP are very useful exchanges; however, not all variants of using CoAP are very useful
inside a block-wise transfer (e.g., using Non-confirmable requests inside a block-wise transfer (e.g., using Non-confirmable requests
skipping to change at page 4, line 37 skipping to change at page 5, line 18
(Section 4.7 of [RFC7252]) and the security considerations (Section 4.7 of [RFC7252]) and the security considerations
(Section 11 of [RFC7252]; additional security considerations then (Section 11 of [RFC7252]; additional security considerations then
apply to the transfers as a whole, see Section 7). The present apply to the transfers as a whole, see Section 7). The present
specification minimizes the constraints it adds to those base specification minimizes the constraints it adds to those base
exchanges; however, not all variants of using CoAP are very useful exchanges; however, not all variants of using CoAP are very useful
inside a block-wise transfer (e.g., using Non-confirmable requests inside a block-wise transfer (e.g., using Non-confirmable requests
within block-wise transfers outside the use case of Section 2.8 would within block-wise transfers outside the use case of Section 2.8 would
escalate the overall non-delivery probability). To be perfectly escalate the overall non-delivery probability). To be perfectly
clear, the present specification also does not remove any of the clear, the present specification also does not remove any of the
constraints posed by the base specification it is strictly layered on constraints posed by the base specification it is strictly layered on
top of; e.g., back-to-back packets are limited by Section 4.7 of top of. For example, back-to-back packets are limited by the
[RFC7252] (NSTART as a limit for initiating exchanges, PROBING_RATE congestion control described in Section 4.7 of [RFC7252] (NSTART as a
as a limit for sending with no response): block-wise transfers cannot limit for initiating exchanges, PROBING_RATE as a limit for sending
send/solicit more traffic than a client could be sending to the same with no response); block-wise transfers cannot send/solicit more
traffic than a client could be sending to / soliciting from the same
server without the block-wise mode. server without the block-wise mode.
In some cases, the present specification will RECOMMEND that a client In some cases, the present specification will RECOMMEND that a client
perform a sequence of block-wise transfers "without undue delay". perform a sequence of block-wise transfers "without undue delay".
This cannot be phrased as an interoperability requirement, but is an This cannot be phrased as an interoperability requirement, but is an
expectation on implementation quality. Conversely, the expectation expectation on implementation quality. Conversely, the expectation
is that servers will not have go out of their way to accommodate is that servers will not have to go out of their way to accommodate
clients that take forever to finish a block-wise transfer. E.g., for clients that take considerable time to finish a block-wise transfer.
a block-wise GET, if the resource changes while this proceeds, the For example, for a block-wise GET, if the resource changes while this
ETag for a further block obtained may be different. To avoid this proceeds, the entity-tag (ETag) for a further block obtained may be
happening all the time for a fast-changing resource, a server MAY try different. To avoid this happening all the time for a fast-changing
to keep a cache around for a specific client for a short amount of resource, a server MAY try to keep a cache around for a specific
time. The expectation here is that the lifetime for such a cache can client for a short amount of time. The expectation here is that the
be kept short, on the order of a few expected round-trip times, lifetime for such a cache can be kept short, on the order of a few
counting from the previous block transferred. expected round-trip times, counting from the previous block
transferred.
In summary, this specification adds a pair of Block options to CoAP In summary, this specification adds a pair of Block options to CoAP
that can be used for block-wise transfers. Benefits of using these that can be used for block-wise transfers. Benefits of using these
options include: options include:
o Transfers larger than what can be accommodated in constrained- o Transfers larger than what can be accommodated in constrained-
network link-layer packets can be performed in smaller blocks. network link-layer packets can be performed in smaller blocks.
o No hard-to-manage conversation state is created at the adaptation o No hard-to-manage conversation state is created at the adaptation
layer or IP layer for fragmentation. layer or IP layer for fragmentation.
o The transfer of each block is acknowledged, enabling individual o The transfer of each block is acknowledged, enabling individual
retransmission if required. retransmission if required.
o Both sides have a say in the block size that actually will be o Both sides have a say in the block size that actually will be
used. used.
o The resulting exchanges are easy to understand using packet o The resulting exchanges are easy to understand using packet
analyzer tools and thus quite accessible to debugging. analyzer tools, and thus quite accessible to debugging.
o If needed, the Block options can also be used (without changes) to o If needed, the Block options can also be used (without changes) to
provide random access to power-of-two sized blocks within a provide random access to power-of-two sized blocks within a
resource representation. resource representation.
A CoAP implementation that does not support these options generally A CoAP implementation that does not support these options generally
is limited in the size of the representations that can be exchanged, is limited in the size of the representations that can be exchanged,
see Section 4.6 of [RFC7252]. Even though the options are Critical, see Section 4.6 of [RFC7252]. Even though the options are Critical,
a server may decide to start using them in an unsolicited way in a a server may decide to start using them in an unsolicited way in a
response. No effort was expended to provide a capability indication response. No effort was expended to provide a capability indication
skipping to change at page 6, line 9 skipping to change at page 6, line 38
2119, BCP 14 [RFC2119] and indicate requirement levels for compliant 2119, BCP 14 [RFC2119] and indicate requirement levels for compliant
CoAP implementations. CoAP 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 As discussed in the introduction, there are good reasons to limit the
size of datagrams in constrained networks: size of datagrams in constrained networks:
o by the maximum datagram size (~ 64 KiB for UDP) 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 IP fragmentation (MTU of 1280 for IPv6)
o by the desire to avoid adaptation layer fragmentation (60-80 bytes o by the desire to avoid adaptation-layer fragmentation (60-80 bytes
for 6LoWPAN [RFC4919]) for 6LoWPAN [RFC4919])
When a resource representation is larger than can be comfortably When a resource representation is larger than can be comfortably
transferred in the payload of a single CoAP datagram, a Block option transferred in the payload of a single CoAP datagram, a Block option
can be used to indicate a block-wise transfer. As payloads can be can be used to indicate a block-wise transfer. As payloads can be
sent both with requests and with responses, this specification sent both with requests and with responses, this specification
provides two separate options for each direction of payload transfer. provides two separate options for each direction of payload transfer.
In naming these options (for block-wise transfers as well as in In naming these options (for block-wise transfers as well as in
Section 4), we use the number 1 ("Block1", "Size1") to refer to the Section 4), we use the number 1 ("Block1", "Size1") to refer to the
transfer of the resource representation that pertains to the request, transfer of the resource representation that pertains to the request,
and the number 2 ("Block2", "Size2") to refer to the transfer of the and the number 2 ("Block2", "Size2") to refer to the transfer of the
resource representation for the response. resource representation for the response.
In the following, the term "payload" will be used for the actual In the following, the term "payload" will be used for the actual
content of a single CoAP message, i.e. a single block being content of a single CoAP message, i.e., a single block being
transferred, while the term "body" will be used for the entire transferred, while the term "body" will be used for the entire
resource representation that is being transferred in a block-wise resource representation that is being transferred in a block-wise
fashion. The Content-Format option applies to the body, not to the fashion. The Content-Format Option applies to the body, not to the
payload, in particular the boundaries between the blocks may be in payload; in particular, the boundaries between the blocks may be in
places that are not separating whole units in terms of the structure, places that are not separating whole units in terms of the structure,
encoding, or content-coding used by the Content-Format. (Similarly, encoding, or content-coding used by the Content-Format. (Similarly,
the ETag option defined in Section 5.10.6 of [RFC7252] applies to the the ETag Option defined in Section 5.10.6 of [RFC7252] applies to the
whole representation of the resource and thus to the body of the whole representation of the resource, and thus to the body of the
response.) response.)
In most cases, all blocks being transferred for a body (except for In most cases, all blocks being transferred for a body (except for
the last one) will be of the same size. (If the first request uses a the last one) will be of the same size. (If the first request uses a
bigger block size than the receiver prefers, subsequent requests will bigger block size than the receiver prefers, subsequent requests will
use the preferred block size.) The block size is not fixed by the use the preferred block size.) The block size is not fixed by the
protocol. To keep the implementation as simple as possible, the protocol. To keep the implementation as simple as possible, the
Block options support only a small range of power-of-two block sizes, 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 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 evenly divide into the power-of-two block size chosen, the size need
skipping to change at page 7, line 19 skipping to change at page 7, line 48
+-----+---+---+---+---+--------+--------+--------+---------+ +-----+---+---+---+---+--------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+--------+--------+--------+---------+ +-----+---+---+---+---+--------+--------+--------+---------+
| 23 | C | U | - | - | Block2 | uint | 0-3 | (none) | | 23 | C | U | - | - | Block2 | uint | 0-3 | (none) |
| | | | | | | | | | | | | | | | | | | |
| 27 | C | U | - | - | Block1 | uint | 0-3 | (none) | | 27 | C | U | - | - | Block1 | uint | 0-3 | (none) |
+-----+---+---+---+---+--------+--------+--------+---------+ +-----+---+---+---+---+--------+--------+--------+---------+
Table 1: Block Option Numbers Table 1: Block Option Numbers
Both Block1 and Block2 options can be present both in request and Both Block1 and Block2 Options can be present in both the request and
response messages. In either case, the Block1 Option pertains to the response messages. In either case, the Block1 Option pertains to the
request payload, and the Block2 Option pertains to the response request payload, and the Block2 Option pertains to the response
payload. payload.
Hence, for the methods defined in [RFC7252], Block1 is useful with Hence, for the methods defined in [RFC7252], Block1 is useful with
the payload-bearing POST and PUT requests and their responses. the payload-bearing POST and PUT requests and their responses.
Block2 is useful with GET, POST, and PUT requests and their payload- Block2 is useful with GET, POST, and PUT requests and their payload-
bearing responses (2.01, 2.02, 2.04, 2.05 -- see Section 5.5 of bearing responses (2.01, 2.02, 2.04, and 2.05 -- see Section 5.5 of
[RFC7252]). [RFC7252]).
Where Block1 is present in a request or Block2 in a response (i.e., Where Block1 is present in a request or Block2 in a response (i.e.,
in that message to the payload of which it pertains) it indicates a in that message to the payload of which it pertains) it indicates a
block-wise transfer and describes how this specific block-wise block-wise transfer and describes how this specific block-wise
payload forms part of the entire body being transferred ("descriptive payload forms part of the entire body being transferred ("descriptive
usage"). Where it is present in the opposite direction, it provides usage"). Where it is present in the opposite direction, it provides
additional control on how that payload will be formed or was additional control on how that payload will be formed or was
processed ("control usage"). 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. It MUST NOT occur more than once. option. Either Block option MUST NOT occur more than once in a
single message.
2.2. Structure of a Block Option 2.2. Structure of a Block Option
Three items of information may need to be transferred in a Block Three items of information may need to be transferred in a Block
(Block1 or Block2) option: (Block1 or Block2) option:
o The size of the block (SZX); o the size of the block (SZX);
o whether more blocks are following (M); o whether more blocks are following (M);
o the relative number of the block (NUM) within a sequence of blocks o the relative number of the block (NUM) within a sequence of blocks
with the given size. with the given size.
The value of the Block Option is a variable-size (0 to 3 byte) The value of the Block option is a variable-size (0 to 3 byte)
unsigned integer (uint, see Section 3.2 of [RFC7252]). This integer unsigned integer (uint, see Section 3.2 of [RFC7252]). This integer
value encodes these three fields, see Figure 1. (Due to the CoAP 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 uint-encoding rules, when all of NUM, M, and SZX happen to be zero, a
zero-byte integer will be sent.) zero-byte integer will be sent.)
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| NUM |M| SZX | | NUM |M| SZX |
skipping to change at page 8, line 31 skipping to change at page 9, line 22
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| NUM |M| SZX | | NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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
The block size is encoded using a three-bit unsigned integer (0 for 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 2**4 bytes to 6 for 2**10 bytes), which we call the "SZX" ("size
exponent"); the actual block size is then "2**(SZX + 4)". SZX is exponent"); the actual block size is then "2**(SZX + 4)". SZX is
transferred in the three least significant bits of the option value transferred in the three least significant bits of the option value
(i.e., "val & 7" where "val" is the value of the option). (i.e., "val & 7" where "val" is the value of the option).
The fourth least significant bit, the M or "more" bit ("val & 8"), The fourth least significant bit, the M or "more" bit ("val & 8"),
indicates whether more blocks are following or the current block-wise indicates whether more blocks are following or if the current block-
transfer is the last block being transferred. wise transfer is the last block being transferred.
The option value divided by sixteen (the NUM field) is the sequence The option value divided by sixteen (the NUM field) is the sequence
number of the block currently being transferred, starting from zero. number of the block currently being transferred, starting from zero.
The current transfer is therefore about the "size" bytes starting at The current transfer is, therefore, about the "size" bytes starting
byte "NUM << (SZX + 4)". at byte "NUM << (SZX + 4)".
Implementation note: As an implementation convenience, "(val & ~0xF) Implementation note: As an implementation convenience, "(val & ~0xF)
<< (val & 7)", i.e., the option value with the last 4 bits masked << (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 out, shifted to the left by the value of SZX, gives the byte
position of the first byte of the block being transferred. position of the first byte of the block being transferred.
More specifically, within the option value of a Block1 or Block2 More specifically, within the option value of a Block1 or Block2
Option, the meaning of the option fields is defined as follows: Option, the meaning of the option fields is defined as follows:
NUM: Block Number, indicating the block number being requested or NUM: Block Number, indicating the block number being requested or
provided. Block number 0 indicates the first block of a body provided. Block number 0 indicates the first block of a body
(i.e., starting with the first byte of the body). (i.e., starting with the first byte of the body).
M: More Flag ("not last block"). For descriptive usage, this flag, M: More Flag ("not last block"). For descriptive usage, this flag,
if unset, indicates that the payload in this message is the last 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 block in the body; when set, it indicates that there are one or
more additional blocks available. When a Block2 Option is used in more additional blocks available. When a Block2 Option is used in
a request to retrieve a specific block number ("control usage"), a request to retrieve a specific block number ("control usage"),
the M bit MUST be sent as zero and ignored on reception. (In a the M bit MUST be sent as zero and ignored on reception. (In a
Block1 Option in a response, the M flag is used to indicate Block1 Option in a response, the M flag is used to indicate
atomicity, see below.) atomicity, see below.)
SZX: Block Size. The block size is represented as three-bit SZX: Block Size. The block size is represented as a three-bit
unsigned integer indicating the size of a block to the power of unsigned integer indicating the size of a block to the power of
two. Thus block size = 2**(SZX + 4). The allowed values of SZX two. Thus, block size = 2**(SZX + 4). The allowed values of SZX
are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the
maximum is 2**(6+4) = 1024. The value 7 for SZX (which would maximum is 2**(6+4) = 1024. The value 7 for SZX (which would
indicate a block size of 2048) is reserved, i.e. MUST NOT be sent indicate a block size of 2048) is reserved, i.e., MUST NOT be sent
and MUST lead to a 4.00 Bad Request response code upon reception and MUST lead to a 4.00 Bad Request response code upon reception
in a request. in a request.
There is no default value for the Block1 and Block2 Options. Absence There is no default value for the Block1 and Block2 Options. Absence
of one of these options is equivalent to an option value of 0 with of one of these options is equivalent to an option value of 0 with
respect to the value of NUM and M that could be given in the option, respect to the value of NUM and M that could be given in the option,
i.e. it indicates that the current block is the first and only block i.e., it indicates that the current block is the first and only block
of the transfer (block number 0, M bit not set). However, in of the transfer (block number 0, M bit not set). However, in
contrast to the explicit value 0, which would indicate an SZX of 0 contrast to the explicit value 0, which would indicate an SZX of 0
and thus a size value of 16 bytes, there is no specific explicit size and thus a size value of 16 bytes, there is no specific explicit size
implied by the absence of the option -- the size is left unspecified. implied by the absence of the option -- the size is left unspecified.
(As for any uint, the explicit value 0 is efficiently indicated by a (As for any uint, the explicit value 0 is efficiently indicated by a
zero-length option; this, therefore, is different in semantics from zero-length option; this, therefore, is different in semantics from
the absence of the option.) the absence of the option.)
2.3. Block Options in Requests and Responses 2.3. Block Options in Requests and Responses
skipping to change at page 10, line 43 skipping to change at page 11, line 35
* The NUM field of the Block1 Option indicates what block number * The NUM field of the Block1 Option indicates what block number
is being acknowledged. is being acknowledged.
* If the M bit was set in the request, the server can choose * 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 act on each block separately, with no memory, or
whether to handle the request for the entire body atomically, whether to handle the request for the entire body atomically,
or any mix of the two. or any mix of the two.
+ If the M bit is also set in the response, it indicates that + If the M bit is also set in the response, it indicates that
this response does not carry the final response code to the this response does not carry the final response code to the
request, i.e. the server collects further blocks from the request, i.e., the server collects further blocks from the
same endpoint and plans to implement the request atomically same endpoint and plans to implement the request atomically
(e.g., acts only upon reception of the last block of (e.g., acts only upon reception of the last block of
payload). In this case, the response MUST NOT carry a payload). In this case, the response MUST NOT carry a
Block2 option. Block2 Option.
+ Conversely, if the M bit is unset even though it was set in + Conversely, if the M bit is unset even though it was set in
the request, it indicates the block-wise request was enacted the request, it indicates the block-wise request was enacted
now specifically for this block, and the response carries now specifically for this block, and the response carries
the final response to this request (and to any previous ones the final response to this request (and to any previous ones
with the M bit set in the response's Block1 Option in this with the M bit set in the response's Block1 Option in this
sequence of block-wise transfers); the client is still sequence of block-wise transfers); the client is still
expected to continue sending further blocks, the request expected to continue sending further blocks, the request
method for which may or may not also be enacted per-block. method for which may or may not also be enacted per-block.
(Note that the resource is now in a partially updated state; (Note that the resource is now in a partially updated state;
skipping to change at page 11, line 28 skipping to change at page 12, line 22
this block size or a smaller one in all further requests in the this block size or a smaller one in all further requests in the
transfer sequence, even if that means changing the block size transfer sequence, even if that means changing the block size
(and possibly scaling the block number accordingly) from now (and possibly scaling the block number accordingly) from now
on. on.
Using one or both Block options, a single REST operation can be split Using one or both Block options, a single REST operation can be split
into multiple CoAP message exchanges. As specified in [RFC7252], into multiple CoAP message exchanges. As specified in [RFC7252],
each of these message exchanges uses their own CoAP Message ID. each of these message exchanges uses their own CoAP Message ID.
The Content-Format Option sent with the requests or responses MUST The Content-Format Option sent with the requests or responses MUST
reflect the content-format of the entire body. If blocks of a reflect the Content-Format of the entire body. If blocks of a
response body arrive with different content-format options, it is up response body arrive with different Content-Format Options, it is up
to the client how to handle this error (it will typically abort any to the client how to handle this error (it will typically abort any
ongoing block-wise transfer). If blocks of a request arrive at a ongoing block-wise transfer). If blocks of a request arrive at a
server with mismatching content-format options, the server MUST NOT server with mismatching Content-Format Options, the server MUST NOT
assemble them into a single request; this usually leads to a 4.08 assemble them into a single request; this usually leads to a 4.08
(Request Entity Incomplete, Section 2.9.2) error response on the (Request Entity Incomplete, Section 2.9.2) error response on the
mismatching block. mismatching block.
2.4. Using the Block2 Option 2.4. Using the Block2 Option
When a request is answered with a response carrying a Block2 Option When a request is answered with a response carrying a Block2 Option
with the M bit set, the requester may retrieve additional blocks of with the M bit set, the requester may retrieve additional blocks of
the resource representation by sending further requests with the same the resource representation by sending further requests with the same
options as the initial request and a Block2 Option giving the block options as the initial request and a Block2 Option giving the block
skipping to change at page 12, line 14 skipping to change at page 13, line 8
size that was used by the server in the response for the first size that was used by the server in the response for the first
request that gave a desired size using a Block2 Option. request that gave a desired size using a Block2 Option.
Once the Block2 Option is used by the requester and a first response Once the Block2 Option is used by the requester and a first response
has been received with a possibly adjusted block size, all further has been received with a possibly adjusted block size, all further
requests in a single block-wise transfer will ultimately converge on requests in a single block-wise transfer will ultimately converge on
using the same size, except that there may not be enough content to using 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 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 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 after a first request without a Block2 Option resulted in a Block2
option in the response.) The server uses the block size indicated in Option in the response.) The server uses the block size indicated in
the request option or a smaller size, but the requester MUST take 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 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 initial request and proceed to use it in subsequent requests. The
server behavior MUST ensure that this client behavior results in 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 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 one with the M bit not set, and possibly the first one if the initial
request did not contain a Block2 Option). request did not contain a Block2 Option).
Block-wise transfers can be used to GET resources the representations Block-wise transfers can be used to GET resources whose
of which are entirely static (not changing over time at all, such as representations are entirely static (not changing over time at all,
in a schema describing a device), or for dynamically changing such as in a schema describing a device), or for dynamically changing
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 ([RFC7252], Section 5.10.6), to conjunction with the ETag Option ([RFC7252], Section 5.10.6), to
ensure that the blocks being reassembled are from the same version of ensure that the blocks being reassembled are from the same version of
the representation: The server SHOULD include an ETag option in each the representation: The server SHOULD include an ETag Option in each
response. If an ETag option is available, the client, when response. If an ETag Option is available, the client, when
reassembling the representation from the blocks being exchanged, MUST reassembling the representation from the blocks being exchanged, MUST
compare ETag Options. If the ETag Options do not match in a GET compare ETag Options. If the ETag Options do not match in a GET
transfer, the requester has the option of attempting to retrieve transfer, the requester has the option of attempting to retrieve
fresh values for the blocks it retrieved first. To minimize the fresh values for the blocks it retrieved first. To minimize the
resulting inefficiency, the server MAY cache the current value of a resulting inefficiency, the server MAY cache the current value of a
representation for an ongoing sequence of requests. (The server may representation for an ongoing sequence of requests. (The server may
identify the sequence by the combination of the requesting end-point identify the sequence by the combination of the requesting endpoint
and the URI being the same in each block-wise request.) Note well and the URI being the same in each block-wise request.) Note well
that this specification makes no requirement for the server to that this specification makes no requirement for the server to
establish any state; however, servers that offer quickly changing establish any state; however, servers that offer quickly changing
resources may thereby make it impossible for a client to ever resources may thereby make it impossible for a client to ever
retrieve a consistent set of blocks. Clients that want to retrieve retrieve a consistent set of blocks. Clients that want to retrieve
all blocks of a resource SHOULD strive to do so without undue delay. all blocks of a resource SHOULD strive to do so without undue delay.
Servers can fully expect to be free to discard any cached state after Servers can fully expect to be free to discard any cached state after
a period of EXCHANGE_LIFETIME ([RFC7252], Section 4.8.2) after the a period of EXCHANGE_LIFETIME ([RFC7252], Section 4.8.2) after the
last access to the state, however, there is no requirement to always last access to the state, however, there is no requirement to always
keep the state for as long. keep the state for as long.
The Block2 option provides no way for a single endpoint to perform The Block2 Option provides no way for a single endpoint to perform
multiple concurrently proceeding block-wise response payload transfer multiple concurrently proceeding block-wise response payload transfer
(e.g., GET) operations to the same resource. This is rarely a (e.g., GET) operations to the same resource. This is rarely a
requirement, but as a workaround, a client may vary the cache key requirement, but as a workaround, a client may vary the cache key
(e.g., by using one of several URIs accessing resources with the same (e.g., by using one of several URIs accessing resources with the same
semantics, or by varying a proxy-safe elective option). semantics, or by varying a proxy-safe elective option).
2.5. Using the Block1 Option 2.5. Using the Block1 Option
In a request with a request payload (e.g., PUT or POST), the Block1 In a request with a request payload (e.g., PUT or POST), the Block1
Option refers to the payload in the request (descriptive usage). Option refers to the payload in the request (descriptive usage).
skipping to change at page 13, line 25 skipping to change at page 14, line 22
block size preference of the server for this resource (control block size preference of the server for this resource (control
usage). Obviously, at this point the first block has already been usage). Obviously, at this point the first block has already been
transferred by the client without benefit of this knowledge. Still, transferred by the client without benefit of this knowledge. Still,
the client SHOULD heed the preference indicated and, for all further the client SHOULD heed the preference indicated and, for all further
blocks, use the block size preferred by the server or a smaller one. 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 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 starts with a block number larger than one, as the first
request already transferred multiple blocks as counted in the smaller request already transferred multiple blocks as counted in the smaller
size. size.
To counter the effects of adaptation layer fragmentation on packet To counter the effects of adaptation-layer fragmentation on packet-
delivery probability, a client may want to give up retransmitting a delivery probability, a client may want to give up retransmitting a
request with a relatively large payload even before MAX_RETRANSMIT request with a relatively large payload even before MAX_RETRANSMIT
has been reached, and try restating the request as a block-wise has been reached, and try restating the request as a block-wise
transfer with a smaller payload. Note that this new attempt is then transfer with a smaller payload. Note that this new attempt is then
a new message-layer transaction and requires a new Message ID. a new message-layer transaction and requires a new Message ID.
(Because of the uncertainty whether the request or the (Because of the uncertainty about whether the request or the
acknowledgement was lost, this strategy is useful mostly for acknowledgement was lost, this strategy is useful mostly for
idempotent requests.) idempotent requests.)
In a block-wise transfer of a request payload (e.g., a PUT or POST) In a block-wise transfer of a request payload (e.g., a PUT or POST)
that is intended to be implemented in an atomic fashion at the that is intended to be implemented in an atomic fashion at the
server, the actual creation/replacement takes place at the time the server, the actual creation/replacement takes place at the time the
final block, i.e. a block with the M bit unset in the Block1 Option, final block, i.e., a block with the M bit unset in the Block1 Option,
is received. In this case, all success responses to non-final blocks is received. In this case, all success responses to non-final blocks
carry the response code 2.31 (Continue, Section 2.9.1). If not all carry the response code 2.31 (Continue, Section 2.9.1). If not all
previous blocks are available at the server at the time of processing previous blocks are available at the server at the time of processing
the final block, the transfer fails and error code 4.08 (Request the final block, the transfer fails and error code 4.08 (Request
Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY
also return a 4.08 error code for any (final or non-final) Block1 also return a 4.08 error code for any (final or non-final) Block1
transfer that is not in sequence; clients that do not have specific transfer that is not in sequence; therefore, clients that do not have
mechanisms to handle this case therefore SHOULD always start with specific mechanisms to handle this case SHOULD always start with
block zero and send the following blocks in order. block zero and send the following blocks in order.
One reason that a client might encounter a 4.08 error code is that One reason that a client might encounter a 4.08 error code is that
the server has already timed out and discarded the partial request the server has already timed out and discarded the partial request
body being assembled. Clients SHOULD strive to send all blocks of a body being assembled. Clients SHOULD strive to send all blocks of a
request without undue delay. Servers can fully expect to be free to request without undue delay. Servers can fully expect to be free to
discard any partial request body when a period of EXCHANGE_LIFETIME discard any partial request body when a period of EXCHANGE_LIFETIME
([RFC7252], Section 4.8.2) has elapsed after the most recent block ([RFC7252], Section 4.8.2) has elapsed after the most recent block
was transferred; however, there is no requirement on a server to was transferred; however, there is no requirement on a server to
always keep the partial request body for as long. always keep the partial request body for as long.
The error code 4.13 (Request Entity Too Large) can be returned at any The error code 4.13 (Request Entity Too Large) can be returned at any
time by a server that does not currently have the resources to store time by a server that does not currently have the resources to store
blocks for a block-wise request payload transfer that it would intend blocks for a block-wise request payload transfer that it would intend
to implement in an atomic fashion. (Note that a 4.13 response to a to implement in an atomic fashion. (Note that a 4.13 response to a
request that does not employ Block1 is a hint for the client to try request that does not employ Block1 is a hint for the client to try
sending Block1, and a 4.13 response with a smaller SZX in its Block1 sending Block1, and a 4.13 response with a smaller SZX in its Block1
option than requested is a hint to try a smaller SZX.) Option than requested is a hint to try a smaller SZX.)
A block-wise transfer of a request payload that is implemented in a A block-wise transfer of a request payload that is implemented in a
stateless fashion at the server is likely to leave the resource being stateless fashion at the server is likely to leave the resource being
operated on in an inconsistent state during the time the transfer is operated on in an inconsistent state while the transfer is still
still ongoing or when the client does not complete the transfer. ongoing or when the client does not complete the transfer. This
This characteristic is closer to that of remote file systems than to characteristic is closer to that of remote file systems than to that
that of HTTP, where state is always kept on the server during a of HTTP, where state is always kept on the server during a transfer.
transfer. Techniques well known from shared file access (e.g., Techniques well known from shared file access (e.g., client-specific
client-specific temporary resources) can be used to mitigate this temporary resources) can be used to mitigate this difference from
difference from HTTP. HTTP.
The Block1 option provides no way for a single endpoint to perform The Block1 Option provides no way for a single endpoint to perform
multiple concurrently proceeding block-wise request payload transfer multiple concurrently proceeding block-wise request payload transfer
(e.g., PUT or POST) operations to the same resource. Starting a new (e.g., PUT or POST) operations to the same resource. Starting a new
block-wise sequence of requests to the same resource (before an old block-wise sequence of requests to the same resource (before an old
sequence from the same endpoint was finished) simply overwrites the sequence from the same endpoint was finished) simply overwrites the
context the server may still be keeping. (This is probably exactly context the server may still be keeping. (This is probably exactly
what one wants in this case -- the client may simply have restarted what one wants in this case -- the client may simply have restarted
and lost its knowledge of the previous sequence.) and lost its knowledge of the previous sequence.)
2.6. Combining Block-wise Transfers with the Observe Option 2.6. Combining Block-Wise Transfers with the Observe Option
The Observe Option provides a way for a client to be notified about The Observe option provides a way for a client to be notified about
changes over time of a resource [RFC7641]. Resources observed by changes over time of a resource [RFC7641]. Resources observed by
clients may be larger than can be comfortably processed or clients may be larger than can be comfortably processed or
transferred in one CoAP message. The following rules apply to the transferred in one CoAP message. The following rules apply to the
combination of block-wise transfers with notifications. combination of block-wise transfers with notifications.
Observation relationships always apply to an entire resource; the Observation relationships always apply to an entire resource; the
Block2 option does not provide a way to observe a single block of a Block2 Option does not provide a way to observe a single block of a
resource. resource.
As with basic GET transfers, the client can indicate its desired As with basic GET transfers, the client can indicate its desired
block size in a Block2 Option in the GET request establishing or block size in a Block2 Option in the GET request establishing or
renewing the observation relationship. If the server supports block- renewing the observation relationship. If the server supports block-
wise transfers, it SHOULD take note of the block size and apply it as wise transfers, it SHOULD take note of the block size and apply it as
a maximum size to all notifications/responses resulting from the GET a maximum size to all notifications/responses resulting from the GET
request (until the client is removed from the list of observers or 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 the entry in that list is updated by the server receiving a new GET
request for the resource from the client). request for the resource from the client).
When sending a 2.05 (Content) notification, the server only sends the When sending a 2.05 (Content) notification, the server only sends the
first block of the representation. The client retrieves the rest of first block of the representation. The client retrieves the rest of
the representation as if it had caused this first response by a GET the representation as if it had caused this first response by a GET
request, i.e., by using additional GET requests with Block2 options request, i.e., by using additional GET requests with Block2 Options
containing NUM values greater than zero. (This results in the containing NUM values greater than zero. (This results in the
transfer of the entire representation, even if only some of the transfer of the entire representation, even if only some of the
blocks have changed with respect to a previous notification.) blocks have changed with respect to a previous notification.)
As with other dynamically changing resources, to ensure that the As with other dynamically changing resources, to ensure that the
blocks being reassembled are from the same version of the blocks being reassembled are from the same version of the
representation, the server SHOULD include an ETag option in each representation, the server SHOULD include an ETag Option in each
response, and the reassembling client MUST compare the ETag options response, and the reassembling client MUST compare the ETag Options
(Section 2.4). Even more so than for the general case of Block2, (Section 2.4). Even more so than for the general case of Block2,
clients that want to retrieve all blocks of a resource they have been clients that want to retrieve all blocks of a resource they have been
notified about with a first block SHOULD strive to do so without notified about with a first block SHOULD strive to do so without
undue delay. undue delay.
See Section 3.4 for examples. See Section 3.4 for examples.
2.7. Combining Block1 and Block2 2.7. Combining Block1 and Block2
In PUT and particularly in POST exchanges, both the request body and In PUT and particularly in POST exchanges, both the request body and
the response body may be large enough to require the use of block- the response body may be large enough to require the use of block-
wise transfers. First, the Block1 transfer of the request body wise transfers. First, the Block1 transfer of the request body
proceeds as usual. In the exchange of the last slice of this block- proceeds as usual. In the exchange of the last slice of this block-
wise transfer, the response carries the first slice of the Block2 wise transfer, the response carries the first slice of the Block2
transfer (NUM is zero). To continue this Block2 transfer, the client transfer (NUM is zero). To continue this Block2 transfer, the client
continues to send requests similar to the requests in the Block1 continues to send requests similar to the requests in the Block1
phase, but leaves out the Block1 options and includes a Block2 phase, but leaves out the Block1 Options and includes a Block2
request option with non-zero NUM. request option with non-zero NUM.
Block2 transfers that retrieve the response body for a request that Block2 transfers that retrieve the response body for a request that
used Block1 MUST be performed in sequential order. used Block1 MUST be performed in sequential order.
2.8. Combining Block2 with Multicast 2.8. Combining Block2 with Multicast
A client can use the Block2 option in a multicast GET request with A client can use the Block2 Option in a multicast GET request with
NUM = 0 to aid in limiting the size of the response. NUM = 0 to aid in limiting the size of the response.
Similarly, a response to a multicast GET request can use a Block2 Similarly, a response to a multicast GET request can use a Block2
option with NUM = 0 if the representation is large, or to further Option with NUM = 0 if the representation is large, or to further
limit the size of the response. limit the size of the response.
In both cases, the client retrieves any further blocks using unicast In both cases, the client retrieves any further blocks using unicast
exchanges; in the unicast requests, the client SHOULD heed any block exchanges; in the unicast requests, the client SHOULD heed any block
size preferences indicated by the server in the response to the size preferences indicated by the server in the response to the
multicast request. multicast request.
Other uses of the Block options in conjunction with multicast Other uses of the Block options in conjunction with multicast
messages are for further study. messages are for further study.
2.9. Response Codes 2.9. Response Codes
Two response codes are defined by this specification beyond those Beyond the response codes defined in [RFC7252], this specification
already defined in [RFC7252], and another response code is extended defines two response codes and extends the meaning of one.
in its meaning.
2.9.1. 2.31 Continue 2.9.1. 2.31 Continue
This new success status code indicates that the transfer of this This new success status code indicates that the transfer of this
block of the request body was successful and that the server block of the request body was successful and that the server
encourages sending further blocks, but that a final outcome of the encourages sending further blocks, but that a final outcome of the
whole block-wise request cannot yet be determined. No payload is whole block-wise request cannot yet be determined. No payload is
returned with this response code. returned with this response code.
2.9.2. 4.08 Request Entity Incomplete 2.9.2. 4.08 Request Entity Incomplete
skipping to change at page 16, line 48 skipping to change at page 17, line 47
and a different Content-Format is indicated than expected from the and a different Content-Format is indicated than expected from the
current state of the resource. If it implements the transfer in a current state of the resource. If it implements the transfer in a
stateless fashion, it can match up the Content-Format of the block stateless fashion, it can match up the Content-Format of the block
against that of the existing resource. If it implements the transfer against that of the existing resource. If it implements the transfer
in an atomic fashion, it can match up the block against the partially in an atomic fashion, it can match up the block against the partially
reassembled piece of representation that is going to replace the reassembled piece of representation that is going to replace the
state of the resource.) state of the resource.)
2.9.3. 4.13 Request Entity Too Large 2.9.3. 4.13 Request Entity Too Large
In [RFC7252], Section 5.9.2.9, the response code 4.13 (Request Entity In Section 5.9.2.9 of [RFC7252], the response code 4.13 (Request
Too Large) is defined to be like HTTP 413 "Request Entity Too Large". Entity Too Large) is defined to be like HTTP 413 "Request Entity Too
[RFC7252] also recommends that this response SHOULD include a Size1 Large". [RFC7252] also recommends that this response SHOULD include
Option (Section 4) to indicate the maximum size of request entity the a Size1 Option (Section 4) to indicate the maximum size of request
server is able and willing to handle, unless the server is not in a entity the server is able and willing to handle, unless the server is
position to make this information available. not in a position to make this information available.
The present specification allows the server to return this response The present specification allows the server to return this response
code at any time during a Block1 transfer to indicate that it does code at any time during a Block1 transfer to indicate that it does
not currently have the resources to store blocks for a transfer that not currently have the resources to store blocks for a transfer that
it would intend to implement in an atomic fashion. It also allows it would intend to implement in an atomic fashion. It also allows
the server to return a 4.13 response to a request that does not the server to return a 4.13 response to a request that does not
employ Block1 as a hint for the client to try sending Block1. employ Block1 as a hint for the client to try sending Block1.
Finally, a 4.13 response to a request with a Block1 option (control Finally, a 4.13 response to a request with a Block1 Option (control
usage, see Section 2.3) where the response carries a smaller SZX in usage, see Section 2.3) where the response carries a smaller SZX in
its Block1 option is a hint to try that smaller SZX. its Block1 Option is a hint to try that smaller SZX.
2.10. Caching Considerations 2.10. Caching Considerations
This specification attempts to leave a variety of implementation This specification attempts to leave a variety of implementation
strategies open for caches, in particular those in caching proxies. strategies open for caches, in particular those in caching proxies.
E.g., a cache is free to cache blocks individually, but also could For example, a cache is free to cache blocks individually, but also
wait to obtain the complete representation before it serves parts of could wait to obtain the complete representation before it serves
it. Partial caching may be more efficient in a cross-proxy parts of it. Partial caching may be more efficient in a cross-proxy
(equivalent to a streaming HTTP proxy). A cached block (partial (equivalent to a streaming HTTP proxy). A cached block (partial
cached response) can be used in place of a complete response to cached response) can be used in place of a complete response to
satisfy a block-wise request that is presented to a cache. Note that satisfy a block-wise request that is presented to a cache. Note that
different blocks can have different Max-Age values, as they are different blocks can have different Max-Age values, as they are
transferred at different times. A response with a block updates the transferred at different times. A response with a block updates the
freshness of the complete representation. Individual blocks can be freshness of the complete representation. Individual blocks can be
validated, and validating a single block validates the complete validated, and validating a single block validates the complete
representation. A response with a Block1 Option in control usage representation. A response with a Block1 Option in control usage
with the M bit set invalidates cached responses for the target URI. with the M bit set invalidates cached responses for the target URI.
skipping to change at page 18, line 8 skipping to change at page 19, line 8
This section gives a number of short examples with message flows for This section gives a number of short examples with message flows for
a block-wise GET, and for a PUT or POST. These examples demonstrate a block-wise GET, and for a PUT or POST. These examples demonstrate
the basic operation, the operation in the presence of the basic operation, the operation in the presence of
retransmissions, and examples for the operation of the block size retransmissions, and examples for the operation of the block size
negotiation. negotiation.
In all these examples, a Block option is shown in a decomposed way In all these examples, a Block option is shown in a decomposed way
indicating the kind of Block option (1 or 2) followed by a colon, and indicating the kind of Block option (1 or 2) followed by a colon, and
then the block number (NUM), more bit (M), and block size exponent then the block number (NUM), more bit (M), and block size exponent
(2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 (2**(SZX+4)) separated by slashes. For example, a Block2 Option
would be shown as 2:2/0/32), or a Block1 Option value of 59 would be value of 33 would be shown as 2:2/0/32) and a Block1 Option value of
shown as 1:3/1/128. 59 would be shown as 1:3/1/128.
As in [RFC7252], "MID" is used as an abbreviation of "Message ID". As in [RFC7252], "MID" is used as an abbreviation for "Message ID".
3.1. Block2 Examples 3.1. Block2 Examples
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 a payload of 128 bytes client agrees. The first two ACKs contain a payload of 128 bytes
each, and the third ACK contains a payload between 1 and 128 bytes. each, and the third ACK contains a payload between 1 and 128 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
skipping to change at page 18, line 35 skipping to change at page 19, line 35
| <------ 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 |
Figure 2: Simple block-wise GET Figure 2: Simple Block-Wise GET
In the second example (Figure 3), the client anticipates the block- In the second example (Figure 3), the client anticipates the block-
wise transfer (e.g., because of a size indication in the link-format wise transfer (e.g., because of a size indication in the link-format
description [RFC6690]) and sends a block size proposal. All ACK description [RFC6690]) and sends a block size proposal. All ACK
messages except for the last carry 64 bytes of payload; the last one messages except for the last carry 64 bytes of payload; the last one
carries between 1 and 64 bytes. carries between 1 and 64 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], GET, /status, 2:0/0/64 ------> | | CON [MID=1234], GET, /status, 2:0/0/64 ------> |
skipping to change at page 19, line 25 skipping to change at page 20, line 31
: ... : : ... :
: : : :
| CON [MID=1238], GET, /status, 2:4/0/64 ------> | | CON [MID=1238], GET, /status, 2:4/0/64 ------> |
| | | |
| <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 | | <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 |
| | | |
| CON [MID=1239], GET, /status, 2:5/0/64 ------> | | CON [MID=1239], GET, /status, 2:5/0/64 ------> |
| | | |
| <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 | | <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 |
Figure 3: Block-wise GET with early negotiation Figure 3: Block-Wise GET with Early Negotiation
In the third example (Figure 4), the client is surprised by the need In the third example (Figure 4), the client is surprised by the need
for a block-wise transfer, and unhappy with the size chosen for a block-wise transfer, and unhappy with the size chosen
unilaterally by the server. As it did not send a size proposal unilaterally by the server. As it did not send a size proposal
initially, the negotiation only influences the size from the second initially, the negotiation only influences the size from the second
message exchange onward. Since the client already obtained both the message exchange onward. Since the client already obtained both the
first and second 64-byte block in the first 128-byte exchange, it 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 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 is (or needs to be) understood by the server, which simply responds
to the requests as it best can. to the requests as it best can.
skipping to change at page 20, line 27 skipping to change at page 21, line 37
| <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 | | <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 |
| | | |
| CON [MID=1237], GET, /status, 2:4/0/64 ------> | | CON [MID=1237], GET, /status, 2:4/0/64 ------> |
| | | |
| <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 | | <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 |
| | | |
| CON [MID=1238], GET, /status, 2:5/0/64 ------> | | CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| | | |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 4: Block-wise GET with late negotiation Figure 4: Block-Wise GET with Late Negotiation
In all these (and the following) cases, retransmissions are handled In all these (and the following) cases, retransmissions are handled
by the CoAP message exchange layer, so they don't influence the block by the CoAP message exchange layer, so they don't influence the block
operations (Figure 5, Figure 6). operations (Figures 5 and 6).
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], GE///////////////////////// | | CON [MID=1235], GE///////////////////////// |
| | | |
| (timeout) | | (timeout) |
skipping to change at page 21, line 25 skipping to change at page 22, line 25
| CON [MID=1235], GET, /status, 2:2/0/64 ------> | | CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| | | |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
: : : :
: ... : : ... :
: : : :
| CON [MID=1238], GET, /status, 2:5/0/64 ------> | | CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| | | |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 5: Block-wise GET with late negotiation and lost CON Figure 5: Block-Wise GET with Late Negotiation and Lost CON
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:2/0/64 ------> | | CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| | | |
| //////////////////////////////////tent, 2:2/1/64 | | //////////////////////////////////tent, 2:2/1/64 |
skipping to change at page 21, line 49 skipping to change at page 22, line 49
| CON [MID=1235], GET, /status, 2:2/0/64 ------> | | CON [MID=1235], GET, /status, 2:2/0/64 ------> |
| | | |
| <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 |
: : : :
: ... : : ... :
: : : :
| CON [MID=1238], GET, /status, 2:5/0/64 ------> | | CON [MID=1238], GET, /status, 2:5/0/64 ------> |
| | | |
| <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 |
Figure 6: Block-wise GET with late negotiation and lost ACK Figure 6: Block-Wise GET with Late Negotiation and Lost ACK
3.2. Block1 Examples 3.2. Block1 Examples
The following examples demonstrate a PUT exchange; a POST exchange The following examples demonstrate a PUT exchange; a POST exchange
looks the same, with different requirements on atomicity/idempotence. looks the same, with different requirements on atomicity/idempotence.
Note that, similar to GET, the responses to the requests that have a Note that, similar to GET, the responses to the requests that have a
more bit in the request Block1 Option are provisional and carry the more bit in the request Block1 Option are provisional and carry the
response code 2.31 (Continue); only the final response tells the response code 2.31 (Continue); only the final response tells the
client that the PUT did succeed. client that the PUT succeeded.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> | | CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| | | |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| | | |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> | | CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| | | |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> | | CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| | | |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |
Figure 7: Simple atomic block-wise PUT Figure 7: Simple Atomic Block-Wise PUT
A stateless server that simply builds/updates the resource in place A stateless server that simply builds/updates the resource in place
(statelessly) may indicate this by not setting the more bit in the (statelessly) may indicate this by not setting the more bit in the
response (Figure 8); in this case, the response codes are valid response (Figure 8); in this case, the response codes are valid
separately for each block being updated. This is of course only an separately for each block being updated. This is of course only an
acceptable behavior of the server if the potential inconsistency acceptable behavior of the server if the potential inconsistency
present during the run of the message exchange sequence does not lead present during the run of the message exchange sequence does not lead
to problems, e.g. because the resource being created or changed is to problems, e.g., because the resource being created or changed is
not yet or not currently in use. not yet or not currently in use.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> | | CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| | | |
| <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 | | <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 |
| | | |
| CON [MID=1235], PUT, /options, 1:1/1/128 ------> | | CON [MID=1235], PUT, /options, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 | | <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 |
| | | |
| CON [MID=1236], PUT, /options, 1:2/0/128 ------> | | CON [MID=1236], PUT, /options, 1:2/0/128 ------> |
| | | |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |
Figure 8: Simple stateless block-wise PUT Figure 8: Simple Stateless Block-Wise PUT
Finally, a server receiving a block-wise PUT or POST may want to Finally, a server receiving a block-wise PUT or POST may want to
indicate a smaller block size preference (Figure 9). In this case, indicate a smaller block size preference (Figure 9). In this case,
the client SHOULD continue with a smaller block size; if it does, it 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. MUST adjust the block number to properly count in that smaller size.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], PUT, /options, 1:0/1/128 ------> | | CON [MID=1234], PUT, /options, 1:0/1/128 ------> |
| | | |
skipping to change at page 23, line 44 skipping to change at page 24, line 44
| <------ ACK [MID=1235], 2.31 Continue, 1:4/1/32 | | <------ ACK [MID=1235], 2.31 Continue, 1:4/1/32 |
| | | |
| CON [MID=1236], PUT, /options, 1:5/1/32 ------> | | CON [MID=1236], PUT, /options, 1:5/1/32 ------> |
| | | |
| <------ ACK [MID=1235], 2.31 Continue, 1:5/1/32 | | <------ ACK [MID=1235], 2.31 Continue, 1:5/1/32 |
| | | |
| CON [MID=1237], PUT, /options, 1:6/0/32 ------> | | CON [MID=1237], PUT, /options, 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 block-wise PUT with negotiation Figure 9: Simple Atomic Block-Wise PUT with Negotiation
3.3. Combining Block1 and Block2 3.3. Combining Block1 and Block2
Block options may be used in both directions of a single exchange. Block options may be used in both directions of a single exchange.
The following example demonstrates a block-wise POST request, The following example demonstrates a block-wise POST request,
resulting in a separate block-wise response. resulting in a separate block-wise response.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> | | CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
skipping to change at page 24, line 21 skipping to change at page 25, line 27
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> | | CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| | | |
| CON [MID=1236], POST, /soap, 1:2/0/128 ------> | | CON [MID=1236], POST, /soap, 1:2/0/128 ------> |
| | | |
| <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 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 ------> | | CON [MID=1237], POST, /soap, 2:1/0/128 ------> |
| (no payload for requests with Block2 with NUM != 0) | | (no payload for requests with Block2 with NUM != 0) |
| (could also do late negotiation by requesting e.g. 2:2/0/64) | | (could also do late negotiation by requesting, |
| e.g., 2:2/0/64) |
| | | |
| <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 | | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 |
| | | |
| CON [MID=1238], POST, /soap, 2:2/0/128 ------> | | CON [MID=1238], POST, /soap, 2:2/0/128 ------> |
| | | |
| <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 | | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 |
| | | |
| CON [MID=1239], POST, /soap, 2:3/0/128 ------> | | CON [MID=1239], POST, /soap, 2:3/0/128 ------> |
| | | |
| <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 | | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 |
Figure 10: Atomic block-wise POST with block-wise response Figure 10: Atomic Block-Wise POST with Block-Wise Response
This model does provide for early negotiation input to the Block2 This model does provide for early negotiation input to the Block2
block-wise transfer, as shown below. block-wise transfer, as shown below.
CLIENT SERVER CLIENT SERVER
| | | |
| CON [MID=1234], POST, /soap, 1:0/1/128 ------> | | CON [MID=1234], POST, /soap, 1:0/1/128 ------> |
| | | |
| <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 |
| | | |
| CON [MID=1235], POST, /soap, 1:1/1/128 ------> | | CON [MID=1235], POST, /soap, 1:1/1/128 ------> |
| | | |
| <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 |
| | | |
| CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> | | CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> |
| | | |
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 | | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 |
| | | |
| CON [MID=1237], POST, /soap, 2:1/0/64 ------> | | CON [MID=1237], POST, /soap, 2:1/0/64 ------> |
| (no payload for requests with Block2 with NUM != 0) | | (no payload for requests with Block2 with NUM != 0) |
| | | |
| <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 | | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 |
| | | |
| CON [MID=1238], POST, /soap, 2:2/0/64 ------> | | CON [MID=1238], POST, /soap, 2:2/0/64 ------> |
| | | |
| <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 | | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 |
| | | |
| CON [MID=1239], POST, /soap, 2:3/0/64 ------> | | CON [MID=1239], POST, /soap, 2:3/0/64 ------> |
| | | |
| <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 | | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 |
Figure 11: Atomic block-wise POST with block-wise response, early Figure 11: Atomic Block-Wise POST with Block-Wise Response,
negotiation Early Negotiation
3.4. Combining Observe and Block2 3.4. Combining Observe and Block2
In the following example, the server first sends a direct response In the following example, the server first sends a direct response
(Observe sequence number 62350) to the initial GET request (the (Observe sequence number 62350) to the initial GET request (the
resulting block-wise transfer is as in Figure 4 and has therefore resulting block-wise transfer is as in Figure 4 and has therefore
been left out). The second transfer is started by a 2.05 been left out). The second transfer is started by a 2.05
notification that contains just the first block (Observe sequence notification that contains just the first block (Observe sequence
number 62354); the client then goes on to obtain the rest of the number 62354); the client then goes on to obtain the rest of the
blocks. blocks.
skipping to change at page 26, line 12 skipping to change at page 27, line 21
| | | |
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/128 | | Block2: 0/1/128
| | Observe: 62350 | | Observe: 62350
| | ETag: 6f00f38e | | ETag: 6f00f38e
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
| | (Usual GET transfer left out) | | (Usual GET transfer left out)
... ...
| | (Notification of first block:) | | (Notification of first block)
| | | |
|<-----+ Header: 2.05 0x4145af9c |<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/128 | | Block2: 0/1/128
| | Observe: 62354 | | Observe: 62354
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
+- - ->| Header: 0x6000af9c +- - ->| Header: 0x6000af9c
| | | |
skipping to change at page 26, line 47 skipping to change at page 28, line 10
| GET | Token: 0xfc | GET | Token: 0xfc
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Block2: 2/0/128 | | Block2: 2/0/128
| | | |
|<-----+ Header: 2.05 0x61451638 |<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc | 2.05 | Token: 0xfc
| | Block2: 2/0/128 | | Block2: 2/0/128
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [53 bytes] | | Payload: [53 bytes]
Figure 12: Observe sequence with block-wise response Figure 12: Observe Sequence with Block-Wise Response
(Note that the choice of token 0xfc in this examples is arbitrary; (Note that the choice of token 0xfc in this example is arbitrary;
tokens are just shown in this example to illustrate that the requests tokens are just shown in this example to illustrate that the requests
for additional blocks cannot make use of the token of the Observation for additional blocks cannot make use of the token of the Observation
relationship. As a general comment on tokens, there is no other relationship. As a general comment on tokens, there is no other
mention of tokens in this document, as block-wise transfers handle mention of tokens in this document, as block-wise transfers handle
tokens like any other CoAP exchange. As usual the client is free to tokens like any other CoAP exchange. As usual, the client is free to
choose tokens for each exchange as it likes.) choose tokens for each exchange as it likes.)
In the following example, the client also uses early negotiation to In the following example, the client also uses early negotiation to
limit the block size to 64 bytes. limit the block size to 64 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
+----->| Header: GET 0x41011636 +----->| Header: GET 0x41011636
| GET | Token: 0xfb | GET | Token: 0xfb
| | Uri-Path: status-icon | | Uri-Path: status-icon
skipping to change at page 27, line 31 skipping to change at page 28, line 41
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/64 | | Block2: 0/1/64
| | Observe: 62350 | | Observe: 62350
| | ETag: 6f00f38e | | ETag: 6f00f38e
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [64 bytes] | | Payload: [64 bytes]
| | | |
| | (Usual GET transfer left out) | | (Usual GET transfer left out)
... ...
| | (Notification of first block:) | | (Notification of first block)
| | | |
|<-----+ Header: 2.05 0x4145af9c |<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/64 | | Block2: 0/1/64
| | Observe: 62354 | | Observe: 62354
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [64 bytes] | | Payload: [64 bytes]
| | | |
+- - ->| Header: 0x6000af9c +- - ->| Header: 0x6000af9c
| | | |
skipping to change at page 28, line 19 skipping to change at page 29, line 31
| GET | Token: 0xfc | GET | Token: 0xfc
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Block2: 4/0/64 | | Block2: 4/0/64
| | | |
|<-----+ Header: 2.05 0x61451638 |<-----+ Header: 2.05 0x61451638
| 2.05 | Token: 0xfc | 2.05 | Token: 0xfc
| | Block2: 4/0/64 | | Block2: 4/0/64
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [53 bytes] | | Payload: [53 bytes]
Figure 13: Observe sequence with early negotiation Figure 13: Observe Sequence with Early Negotiation
4. The Size2 and Size1 Options 4. The Size2 and Size1 Options
In many cases when transferring a large resource representation block In many cases when transferring a large resource representation block
by block, it is advantageous to know the total size early in the by block, it is advantageous to know the total size early in the
process. Some indication may be available from the maximum size process. Some indication may be available from the maximum size
estimate attribute "sz" provided in a resource description [RFC6690]. estimate attribute "sz" provided in a resource description [RFC6690].
However, the size may vary dynamically, so a more up-to-date However, the size may vary dynamically, so a more up-to-date
indication may be useful. indication may be useful.
This specification defines two CoAP Options, Size1 for indicating the This specification defines two CoAP options, Size1 for indicating the
size of the representation transferred in requests, and Size2 for size of the representation transferred in requests, and Size2 for
indicating the size of the representation transferred in responses. indicating the size of the representation transferred in responses.
(Size1 has already been defined in Section 5.10.9 of [RFC7252] to (Size1 has already been defined in Section 5.10.9 of [RFC7252] to
provide "size information about the resource representation in a provide "size information about the resource representation in a
request", however that section only details the narrow case of request"; however, that section only details the narrow case of
indicating in 4.13 responses the maximum size of request payload that indicating in 4.13 responses the maximum size of request payload that
the server is able and willing to handle. The present specification the server is able and willing to handle. The present specification
provides details about its use as a request option as well.) provides details about its use as a request option as well.)
The Size2 Option may be used for two purposes: The Size2 Option may be used for two purposes:
o in a request, to ask the server to provide a size estimate along o In a request, to ask the server to provide a size estimate along
with the usual response ("size request"). For this usage, the with the usual response ("size request"). For this usage, the
value MUST be set to 0. value MUST be set to 0.
o in a response carrying a Block2 Option, to indicate the current o In a response carrying a Block2 Option, to indicate the current
estimate the server has of the total size of the resource estimate the server has of the total size of the resource
representation, measured in bytes ("size indication"). representation, measured in bytes ("size indication").
Similarly, the Size1 Option may be used for two purposes: Similarly, the Size1 Option may be used for two purposes:
o in a request carrying a Block1 Option, to indicate the current o In a request carrying a Block1 Option, to indicate the current
estimate the client has of the total size of the resource estimate the client has of the total size of the resource
representation, measured in bytes ("size indication"). representation, measured in bytes ("size indication").
o in a 4.13 response, to indicate the maximum size that would have o In a 4.13 response, to indicate the maximum size that would have
been acceptable [RFC7252], measured in bytes. been acceptable [RFC7252], measured in bytes.
Apart from conveying/asking for size information, the Size options Apart from conveying/asking for size information, the Size options
have no other effect on the processing of the request or response. 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 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 resulting response, it should add a Block2 Option to the request with
a small block size (e.g., setting SZX=0). a small block size (e.g., setting SZX=0).
The Size Options are "elective", i.e., a client MUST be prepared for The Size options are "elective", i.e., a client MUST be prepared for
the server to ignore the size estimate request. The Size Options the server to ignore the size estimate request. Either Size option
MUST NOT occur more than once. MUST NOT occur more than once in a single message.
+-----+---+---+---+---+-------+--------+--------+---------+ +-----+---+---+---+---+-------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+-------+--------+--------+---------+ +-----+---+---+---+---+-------+--------+--------+---------+
| 60 | | | x | | Size1 | uint | 0-4 | (none) | | 60 | | | x | | Size1 | uint | 0-4 | (none) |
| | | | | | | | | | | | | | | | | | | |
| 28 | | | x | | Size2 | uint | 0-4 | (none) | | 28 | | | x | | Size2 | uint | 0-4 | (none) |
+-----+---+---+---+---+-------+--------+--------+---------+ +-----+---+---+---+---+-------+--------+--------+---------+
Table 2: Size Option Numbers Table 2: Size Option Numbers
skipping to change at page 29, line 42 skipping to change at page 31, line 6
Implementation Notes: Implementation Notes:
o As a quality of implementation consideration, block-wise transfers o As a quality of implementation consideration, block-wise transfers
for which the total size considerably exceeds the size of one for which the total size considerably exceeds the size of one
block are expected to include size indications, whenever those can block are expected to include size indications, whenever those can
be provided without undue effort (preferably with the first block be provided without undue effort (preferably with the first block
exchanged). If the size estimate does not change, the indication exchanged). If the size estimate does not change, the indication
does not need to be repeated for every block. does not need to be repeated for every block.
o The end of a block-wise transfer is governed by the M bits in the o The end of a block-wise transfer is governed by the M bits in the
Block Options, _not_ by exhausting the size estimates exchanged. Block options, _not_ by exhausting the size estimates exchanged.
o As usual for an option of type uint, the value 0 is best expressed 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 for as an empty option (0 bytes). There is no default value for
either Size Option. either Size option.
o The Size Options are neither critical nor unsafe, and are marked o The Size options are neither critical nor unsafe, and are marked
as No-Cache-Key. as No-Cache-Key.
5. HTTP Mapping Considerations 5. HTTP-Mapping Considerations
In this subsection, we give some brief examples for the influence the In this subsection, we give some brief examples of the influence that
Block options might have on intermediaries that map between CoAP and the Block options might have on intermediaries that map between CoAP
HTTP. and 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 sequence of block-wise transfers into a single HTTP transfer. the sequence of block-wise transfers into a single HTTP transfer.
E.g., for a GET request, the intermediary could perform the HTTP For example, for a GET request, the intermediary could perform the
request once the first block has been requested and could then HTTP request once the first block has been requested and could then
fulfill all further block requests out of its cache. A constrained fulfill all further block requests out of its cache. A constrained
implementation may not be able to cache the entire object and may use implementation may not be able to cache the entire object and may use
a combination of TCP flow control and (in particular if timeouts a combination of TCP flow control and (in particular if timeouts
occur) HTTP range requests to obtain the information necessary for occur) HTTP range requests to obtain the information necessary for
the next block transfer at the right time. the next block transfer at the right time.
For PUT or POST requests, historically there was more variation in For PUT or POST requests, historically there was more variation in
how HTTP servers might implement ranges; recently, [RFC7233] has how HTTP servers might implement ranges; recently, [RFC7233] has
defined that Range header fields received with a request method other defined that Range header fields received with a request method other
than GET are not to be interpreted. So, in general, the CoAP-to-HTTP than GET are not to be interpreted. So, in general, the CoAP-to-HTTP
skipping to change at page 30, line 42 skipping to change at page 31, line 52
server became impatient with the resulting transfer can then be server became impatient with the resulting transfer can then be
mapped into a CoAP 4.08 response code (similarly, 413 maps to 4.13). 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 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 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 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 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). 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 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 cache and/or mapped to GET requests that request a sequence of blocks
overlapping the range. that cover 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 an 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.)
6. IANA Considerations 6. IANA Considerations
This draft adds the following option numbers to the CoAP Option This document adds the following option numbers to the "CoAP Option
Numbers registry of [RFC7252]: Numbers" registry defined by [RFC7252]:
+--------+--------+-----------+ +--------+--------+-----------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+--------+-----------+ +--------+--------+-----------+
| 23 | Block2 | [RFCXXXX] | | 23 | Block2 | RFC 7959 |
| | | | | | | |
| 27 | Block1 | [RFCXXXX] | | 27 | Block1 | RFC 7959 |
| | | | | | | |
| 28 | Size2 | [RFCXXXX] | | 28 | Size2 | RFC 7959 |
+--------+--------+-----------+ +--------+--------+-----------+
Table 3: CoAP Option Numbers Table 3: CoAP Option Numbers
This draft adds the following response code to the CoAP Response This document adds the following response codes to the "CoAP Response
Codes registry of [RFC7252]: Codes" registry defined by [RFC7252]:
+------+---------------------------+-----------+ +------+---------------------------+-----------+
| Code | Description | Reference | | Code | Description | Reference |
+------+---------------------------+-----------+ +------+---------------------------+-----------+
| 2.31 | Continue | [RFCXXXX] | | 2.31 | Continue | RFC 7959 |
| | | | | | | |
| 4.08 | Request Entity Incomplete | [RFCXXXX] | | 4.08 | Request Entity Incomplete | RFC 7959 |
+------+---------------------------+-----------+ +------+---------------------------+-----------+
Table 4: CoAP Response Codes Table 4: CoAP Response Codes
7. Security Considerations 7. Security Considerations
Providing access to blocks within a resource may lead to surprising Providing access to blocks within a resource may lead to surprising
vulnerabilities. Where requests are not implemented atomically, an vulnerabilities. Where requests are not implemented atomically, an
attacker may be able to exploit a race condition or confuse a server attacker may be able to exploit a race condition or confuse a server
by inducing it to use a partially updated resource representation. by inducing it to use a partially updated resource representation.
Partial transfers may also make certain problematic data invisible to Partial transfers may also make certain problematic data invisible to
intrusion detection systems; it is RECOMMENDED that an intrusion Intrusion Detection Systems (IDSs); it is RECOMMENDED that an IDS
detection system (IDS) that analyzes resource representations that analyzes resource representations transferred by CoAP implement
transferred by CoAP implement the Block options to gain access to the Block options to gain access to entire resource representations.
entire resource representations. Still, approaches such as Still, approaches such as transferring even-numbered blocks on one
transferring even-numbered blocks on one path and odd-numbered blocks path and odd-numbered blocks on another path, or even transferring
on another path, or even transferring blocks multiple times with blocks multiple times with different content and obtaining a
different content and obtaining a different interpretation of different interpretation of temporal order at the IDS than at the
temporal order at the IDS than at the server, may prevent an IDS from server, may prevent an IDS from seeing the whole picture. These
seeing the whole picture. These kinds of attacks are well understood kinds of attacks are well understood from IP fragmentation and TCP
from IP fragmentation and TCP segmentation; CoAP does not add segmentation; CoAP does not add fundamentally new considerations.
fundamentally new considerations.
Where access to a resource is only granted to clients making use of Where access to a resource is only granted to clients making use of
specific security associations, all blocks of that resource MUST be specific security associations, 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. Future end-to- the creation of unusable resources can be tolerated. Future end-to-
end security mechanisms that may be added to CoAP itself may have end security mechanisms that may be added to CoAP itself may have
related security considerations, this includes considerations about related security considerations, this includes considerations about
caching of blocks in clients and in proxies (see Section 2.10 and caching of blocks in clients and in proxies (see Sections 2.10 and 5
Section 5 for different strategies in performing this caching); these for different strategies in performing this caching); these security
security considerations will need to be described in the considerations will need to be described in the specifications of
specifications of those mechanisms. those mechanisms.
A stateless server might be susceptible to an attack where the A stateless server might be susceptible to an attack where the
adversary sends a Block1 (e.g., PUT) block with a high block number: adversary sends a Block1 (e.g., PUT) block with a high block number:
A naive implementation might exhaust its resources by creating a huge A naive implementation might exhaust its resources by creating a huge
resource representation. resource representation.
Misleading size indications may be used by an attacker to induce Misleading size indications may be used by an attacker to induce
buffer overflows in poor implementations, for which the usual buffer overflows in poor implementations, for which the usual
considerations apply. considerations apply.
7.1. Mitigating Resource Exhaustion Attacks 7.1. Mitigating Resource Exhaustion Attacks
Certain block-wise requests may induce the server to create state, Certain block-wise requests may induce the server to create state,
e.g. to create a snapshot for the block-wise GET of a fast-changing e.g., to create a snapshot for the block-wise 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
untrusted sources. But even if this is done, the mitigation may untrusted sources. But even if this is done, the mitigation may
cause a denial-of-service to a legitimate request when it is drowned cause a denial-of-service to a legitimate request when it is drowned
out by other state-creating requests. Wherever possible, servers out by other state-creating requests. Wherever possible, servers
should therefore minimize the opportunities to create state for should therefore minimize the opportunities to create state for
untrusted sources, e.g. by using stateless approaches. untrusted sources, e.g., by using stateless approaches.
Performing segmentation at the application layer is almost always Performing segmentation at the application layer is almost always
better in this respect than at the transport layer or lower (IP better in this respect than at the transport layer or lower (IP
fragmentation, adaptation layer fragmentation), for instance because fragmentation, adaptation-layer fragmentation), for instance, because
there is application layer semantics that can be used for mitigation there are application-layer semantics that can be used for mitigation
or because lower layers provide security associations that can or because lower layers provide security associations that can
prevent attacks. However, it is less common to apply timeouts and prevent attacks. However, it is less common to apply timeouts and
keepalive mechanisms at the application layer than at lower layers. keepalive mechanisms at the application layer than at lower layers.
Servers MAY want to clean up accumulated state by timing it out (cf. Servers MAY want to clean up accumulated state by timing it out (cf.
response code 4.08), and clients SHOULD be prepared to run block-wise response code 4.08), and clients SHOULD be prepared to run block-wise
transfers in an expedient way to minimize the likelihood of running transfers in an expedient way to minimize the likelihood of running
into such a timeout. into such a timeout.
7.2. Mitigating Amplification Attacks 7.2. Mitigating Amplification Attacks
[RFC7252] discusses the susceptibility of CoAP end-points for use in [RFC7252] discusses the susceptibility of CoAP endpoints for use in
amplification attacks. 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.
8. References 8. References
8.1. Normative References 8.1. Normative References
[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, Requirement Levels", BCP 14, RFC 2119,
skipping to change at page 34, line 43 skipping to change at page 36, line 7
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>. <http://www.rfc-editor.org/info/rfc7230>.
[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
"Hypertext Transfer Protocol (HTTP/1.1): Range Requests", "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
RFC 7233, DOI 10.17487/RFC7233, June 2014, RFC 7233, DOI 10.17487/RFC7233, June 2014,
<http://www.rfc-editor.org/info/rfc7233>. <http://www.rfc-editor.org/info/rfc7233>.
Acknowledgements Acknowledgements
Much of the content of this draft is the result of discussions with Much of the content of this document is the result of discussions
the [RFC7252] authors, and via many CoRE WG discussions. with the [RFC7252] authors, and via many CoRE WG discussions.
Charles Palmer provided extensive editorial comments to a previous Charles Palmer provided extensive editorial comments to a previous
version of this draft, some of which the authors hope to have covered draft version of this document, some of which have been covered in
in this version. Esko Dijk reviewed a more recent version, leading this document. Esko Dijk reviewed a more recent version, leading to
to a number of further editorial improvements, a solution to the 4.13 a number of further editorial improvements, a solution to the 4.13
ambiguity problem, and the section about combining Block and ambiguity problem, and the section about combining Block and
multicast. Markus Becker proposed getting rid of an ill-conceived multicast (Section 2.8). Markus Becker proposed getting rid of an
default value for the Block2 and Block1 options. Peter Bigot ill-conceived default value for the Block2 and Block1 Options. Peter
insisted on a more systematic coverage of the options and response Bigot insisted on a more systematic coverage of the options and
code. Qin Wu provided a review for the IETF Operational directorate, response code. Qin Wu provided a review for the IETF Operations
and Goeran Selander commented on the security considerations. directorate, and Goeran Selander commented on the security
considerations.
Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of
the Size Option, which has informed this draft. Klaus Hartke wrote the Size option, which is described in this document. Klaus Hartke
some of the text describing the interaction of Block2 with Observe. wrote some of the text describing the interaction of Block2 with
Matthias Kovatsch provided a number of significant simplifications of Observe. Matthias Kovatsch provided a number of significant
the protocol. simplifications of the protocol.
The IESG reviewers provided very useful comments. Spencer Dawkins The IESG reviewers provided very useful comments. Spencer Dawkins
even suggested new text. Mirja Kuehlewind and he insisted on being even suggested new text. He and Mirja Kuehlewind insisted on more
more explicit about the layering of block-wise transfers on top of explicit information about the layering of block-wise transfers on
the base protocol. Ben Campbell helped untangling some MUST/SHOULD top of the base protocol. Ben Campbell helped untangle some MUST/
soup. Comments by Alexey Melnikov, as well as the gen-art review by SHOULD soup. Comments by Alexey Melnikov, as well as the Gen-ART
Jouni Korhonen and the ops-dir review by Qin Wu, caused further review by Jouni Korhonen, resulted in further improvements to the
improvements to the text. text.
Authors' Addresses Authors' Addresses
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org Email: cabo@tzi.org
Zach Shelby (editor) Zach Shelby (editor)
ARM ARM
150 Rose Orchard 150 Rose Orchard
San Jose, CA 95134 San Jose, CA 95134
USA United States of America
Phone: +1-408-203-9434 Phone: +1-408-203-9434
Email: zach.shelby@arm.com Email: zach.shelby@arm.com
 End of changes. 131 change blocks. 
289 lines changed or deleted 280 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/