draft-ietf-core-block-11.txt   draft-ietf-core-block-12.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: October 01, 2013 Sensinode Expires: December 29, 2013 Sensinode
March 30, 2013 June 27, 2013
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-11 draft-ietf-core-block-12
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 -\u002D 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 1, line 46 skipping to change at page 1, line 46
other server-side memory of previous block transfers. other server-side memory of previous block transfers.
In summary, the Block options provide a minimal way to transfer In summary, the Block options provide a minimal way to transfer
larger representations in a block-wise fashion. larger representations in a block-wise fashion.
The present revision -11 fixes one example and adds the text and The present revision -11 fixes one example and adds the text and
examples about the Block/Observe interaction, taken from -observe. examples about the Block/Observe interaction, taken from -observe.
It also adds a couple of formatting bugs from the new xml2rfc. The It also adds a couple of formatting bugs from the new xml2rfc. The
"grand rewrite" is next. "grand rewrite" is next.
Status of This Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 01, 2013. This Internet-Draft will expire on December 29, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 5 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6
2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 5 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6
2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7
2.3. Block Options in Requests and Responses . . . . . . . . . 8 2.3. Block Options in Requests and Responses . . . . . . . . . 9
2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 11
2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 12
2.6. Combining Blockwise Transfers with the Observe Option . . 12 2.6. Combining Blockwise Transfers with the Observe Option . . 13
2.7. Block2 and Initiative . . . . . . . . . . . . . . . . . . 13 2.7. Block2 and Initiative . . . . . . . . . . . . . . . . . . 14
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 13 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15
3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 16 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18
3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 18 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20
3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 20 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . . 22
4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 23 4. The Size Options . . . . . . . . . . . . . . . . . . . . . . . 26
5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 24 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 28
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30
7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31
7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 26 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 31
7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 27 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 32
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.1. Normative References . . . . . . . . . . . . . . . . . . 28 9.1. Normative References . . . . . . . . . . . . . . . . . . . 34
9.2. Informative References . . . . . . . . . . . . . . . . . 28 9.2. Informative References . . . . . . . . . . . . . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35
1. Introduction 1. Introduction
The CoRE WG is tasked with standardizing an Application Protocol for The CoRE WG is tasked with standardizing an Application Protocol for
Constrained Networks/Nodes, CoAP. This protocol is intended to Constrained Networks/Nodes, CoAP. This protocol is intended to
provide RESTful [REST] services not unlike HTTP [RFC2616], while provide RESTful [REST] services not unlike HTTP [RFC2616], while
reducing the complexity of implementation as well as the size of reducing the complexity of implementation as well as the size of
packets exchanged in order to make these services useful in a highly packets exchanged in order to make these services useful in a highly
constrained network of themselves highly constrained nodes. constrained network of themselves highly constrained nodes.
skipping to change at page 5, line 24 skipping to change at page 6, line 24
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 the following, the term "payload" will be used for the actual In the following, the term "payload" will be used for the actual
content of a single CoAP message, i.e. a single block being content of a single CoAP message, i.e. a single block being
transferred, while the term "body" will be used for the entire transferred, while the term "body" will be used for the entire
resource representation that is being transferred in a block-wise resource representation that is being transferred in a block-wise
fashion. The Content-Format option applies to the body, not to the fashion. The Content-Format option applies to the body, not to the
payload, in particular the boundaries between the blocks may in payload, in particular the boundaries between the blocks may in
places that are not whole units in terms of the structure, encoding, places that are not whole units in terms of the structure, encoding,
or content-coding used by the Content-Format. or content-coding used by the Content-Format.
In most cases, all blocks being transferred for a body will be of the In most cases, all blocks being transferred for a body will be of the
same size. The block size is not fixed by the protocol. To keep the same size. The block size is not fixed by the protocol. To keep the
implementation as simple as possible, the Block options support only implementation as simple as possible, the Block options support only
skipping to change at page 6, line 13 skipping to change at page 7, line 13
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 [I-D.ietf-core-coap], Block1 is
useful with the payload-bearing POST and PUT requests and their useful with the payload-bearing POST and PUT requests and their
responses. Block2 is useful with GET, POST, and PUT requests and responses. Block2 is useful with GET, POST, and PUT requests and
their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -\u002D see their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see
section "Payload" of [I-D.ietf-core-coap]). section "Payload" of [I-D.ietf-core-coap]).
(As a memory aid: Block_1_ pertains to the payload of the _1st_ part (As a memory aid: Block_1_ pertains to the payload of the _1st_ part
of the request-response exchange, i.e. the request, and Block_2_ of the request-response exchange, i.e. the request, and Block_2_
pertains to the payload of the _2nd_ part of the request-response pertains to the payload of the _2nd_ part of the request-response
exchange, i.e. the response.) exchange, i.e. the response.)
Where Block1 is present in a request or Block2 in a response (i.e., Where Block1 is present in a request or Block2 in a response (i.e.,
in that message to the payload of which it pertains) it indicates a in that message to the payload of which it pertains) it indicates a
block-wise transfer and describes how this block-wise payload forms block-wise transfer and describes how this block-wise payload forms
part of the entire body being transferred ("descriptive usage"). part of the entire body being transferred ("descriptive usage").
Where it is present in the opposite direction, it provides additional Where it is present in the opposite direction, it provides additional
control on how that payload will be formed or was processed ("control control on how that payload will be formed or was processed ("control
usage"). usage").
Implementation of either Block option is intended to be optional. Implementation of either Block option is intended to be optional.
skipping to change at page 8, line 26 skipping to change at page 9, line 26
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 -\u002D 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
skipping to change at page 9, line 35 skipping to change at page 10, 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
skipping to change at page 11, line 51 skipping to change at page 13, line 5
has been reached, and try restating the request as a block-wise has been reached, and try restating the request as a block-wise
transfer with a smaller payload. Note that this new attempt is then transfer with a smaller payload. Note that this new attempt is then
a new message-layer transaction and requires a new Message ID. a new message-layer transaction and requires a new Message ID.
(Because of the uncertainty whether the request or the (Because of the uncertainty whether the request or the
acknowledgement was lost, this strategy is useful mostly for acknowledgement was lost, this strategy is useful mostly for
idempotent requests.) idempotent requests.)
In a blockwise transfer of a request payload (e.g., a PUT or POST) In a blockwise transfer of a request payload (e.g., a PUT or POST)
that is intended to be implemented in an atomic fashion at the that is intended to be implemented in an atomic fashion at the
server, the actual creation/replacement takes place at the time the server, the actual creation/replacement takes place at the time the
final block, i.e. a block with the M bit unset in the Block1 Option, final block, i.e. a block with the M bit unset in the Block1 Option,
is received. If not all previous blocks are available at the server is received. If not all previous blocks are available at the server
at this time, the transfer fails and error code 4.08 (Request Entity at this time, the transfer fails and error code 4.08 (Request Entity
Incomplete) MUST be returned. The error code 4.13 (Request Entity Incomplete) MUST be returned. The error code 4.13 (Request Entity
Too Large) can be returned at any time by a server that does not Too Large) can be returned at any time by a server that does not
currently have the resources to store blocks for a block-wise request currently have the resources to store blocks for a block-wise request
payload transfer that it would intend to implement in an atomic payload transfer that it would intend to implement in an atomic
fashion. (Note that a 4.13 response to a request that does not fashion. (Note that a 4.13 response to a request that does not
employ Block1 is a hint for the client to try sending Block1, and a employ Block1 is a hint for the client to try sending Block1, and a
4.13 response with a smaller SZX in its Block1 option than requested 4.13 response with a smaller SZX in its Block1 option than requested
is a hint to try a smaller SZX.) is a hint to try a smaller SZX.)
skipping to change at page 17, line 22 skipping to change at page 19, line 27
| <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 |
Figure 7: Simple atomic blockwise PUT Figure 7: Simple atomic blockwise PUT
A stateless server that simply builds/updates the resource in place A stateless server that simply builds/updates the resource in place
(statelessly) may indicate this by not setting the more bit in the (statelessly) may indicate this by not setting the more bit in the
response (Figure 8); in this case, the response codes are valid response (Figure 8); in this case, the response codes are valid
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 ------> |
| | | |
skipping to change at page 20, line 29 skipping to change at page 23, line 5
early negotiation early negotiation
3.4. Combining Observe and Block2 3.4. Combining Observe and Block2
In the following example, the server sends two notifications of two In the following example, the server sends two notifications of two
blocks each. The first notification is a direct response to the GET blocks each. The first notification is a direct response to the GET
request; the first block therefore can be sent piggy-backed in the request; the first block therefore can be sent piggy-backed in the
ACK. The Observe Option indicates that the initiative has switched ACK. The Observe Option indicates that the initiative has switched
to the server. to the server.
CLIENT SERVER CLIENT SERVER
| | | |
+----->| Header: GET 0x41011636 +----->| Header: GET 0x41011636
| GET | Token: 0xfb | GET | Token: 0xfb
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Observe: (empty) | | Observe: (empty)
| | | |
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/128 | | Block2: 0/1/128
| | Observe: 62354 | | Observe: 62354
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
| | (initiative changes to server) | | (initiative changes to server)
| | | |
|<-----+ Header: 2.05 0x4145af9c |<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 1/0/128 | | Block2: 1/0/128
| | Observe: 62354 | | Observe: 62354
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [27 bytes] | | Payload: [27 bytes]
| | | |
+- - ->| Header: 0x6000af9c +- - ->| Header: 0x6000af9c
| | | |
|<-----+ Header: 2.05 0x4145af9d |<-----+ Header: 2.05 0x4145af9d
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/128 | | Block2: 0/1/128
| | Observe: 62444 | | Observe: 62444
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
+- - ->| Header: 0x6000af9d +- - ->| Header: 0x6000af9d
| | | |
|<-----+ Header: 2.05 0x4145af9e |<-----+ Header: 2.05 0x4145af9e
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 1/0/128 | | Block2: 1/0/128
| | Observe: 62444 | | Observe: 62444
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [27 bytes] | | Payload: [27 bytes]
| | | |
+- - ->| Header: 0x6000af9e +- - ->| Header: 0x6000af9e
| | | |
Figure 12: Observe sequence with blockwise response Figure 12: Observe sequence with blockwise response
In the following example, the client also uses early negotiation to In the following example, the client also uses early negotiation to
limit the block size to 64 bytes. limit the block size to 64 bytes.
CLIENT SERVER CLIENT SERVER
| | | |
+----->| Header: GET 0x41011636 +----->| Header: GET 0x41011636
| GET | Token: 0xfb | GET | Token: 0xfb
| | Uri-Path: status-icon | | Uri-Path: status-icon
| | Observe: (empty) | | Observe: (empty)
| | Block2: 0/0/64 | | Block2: 0/0/64
| | | |
|<-----+ Header: 2.05 0x61451636 |<-----+ Header: 2.05 0x61451636
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/64 | | Block2: 0/1/64
| | Observe: 62354 | | Observe: 62354
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [64 bytes] | | Payload: [64 bytes]
| | | |
| | (initiative changes to server) | | (initiative changes to server)
| | | |
|<-----+ Header: 2.05 0x4145af9c |<-----+ Header: 2.05 0x4145af9c
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 1/1/64 | | Block2: 1/1/64
| | Observe: 62354 | | Observe: 62354
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [64 bytes] | | Payload: [64 bytes]
| | | |
+- - ->| Header: 0x6000af9c +- - ->| Header: 0x6000af9c
| | | |
|<-----+ Header: 2.05 0x4145af9d |<-----+ Header: 2.05 0x4145af9d
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 2/0/64 | | Block2: 2/0/64
| | Observe: 62354 | | Observe: 62354
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [27 bytes] | | Payload: [27 bytes]
| | | |
+- - ->| Header: 0x6000af9d +- - ->| Header: 0x6000af9d
| | | |
|<-----+ Header: 2.05 0x4145af9e |<-----+ Header: 2.05 0x4145af9e
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 0/1/64 | | Block2: 0/1/64
| | Observe: 62444 | | Observe: 62444
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
+- - ->| Header: 0x6000af9e +- - ->| Header: 0x6000af9e
| | | |
|<-----+ Header: 2.05 0x4145af9f |<-----+ Header: 2.05 0x4145af9f
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 1/1/64 | | Block2: 1/1/64
| | Observe: 62444 | | Observe: 62444
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [128 bytes] | | Payload: [128 bytes]
| | | |
+- - ->| Header: 0x6000af9f +- - ->| Header: 0x6000af9f
| | | |
|<-----+ Header: 2.05 0x4145afa0 |<-----+ Header: 2.05 0x4145afa0
| 2.05 | Token: 0xfb | 2.05 | Token: 0xfb
| | Block2: 2/0/64 | | Block2: 2/0/64
| | Observe: 62444 | | Observe: 62444
| | Max-Age: 60 | | Max-Age: 60
| | Payload: [27 bytes] | | Payload: [27 bytes]
| | | |
+- - ->| Header: 0x6000afa0 +- - ->| Header: 0x6000afa0
| | | |
Figure 13: Observe sequence with early negotiation Figure 13: Observe sequence with early negotiation
4. The Size Option 4. The Size Options
In many cases when transferring a large resource representation block In many cases when transferring a large resource representation block
by block, it is advantageous to know the total size early in the by block, it is advantageous to know the total size early in the
process. Some indication may be available from the maximum size process. Some indication may be available from the maximum size
estimate attribute "sz" provided in a resource description [RFC6690]. estimate attribute "sz" provided in a resource description [RFC6690].
However, the size may vary dynamically, so a more up-to-date However, the size may vary dynamically, so a more up-to-date
indication may be useful. indication may be useful.
The Size Option may be used for three purposes: This specification defines two CoAP Options, Size1 for indicating the
size of the representation transferred in requests, and Size2 for
indicating the size of the representation transferred in responses.
The Size2 Option may be used for two purposes:
o in a request, to ask the server to provide a size estimate along 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. representation, measured in bytes ("size indication").
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. representation, measured in bytes ("size indication").
In the latter two cases ("size indication"), the value of the option o in a 4.13 response, to indicate the maximum size that would have
is the current estimate, measured in bytes. been acceptable [I-D.ietf-core-coap], measured in bytes.
A size request can be easily distinguished from a size indication, as Apart from conveying/asking for size information, the Size options
the third case is not useful for a GET or DELETE, and an actual size have no other effect on the processing of the request or response.
indication of 0 would either be overridden by the actual size of the If the client wants to minimize the size of the payload in the
payload for a PUT or POST or would not be useful. resulting response, it should add a Block2 option to the request with
a small block size (e.g., setting SZX=0).
Apart from conveying/asking for size information, the Size option has The Size Options are "elective", i.e., a client MUST be prepared for
no other effect on the processing of the request or response. If the the server to ignore the size estimate request. The Size Options
client wants to minimize the size of the payload in the resulting MUST NOT occur more than once.
response, it should add a Block2 option to the request with a small
block size (e.g., setting SZX=0).
The Size Option is "elective", i.e., a client MUST be prepared for +------+---+---+---+---+-------+--------+--------+---------+
the server to ignore the size estimate request. The Size Option MUST | Type | C | U | N | R | Name | Format | Length | Default |
NOT occur more than once. +------+---+---+---+---+-------+--------+--------+---------+
| 60 | | | x | | Size1 | uint | 0-4 B | (none) |
| | | | | | | | | |
| 28 | | | x | | Size2 | uint | 0-4 B | (none) |
+------+---+---+---+---+-------+--------+--------+---------+
+------+---+---+---+---+------+--------+--------+---------+ Table 2: Size Option Numbers
| Type | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+------+--------+--------+---------+
| 28 | - | - | N | - | Size | uint | 0-4 B | (none) |
+------+---+---+---+---+------+--------+--------+---------+
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.
o Size is neither critical nor unsafe, and is marked as No-Cache- o The Size Options are neither critical nor unsafe, and are marked
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
skipping to change at page 25, line 36 skipping to change at page 30, line 15
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 [I-D.ietf-core-coap]:
+--------+--------+-----------+ +--------+--------+-----------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+--------+-----------+ +--------+--------+-----------+
| 23 | Block2 | [RFCXXXX] | | 23 | Block2 | [RFCXXXX] |
| | | | | | | |
| 28 | Size | [RFCXXXX] |
| | | |
| 27 | Block1 | [RFCXXXX] | | 27 | Block1 | [RFCXXXX] |
| | | |
| 28 | Size2 | [RFCXXXX] |
| | | |
| 60 | Size1 | [RFCXXXX] |
+--------+--------+-----------+ +--------+--------+-----------+
Table 2: CoAP Option Numbers Table 3: CoAP Option Numbers
This draft adds the following response code to the CoAP Response This draft adds the following response code to the CoAP Response
Codes registry of [I-D.ietf-core-coap]: Codes registry of [I-D.ietf-core-coap]:
+------+--------------------------------+-----------+ +------+--------------------------------+-----------+
| Code | Description | Reference | | Code | Description | Reference |
+------+--------------------------------+-----------+ +------+--------------------------------+-----------+
| 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] |
+------+--------------------------------+-----------+ +------+--------------------------------+-----------+
Table 3: 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; it is RECOMMENDED that an intrusion
detection system (IDS) that analyzes resource representations detection system (IDS) that analyzes resource representations
skipping to change at page 27, line 4 skipping to change at page 31, line 43
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 blockwise requests may induce the server to create state, Certain blockwise requests may induce the server to create state,
e.g. to create a snapshot for the blockwise GET of a fast-changing e.g. to create a snapshot for the blockwise GET of a fast-changing
resource to enable consistent access to the same version of a resource to enable consistent access to the same version of a
resource for all blocks, or to create temporary resource resource for all blocks, or to create temporary resource
representations that are collected until pressed into service by a representations that are collected until pressed into service by a
final PUT or POST with the more bit unset. All mechanisms that final PUT or POST with the more bit unset. All mechanisms that
induce a server to create state that cannot simply be cleaned up induce a server to create state that cannot simply be cleaned up
create opportunities for denial-of-service attacks. Servers SHOULD create opportunities for denial-of-service attacks. Servers SHOULD
avoid being subject to resource exhaustion based on state created by avoid being subject to resource exhaustion based on state created by
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 fragmentation, adaptation layer fragmentation), e.g. because there is
is application layer semantics that can be used for mitigation or application layer semantics that can be used for mitigation or
because lower layers provide security associations that can prevent because lower layers provide security associations that can prevent
attacks. However, it is less common to apply timeouts and keepalive attacks. However, it is less common to apply timeouts and keepalive
mechanisms at the application layer than at lower layers. Servers mechanisms at the application layer than at lower layers. Servers
MAY want to clean up accumulated state by timing it out (cf. MAY want to clean up accumulated state by timing it out (cf. response
response code 4.08), and clients SHOULD be prepared to run blockwise code 4.08), and clients SHOULD be prepared to run blockwise transfers
transfers in an expedient way to minimize the likelihood of running in an expedient way to minimize the likelihood of running into such a
into such a timeout. timeout.
7.2. Mitigating Amplification Attacks 7.2. Mitigating Amplification Attacks
[I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points
for use in amplification attacks. for use in amplification attacks.
A CoAP server can reduce the amount of amplification it provides to A CoAP server can reduce the amount of amplification it provides to
an attacker by offering large resource representations only in an attacker by offering large resource representations only in
relatively small blocks. With this, e.g., for a 1000 byte resource, relatively small blocks. With this, e.g., for a 1000 byte resource,
a 10-byte request might result in an 80-byte response (with a 64-byte a 10-byte request might result in an 80-byte response (with a 64-byte
skipping to change at page 28, line 17 skipping to change at page 34, line 11
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.
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-core-coap] [I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-14 Application Protocol (CoAP)", draft-ietf-core-coap-17
(work in progress), March 2013. (work in progress), May 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",
core-observe-08 (work in progress), February 2013. draft-ietf-core-observe-08 (work in progress),
February 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
9.2. Informative References 9.2. Informative References
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation, Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000, <http:// University of California, Irvine, 2000, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/ www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>. fielding_dissertation.pdf>.
[RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
over Low-Power Wireless Personal Area Networks (6LoWPANs): over Low-Power Wireless Personal Area Networks (6LoWPANs):
Overview, Assumptions, Problem Statement, and Goals", RFC Overview, Assumptions, Problem Statement, and Goals",
4919, August 2007. RFC 4919, August 2007.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012. Format", RFC 6690, August 2012.
Authors' Addresses Authors' Addresses
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
 End of changes. 39 change blocks. 
194 lines changed or deleted 203 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/