draft-ietf-core-block-14.txt   draft-ietf-core-block-15.txt 
CoRE Working Group C. Bormann CoRE Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track Z. Shelby, Ed. Intended status: Standards Track Z. Shelby, Ed.
Expires: April 24, 2014 Sensinode Expires: January 5, 2015 ARM
October 21, 2013 July 04, 2014
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-14 draft-ietf-core-block-15
Abstract Abstract
CoAP is a RESTful transfer protocol for constrained nodes and CoAP is a RESTful transfer protocol for constrained nodes and
networks. Basic CoAP messages work well for the small payloads we networks. Basic CoAP messages work well for the small payloads we
expect from temperature sensors, light switches, and similar expect from temperature sensors, light switches, and similar
building-automation devices. Occasionally, however, applications building-automation devices. Occasionally, however, applications
will need to transfer larger payloads -- for instance, for will need to transfer larger payloads -- for instance, for firmware
firmware updates. With HTTP, TCP does the grunt work of slicing updates. With HTTP, TCP does the grunt work of slicing large
large payloads up into multiple packets and ensuring that they all payloads up into multiple packets and ensuring that they all arrive
arrive and are handled in the right order. and are handled in the right order.
CoAP is based on datagram transports such as UDP or DTLS, which CoAP is based on datagram transports such as UDP or DTLS, which
limits the maximum size of resource representations that can be limits the maximum size of resource representations that can be
transferred without too much fragmentation. Although UDP supports transferred without too much fragmentation. Although UDP supports
larger payloads through IP fragmentation, it is limited to 64 KiB larger payloads through IP fragmentation, it is limited to 64 KiB
and, more importantly, doesn't really work well for constrained and, more importantly, doesn't really work well for constrained
applications and networks. applications and networks.
Instead of relying on IP fragmentation, this specification extends Instead of relying on IP fragmentation, this specification extends
basic CoAP with a pair of "Block" options, for transferring multiple basic CoAP with a pair of "Block" options, for transferring multiple
skipping to change at page 2, line 10 skipping to change at page 2, line 10
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 24, 2014. This Internet-Draft will expire on January 5, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
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 . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 5
2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5 2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6
2.3. Block Options in Requests and Responses . . . . . . . . . 8 2.3. Block Options in Requests and Responses . . . . . . . . . 8
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11
2.6. Combining Blockwise Transfers with the Observe Option . . 12 2.6. Combining Blockwise Transfers with the Observe Option . . 12
2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13
2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13
2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14
2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14
2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14
2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 19
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 21 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 22
4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 24 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 25
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 25 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 26
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
7. Security Considerations . . . . . . . . . . . . . . . . . . . 28 7. Security Considerations . . . . . . . . . . . . . . . . . . . 28
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 28 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 29
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.1. Normative References . . . . . . . . . . . . . . . . . . 30 9.1. Normative References . . . . . . . . . . . . . . . . . . 30
9.2. Informative References . . . . . . . . . . . . . . . . . 30 9.2. Informative References . . . . . . . . . . . . . . . . . 30
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
The CoRE WG is tasked with standardizing an Application Protocol for The work on Constrained RESTful Environments (CoRE) aims at realizing
Constrained Networks/Nodes, CoAP. This protocol is intended to the REST architecture in a suitable form for the most constrained
provide RESTful [REST] services not unlike HTTP [RFC2616], while nodes (such as microcontrollers with limited RAM and ROM [RFC7228])
reducing the complexity of implementation as well as the size of and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP
packets exchanged in order to make these services useful in a highly protocol is intended to provide RESTful [REST] services not unlike
constrained network of themselves highly constrained nodes. HTTP [RFC7230], while reducing the complexity of implementation as
well as the size of packets exchanged in order to make these services
useful in a highly constrained network of themselves highly
constrained nodes.
This objective requires restraint in a number of sometimes 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 (in turn to maximize the
probability of delivery of the message), the amount of probability of delivery of the message), the amount of
transmission power needed and the loading of the limited-bandwidth transmission power needed and the loading of the limited-bandwidth
skipping to change at page 3, line 41 skipping to change at page 3, line 44
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 CoAP is based on datagram transports such as UDP, which limit the
maximum size of resource representations that can be transferred maximum size of resource representations that can be transferred
without creating unreasonable levels of IP fragmentation. In without creating unreasonable levels of IP fragmentation. In
addition, not all resource representations will fit into a single addition, not all resource representations will fit into a single
link layer packet of a constrained network, which may cause link layer packet of a constrained network, which may cause
adaptation layer fragmentation even if IP layer fragmentation is not adaptation layer fragmentation even if IP layer fragmentation is not
required. Using fragmentation (either at the adaptation layer or at required. Using fragmentation (either at the adaptation layer or at
the IP layer) to enable the transport of larger representations is the IP layer) for the transport of larger representations would be
possible up to the maximum size of the underlying datagram protocol possible up to the maximum size of the underlying datagram protocol
(such as UDP), but the fragmentation/reassembly process burdens the (such as UDP), but the fragmentation/reassembly process burdens the
lower layers with conversation state that is better managed in the lower layers with conversation state that is better managed in the
application layer. 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
skipping to change at page 4, line 19 skipping to change at page 4, line 22
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 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.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in RFC 2119, BCP 14 "OPTIONAL" in this document are to be interpreted as described in RFC
[RFC2119] and indicate requirement levels for compliant CoAP 2119, BCP 14 [RFC2119] and indicate requirement levels for compliant
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
skipping to change at page 5, line 28 skipping to change at page 5, line 36
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. encoding, or content-coding used by the Content-Format.
In most cases, all blocks being transferred for a body will be of the In most cases, all blocks being transferred for a body (except for
same size. The block size is not fixed by the protocol. To keep the the last one) will be of the same size. The block size is not fixed
implementation as simple as possible, the Block options support only by the protocol. To keep the implementation as simple as possible,
a small range of power-of-two block sizes, from 2**4 (16) to 2**10 the Block options support only a small range of power-of-two block
(1024) bytes. As bodies often will not evenly divide into the power- sizes, from 2**4 (16) to 2**10 (1024) bytes. As bodies often will
of-two block size chosen, the size need not be reached in the final not evenly divide into the power-of-two block size chosen, the size
block (but even for the final block, the chosen power-of-two size need not be reached in the final block (but even for the final block,
will still be indicated in the block size field of the Block option). the chosen power-of-two size will still be indicated in the block
size field of the Block option).
2.1. The Block2 and Block1 Options 2.1. The Block2 and Block1 Options
+-----+---+---+---+---+--------+--------+--------+---------+
+------+---+---+---+---+--------+--------+--------+---------+ | No. | C | U | N | R | Name | Format | Length | Default |
| Type | C | U | N | R | Name | Format | Length | Default | +-----+---+---+---+---+--------+--------+--------+---------+
+------+---+---+---+---+--------+--------+--------+---------+ | 23 | C | U | - | - | Block2 | uint | 0-3 | (none) |
| 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) | | | | | | | | | | |
| | | | | | | | | | | 27 | C | U | - | - | Block1 | uint | 0-3 | (none) |
| 27 | C | U | - | - | Block1 | uint | 0-3 B | (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 both in 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 [I-D.ietf-core-coap], Block1 is Hence, for the methods defined in [RFC7252], Block1 is useful with
useful with the payload-bearing POST and PUT requests and their the payload-bearing POST and PUT requests and their responses.
responses. Block2 is useful with GET, POST, and PUT requests and Block2 is useful with GET, POST, and PUT requests and their payload-
their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see bearing responses (2.01, 2.02, 2.04, 2.05 -- see section "Payload" of
section "Payload" of [I-D.ietf-core-coap]). [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 block-wise payload forms block-wise transfer and describes how this specific block-wise
part of the entire body being transferred ("descriptive usage"). payload forms part of the entire body being transferred ("descriptive
Where it is present in the opposite direction, it provides additional usage"). Where it is present in the opposite direction, it provides
control on how that payload will be formed or was processed ("control additional control on how that payload will be formed or was
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. It MUST NOT occur more than once.
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 Appendix A of [I-D.ietf-core-coap]). unsigned integer (uint, see Section 3.2 of [RFC7252]). This integer
This integer value encodes these three fields, see Figure 1. (Due to value encodes these three fields, see Figure 1. (Due to the CoAP
the CoAP uint encoding rules, when all of NUM, M, and SZX happen to uint encoding rules, when all of NUM, M, and SZX happen to be zero, a
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 |
skipping to change at page 7, line 36 skipping to change at page 7, line 46
transfer is the last block being transferred. 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 at
byte "NUM << (SZX + 4)". 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 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, if M: More Flag ("not last block"). For descriptive usage, this flag,
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 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 implied by the absence of the option -- the size is left unspecified.
unspecified. (As for any uint, the explicit value 0 is efficiently (As for any uint, the explicit value 0 is efficiently indicated by a
indicated by a zero-length option; this, therefore, is different in zero-length option; this, therefore, is different in semantics from
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
The Block options are used in one of three roles: The Block options are used in one of three roles:
o In descriptive usage, i.e., a Block2 Option in a response (such as o In descriptive usage, i.e., a Block2 Option in a response (such as
a 2.05 response for GET), or a Block1 Option in a request (a PUT a 2.05 response for GET), or a Block1 Option in a request (a PUT
or POST): or POST):
* The NUM field in the option value describes what block number * The NUM field in the option value describes what block number
is contained in the payload of this message. is contained in the payload of this message.
* The M bit indicates whether further blocks need to be * The M bit indicates whether further blocks need to be
transferred to complete the transfer of that body. transferred to complete the transfer of that body.
* The block size given by SZX MUST match the size of the payload * The block size implied by SZX MUST match the size of the
in bytes, if the M bit is set. (SZX does not govern the payload in bytes, if the M bit is set. (SZX does not govern
payload size if M is unset). For Block2, if the request the payload size if M is unset). For Block2, if the request
suggested a larger value of SZX, the next request MUST move SZX suggested a larger value of SZX, the next request MUST move SZX
down to the size given in the response. (The effect is that, down to the size given in the response. (The effect is that,
if the server uses the smaller of (1) its preferred block size if the server uses the smaller of (1) its preferred block size
and (2) the block size requested, all blocks for a body use the and (2) the block size requested, all blocks for a body use the
same block size.) same block size.)
o A Block2 Option in control usage in a request (e.g., GET): o A Block2 Option in control usage in a request (e.g., GET):
* The NUM field in the Block2 Option gives the block number of * The NUM field in the Block2 Option gives the block number of
the payload that is being requested to be returned in the the payload that is being requested to be returned in the
skipping to change at page 10, line 12 skipping to change at page 10, line 17
* Finally, the SZX block size given in a control Block1 Option * Finally, the SZX block size given in a control Block1 Option
indicates the largest block size preferred by the server for indicates the largest block size preferred by the server for
transfers toward the resource that is the same or smaller than transfers toward the resource that is the same or smaller than
the one used in the initial exchange; the client SHOULD use the one used in the initial exchange; the client SHOULD use
this block size or a smaller one in all further requests in the this block size or a smaller one in all further requests in the
transfer sequence, even if that means changing the block size transfer sequence, even if that means changing the block size
(and possibly scaling the block number accordingly) from now (and possibly scaling the block number accordingly) from now
on. on.
Using one or both Block options, a single REST operation can be split Using one or both Block options, a single REST operation can be split
into multiple CoAP message exchanges. As specified in into multiple CoAP message exchanges. As specified in [RFC7252],
[I-D.ietf-core-coap], each of these message exchanges uses their own each of these message exchanges uses their own CoAP Message ID.
CoAP Message ID.
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 and a Block2 Option giving the block number and block size options as the initial request and a Block2 Option giving the block
desired. In a request, the client MUST set the M bit of a Block2 number and block size desired. In a request, the client MUST set the
Option to zero and the server MUST ignore it on reception. M bit of a Block2 Option to zero and the server MUST ignore it on
reception.
To influence the block size used in a response, the requester also To influence the block size used in a response, the requester MAY
uses the Block2 Option, giving the desired size, a block number of also use the Block2 Option on the initial request, giving the desired
zero and an M bit of zero. A server MUST use the block size size, a block number of zero and an M bit of zero. A server MUST use
indicated or a smaller size. Any further block-wise requests for the block size indicated or a smaller size. Any further block-wise
blocks beyond the first one MUST indicate the same block size that requests for blocks beyond the first one MUST indicate the same block
was used by the server in the response for the first request that size that was used by the server in the response for the first
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 SHOULD ultimately use the requests in a single block-wise transfer SHOULD ultimately use the
same size, except that there may not be enough content to fill the same size, except that there may not be enough content to fill the
last block (the one returned with the M bit not set). (Note that the last block (the one returned with the M bit not set). (Note that the
client may start using the Block2 Option in a second request after a client may start using the Block2 Option in a second request after a
first request without a Block2 Option resulted in a Block2 option in first request without a Block2 Option resulted in a Block2 option in
the response.) The server SHOULD use the block size indicated in the the response.) The server SHOULD use the block size indicated in the
request option or a smaller size, but the requester MUST take note of request option or a smaller size, but the requester MUST take note of
skipping to change at page 14, line 8 skipping to change at page 14, line 16
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 Two response codes are defined by this specification beyond those
already defined in [I-D.ietf-core-coap], and another response code is already defined in [RFC7252], and another response code is extended
extended in its meaning. in its meaning.
TODO: Add or appropriate useful response codes for Block2 problems
(overshoot beyond end of representation, unsupported out-of-order
access).
2.9.1. 2.31 Continue 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 serve 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
This new client error status code indicates that the server has not This new client error status code indicates that the server has not
received the blocks of the request body that it needs to proceed. received the blocks of the request body that it needs to proceed.
The client has not sent all blocks, not sent them in the order The client has not sent all blocks, not sent them in the order
required by the server, or has sent them long enough ago that the required by the server, or has sent them long enough ago that the
server has already discarded them. server has already discarded them.
2.9.3. 4.13 Request Entity Too Large 2.9.3. 4.13 Request Entity Too Large
In [I-D.ietf-core-coap], section 5.9.2.9, the response code 4.13 In [RFC7252], section 5.9.2.9, the response code 4.13 (Request Entity
(Request Entity Too Large) is defined to be like HTTP 413 "Request Too Large) is defined to be like HTTP 413 "Request Entity Too Large".
Entity Too Large". [I-D.ietf-core-coap] also recommends that this [RFC7252] also recommends that this response SHOULD include a Size1
response SHOULD include a Size1 Option Section 4 to indicate the Option (Section 4) to indicate the maximum size of request entity the
maximum size of request entity the server is able and willing to server is able and willing to handle, unless the server is not in a
handle, unless the server is not in a position to make this position to make this information available.
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.
skipping to change at page 15, line 42 skipping to change at page 15, line 45
| <------ 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 blockwise GET Figure 2: Simple blockwise GET
In the second example (Figure 3), the client anticipates the In the second example (Figure 3), the client anticipates the
blockwise transfer (e.g., because of a size indication in the link- blockwise transfer (e.g., because of a size indication in the link-
format description [RFC6690]) and sends a size proposal. All ACK format description [RFC6690]) and sends a block size proposal. All
messages except for the last carry 64 bytes of payload; the last one ACK messages except for the last carry 64 bytes of payload; the last
carries between 1 and 64 bytes. one 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 ------> |
| | | |
| <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 | | <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 |
| | | |
| CON [MID=1235], GET, /status, 2:1/0/64 ------> | | CON [MID=1235], GET, /status, 2:1/0/64 ------> |
| | | |
| <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 | | <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 |
skipping to change at page 23, line 19 skipping to change at page 24, line 5
| 2.05 | Token: 0xfc | 2.05 | Token: 0xfc
| | Block2: 2/0/128 | | Block2: 2/0/128
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [53 bytes] | | Payload: [53 bytes]
Figure 12: Observe sequence with blockwise response Figure 12: Observe sequence with blockwise response
In the following example, the client also uses early negotiation to In the following example, the client also uses early negotiation to
limit the block size to 64 bytes. limit the block size to 64 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
+----->| Header: GET 0x41011636 +----->| Header: GET 0x41011636
| GET | Token: 0xfb | GET | Token: 0xfb
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Observe: (empty) | | Observe: (empty)
| | Block2: 0/0/64 | | Block2: 0/0/64
| | | |
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/64 | | Block2: 0/1/64
| | Observe: 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
| | | |
| | (Retrieval of remaining blocks) | | (Retrieval of remaining blocks)
| | | |
+----->| Header: GET 0x41011637 +----->| Header: GET 0x41011637
| GET | Token: 0xfc | GET | Token: 0xfc
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Block2: 1/0/64 | | Block2: 1/0/64
| | | |
|<-----+ Header: 2.05 0x61451637 |<-----+ Header: 2.05 0x61451637
| 2.05 | Token: 0xfc | 2.05 | Token: 0xfc
| | Block2: 1/1/64 | | Block2: 1/1/64
| | ETag: 6f00f392 | | ETag: 6f00f392
| | Payload: [64 bytes] | | Payload: [64 bytes]
.... ....
| | | |
+----->| Header: GET 0x41011638 +----->| Header: GET 0x41011638
| 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 is already defined in [RFC7252] for the narrow case of
indicating in 4.13 responses the maximum size of request payload that
the server is able and willing to handle.)
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 [I-D.ietf-core-coap], 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. The Size Options
MUST NOT occur more than once. MUST NOT occur more than once.
+------+---+---+---+---+-------+--------+--------+---------+ +-----+---+---+---+---+-------+--------+--------+---------+
| Type | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+-------+--------+--------+---------+ +-----+---+---+---+---+-------+--------+--------+---------+
| 60 | | | x | | Size1 | uint | 0-4 B | (none) | | 60 | | | x | | Size1 | uint | 0-4 | (none) |
| | | | | | | | | | | | | | | | | | | |
| 28 | | | x | | Size2 | uint | 0-4 B | (none) | | 28 | | | x | | Size2 | uint | 0-4 | (none) |
+------+---+---+---+---+-------+--------+--------+---------+ +-----+---+---+---+---+-------+--------+--------+---------+
Table 2: Size Option Numbers Table 2: Size Option Numbers
Implementation Notes: Implementation Notes:
o As a quality of implementation consideration, blockwise transfers o As a quality of implementation consideration, blockwise 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 blockwise transfer is governed by the M bits in the o The end of a blockwise 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. as an empty option (0 bytes). There is no default value for
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 for the influence the
Block options might have on intermediaries that map between CoAP and Block options might have on intermediaries that map between CoAP and
HTTP. HTTP.
For mapping CoAP requests to HTTP, the intermediary may want to map For mapping CoAP requests to HTTP, the intermediary may want to map
the 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 E.g., for a GET request, the intermediary could perform the HTTP
request once the first block has been requested and could then 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
skipping to change at page 26, line 18 skipping to change at page 27, line 5
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 E.g., for a GET request, the intermediary could perform the HTTP
request once the first block has been requested and could then 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, there is more variation in how HTTP servers For PUT or POST requests, historically there was more variation in
might implement ranges. Some WebDAV servers do, but in general the how HTTP servers might implement ranges; recently, [RFC7233] has
CoAP-to-HTTP intermediary will have to try sending the payload of all defined that Range header fields received with a request method other
the blocks of a block-wise transfer within one HTTP request. If than GET are not to be interpreted. So, in general, the CoAP-to-HTTP
enough buffering is available, this request can be started when the intermediary will have to try sending the payload of all the blocks
last CoAP block is received. A constrained implementation may want of a block-wise transfer for these other methods within one HTTP
to relieve its buffering by already starting to send the HTTP request request. If enough buffering is available, this request can be
at the time the first CoAP block is received; any HTTP 408 status started when the last CoAP block is received. A constrained
code that indicates that the HTTP server became impatient with the implementation may want to relieve its buffering by already starting
resulting transfer can then be mapped into a CoAP 4.08 response code to send the HTTP request at the time the first CoAP block is
(similarly, 413 maps to 4.13). received; any HTTP 408 status code that indicates that the HTTP
server became impatient with the resulting transfer can then be
mapped into a CoAP 4.08 response code (similarly, 413 maps to 4.13).
For mapping HTTP to CoAP, the intermediary may want to map a single 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. overlapping the range.
skipping to change at page 27, line 23 skipping to change at page 27, line 46
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 draft adds the following option numbers to the CoAP Option
Numbers registry of [I-D.ietf-core-coap]: Numbers registry of [RFC7252]:
+--------+--------+-----------+ +--------+--------+-----------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+--------+-----------+ +--------+--------+-----------+
| 23 | Block2 | [RFCXXXX] | | 23 | Block2 | [RFCXXXX] |
| | | | | | | |
| 27 | Block1 | [RFCXXXX] | | 27 | Block1 | [RFCXXXX] |
| | | | | | | |
| 28 | Size2 | [RFCXXXX] | | 28 | Size2 | [RFCXXXX] |
| | | |
| 60 | Size1 | [RFCXXXX] |
+--------+--------+-----------+ +--------+--------+-----------+
Table 3: CoAP Option Numbers Table 3: CoAP Option Numbers
This draft adds the following response code to the CoAP Response This draft adds the following response code to the CoAP Response
Codes registry of [I-D.ietf-core-coap]: Codes registry of [RFC7252]:
+------+---------------------------+-----------+ +------+---------------------------+-----------+
| Code | Description | Reference | | Code | Description | Reference |
+------+---------------------------+-----------+ +------+---------------------------+-----------+
| 2.31 | Continue | [RFCXXXX] | | 2.31 | Continue | [RFCXXXX] |
| | | | | | | |
| 4.08 | Request Entity Incomplete | [RFCXXXX] | | 4.08 | Request Entity Incomplete | [RFCXXXX] |
+------+---------------------------+-----------+ +------+---------------------------+-----------+
Table 4: CoAP Response Codes Table 4: CoAP Response Codes
skipping to change at page 28, line 24 skipping to change at page 28, line 49
transferred by CoAP implement the Block options to gain access to transferred by CoAP implement the Block options to gain access to
entire resource representations. Still, approaches such as entire resource representations. Still, approaches such as
transferring even-numbered blocks on one path and odd-numbered blocks transferring even-numbered blocks on one path and odd-numbered blocks
on another path, or even transferring blocks multiple times with on another path, or even transferring blocks multiple times with
different content and obtaining a different interpretation of different content and obtaining a different interpretation of
temporal order at the IDS than at the server, may prevent an IDS from temporal order at the IDS than at the server, may prevent an IDS from
seeing the whole picture. These kinds of attacks are well understood seeing the whole picture. These kinds of attacks are well understood
from IP fragmentation and TCP segmentation; CoAP does not add from IP fragmentation and TCP segmentation; CoAP does not add
fundamentally new considerations. fundamentally new considerations.
Where access to a resource is only granted to clients making use of a Where access to a resource is only granted to clients making use of
specific security association, 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. the creation of unusable resources can be tolerated.
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
skipping to change at page 29, line 12 skipping to change at page 29, line 37
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), e.g. because there is fragmentation, adaptation layer fragmentation), for instance because
application layer semantics that can be used for mitigation or there is application layer semantics that can be used for mitigation
because lower layers provide security associations that can prevent or because lower layers provide security associations that can
attacks. However, it is less common to apply timeouts and keepalive prevent attacks. However, it is less common to apply timeouts and
mechanisms at the application layer than at lower layers. Servers keepalive mechanisms at the application layer than at lower layers.
MAY want to clean up accumulated state by timing it out (cf. response Servers MAY want to clean up accumulated state by timing it out (cf.
code 4.08), and clients SHOULD be prepared to run blockwise transfers response code 4.08), and clients SHOULD be prepared to run blockwise
in an expedient way to minimize the likelihood of running into such a transfers in an expedient way to minimize the likelihood of running
timeout. into such a timeout.
7.2. Mitigating Amplification Attacks 7.2. Mitigating Amplification Attacks
[I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points [RFC7252] discusses the susceptibility of CoAP end-points for use in
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. Acknowledgements 8. Acknowledgements
Much of the content of this draft is the result of discussions with Much of the content of this draft is the result of discussions with
the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. the [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 version of this draft, some of which the authors hope to have covered
in this version. Esko Dijk reviewed a more recent version, leading in this version. Esko Dijk reviewed a more recent version, leading
to a number of further editorial improvements, a solution to the 4.13 to 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. Markus Becker proposed getting rid of an ill-conceived
default value for the Block2 and Block1 options. Peter Bigot default value for the Block2 and Block1 options. Peter Bigot
insisted on a more systematic coverage of the options and response insisted on a more systematic coverage of the options and response
code. code.
skipping to change at page 30, line 4 skipping to change at page 30, line 30
to a number of further editorial improvements, a solution to the 4.13 to 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. Markus Becker proposed getting rid of an ill-conceived
default value for the Block2 and Block1 options. Peter Bigot default value for the Block2 and Block1 options. Peter Bigot
insisted on a more systematic coverage of the options and response insisted on a more systematic coverage of the options and response
code. code.
Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of
the Size Option, which has informed this draft. Klaus Hartke wrote the Size Option, which has informed this draft. Klaus Hartke wrote
some of the text describing the interaction of Block2 with Observe. some of the text describing the interaction of Block2 with Observe.
Matthias Kovatsch provided a number of significant simplifications of Matthias Kovatsch provided a number of significant simplifications of
the protocol. the protocol.
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), June 2013.
[I-D.ietf-core-observe] [I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP", draft-ietf- Hartke, K., "Observing Resources in CoAP", draft-ietf-
core-observe-11 (work in progress), October 2013. core-observe-14 (work in progress), June 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Application Protocol (CoAP)", RFC 7252, June 2014.
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
9.2. Informative References 9.2. Informative References
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation, Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000, <http:// University of California, Irvine, 2000,
www.ics.uci.edu/~fielding/pubs/dissertation/ <http://www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>. fielding_dissertation.pdf>.
[RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
over Low-Power Wireless Personal Area Networks (6LoWPANs): over Low-Power Wireless Personal Area Networks (6LoWPANs):
Overview, Assumptions, Problem Statement, and Goals", RFC Overview, Assumptions, Problem Statement, and Goals", RFC
4919, August 2007. 4919, August 2007.
[RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
"Transmission of IPv6 Packets over IEEE 802.15.4
Networks", RFC 4944, September 2007.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012. Format", RFC 6690, August 2012.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, May 2014.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June
2014.
[RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext
Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233,
June 2014.
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)
Sensinode ARM
Kidekuja 2 150 Rose Orchard
Vuokatti 88600 San Jose, CA 95134
Finland USA
Phone: +358407796297 Phone: +1-408-203-9434
Email: zach@sensinode.com Email: zach.shelby@arm.com
 End of changes. 59 change blocks. 
209 lines changed or deleted 221 lines changed or added

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