draft-ietf-core-block-07.txt   draft-ietf-core-block-08.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: July 30, 2012 Sensinode Expires: August 18, 2012 Sensinode
January 27, 2012 February 15, 2012
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-07 draft-ietf-core-block-08
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 firmware will need to transfer larger payloads -- for instance, for firmware
updates. With HTTP, TCP does the grunt work of slicing large updates. With HTTP, TCP does the grunt work of slicing large
payloads up into multiple packets and ensuring that they all arrive payloads up into multiple packets and ensuring that they all arrive
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 July 30, 2012. This Internet-Draft will expire on August 18, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 12 skipping to change at page 3, line 12
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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6
2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6
2.2. Using the Block Options . . . . . . . . . . . . . . . . . 10 2.2. Using the Block Options . . . . . . . . . . . . . . . . . 10
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 20 4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22
6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
6.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 23 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
6.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 24 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27
8.1. Normative References . . . . . . . . . . . . . . . . . . . 26 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.2. Informative References . . . . . . . . . . . . . . . . . . 26 9.1. Normative References . . . . . . . . . . . . . . . . . . . 28
Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 27 9.2. Informative References . . . . . . . . . . . . . . . . . . 28
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
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 12, line 39 skipping to change at page 12, line 39
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. fashion. (Note that a 4.13 response to a request that does not
employ Block1 is a hint for the client to try sending Block1, and a
4.13 response with a smaller SZX in the Block1 than requested is a
hint to try a smaller SZX.)
If multiple concurrently proceeding block-wise request payload If multiple concurrently proceeding block-wise request payload
transfer (e.g., PUT or POST) operations are possible, the requester transfer (e.g., PUT or POST) operations are possible, the requester
SHOULD use the Token Option to clearly separate the different SHOULD use the Token Option to clearly separate the different
sequences. In this case, when reassembling the representation from sequences. In this case, when reassembling the representation from
the blocks being exchanged to enable atomic processing, the the blocks being exchanged to enable atomic processing, the
reassembler MUST compare any Token Options present (and, as usual, reassembler MUST compare any Token Options present (and, as usual,
taking an absent Token Option to default to the empty Token). If taking an absent Token Option to default to the empty Token). If
atomic processing is not desired, there is no need to process the atomic processing is not desired, there is no need to process the
Token Option (but it is still returned in the response as usual). Token Option (but it is still returned in the response as usual).
skipping to change at page 13, line 42 skipping to change at page 13, line 42
| <------ 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) and sends a size proposal. All ACK messages format description [I-D.ietf-core-link-format]) and sends a size
except for the last carry 64 bytes of payload; the last one carries proposal. All ACK messages except for the last carry 64 bytes of
between 1 and 64 bytes. payload; the last 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 20, line 5 skipping to change at page 20, line 5
| <------ CON [MID=4714], 2.01 Created, 37a, 2/2/1/128 | | <------ CON [MID=4714], 2.01 Created, 37a, 2/2/1/128 |
| | | |
| ACK [MID=4714], 0, 2/2/1/128 ------> | | ACK [MID=4714], 0, 2/2/1/128 ------> |
| | | |
| <------ CON [MID=4715], 2.01 Created, 37a, 2/3/0/128 | | <------ CON [MID=4715], 2.01 Created, 37a, 2/3/0/128 |
| | | |
| ACK [MID=4715], 0, 2/3/0/128 ------> | | ACK [MID=4715], 0, 2/3/0/128 ------> |
Figure 10: Atomic blockwise POST with separate blockwise response Figure 10: Atomic blockwise POST with separate blockwise response
4. HTTP Mapping Considerations 4. The Size Option
In many cases when transferring a large resource representation block
by block, it is advantageous to know the total size early in the
process. Some indication may be available from the maximum size
estimate attribute "sz" provided in a resource description
[I-D.ietf-core-link-format]. However, the size may vary dynamically,
so a more up-to-date indication may be useful.
The Size Option may be used for three purposes:
o in a request, to ask the server to provide a size estimate in the
response ("size request"). For this usage, the value MUST be set
to 0.
o in a response carrying a Block2 Option, to indicate the current
estimate the server has of the total size of the resource
representation.
o in a request carrying a Block1 Option, to indicate the current
estimate the client has of the total size of the resource
representation.
A size request can be easily distinguished from a size indication, as
the third case is not useful for a GET or DELETE, and an actual size
indication of 0 would either be overridden by the actual size of the
payload for a PUT or POST or would not be useful.
In the latter two cases ("size indication"), the value of the option
is the current estimate, measured in bytes.
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
NOT occur more than once.
+------+----------+------+--------+--------+---------+
| Type | C/E | Name | Format | Length | Default |
+------+----------+------+--------+--------+---------+
| 18 | Elective | Size | uint | 0-4 B | (none) |
+------+----------+------+--------+--------+---------+
Implementation Notes:
o As a quality of implementation consideration, blockwise transfers
for which the total size considerably exceeds the size of one
block are expected to include size indications, whenever those can
be provided without undue effort (preferably with the first block
exchanged). If the size estimate does not change, the indication
does not need to be repeated for every block.
o The end of a blockwise transfer is governed by the M bits in the
Block Options, _not_ by exhausting the size estimates exchanged.
o As usual for an option of type uint, the value 0 is best expressed
as an empty option (0 bytes). There is no default value.
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
skipping to change at page 22, line 5 skipping to change at page 24, line 5
transmitting a request through that active TCP connection. The CoAP transmitting a request through that active TCP connection. The CoAP
4.08 response code indicates one or more missing blocks, which may be 4.08 response code indicates one or more missing blocks, which may be
due to timeouts or resource constraints; as there is no connection due to timeouts or resource constraints; as there is no connection
state, there is no way to deliver such a response immediately; state, there is no way to deliver such a response immediately;
instead, it is delivered on the next block transfer. Still, HTTP 408 instead, it is delivered on the next block transfer. Still, HTTP 408
is probably the best mapping back to HTTP, as the timeout is the most is probably the best mapping back to HTTP, as the timeout is the most
likely cause for a CoAP 4.08. Note that there is no way to likely cause for a CoAP 4.08. Note that there is no way to
distinguish a timeout from a missing block for a server without distinguish a timeout from a missing block for a server without
creating additional state, the need for which we want to avoid.) creating additional state, the need for which we want to avoid.)
5. 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 |
+--------+--------+-----------+ +--------+--------+-----------+
| 17 | Block2 | [RFCXXXX] | | 17 | Block2 | [RFCXXXX] |
| | | | | | | |
| 19 | Block1 | [RFCXXXX] | | 18 | Size | [RFCXXXX] |
| | | |
| 19 | Block1 | [RFCXXXX] |
+--------+--------+-----------+ +--------+--------+-----------+
Table 2: CoAP Option Numbers Table 2: 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 3: CoAP Response Codes
6. 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
transferred by CoAP implement the Block options to gain access to transferred by CoAP implement the Block options to gain access to
entire resource representations. Still, approaches such as entire resource representations. Still, approaches such as
skipping to change at page 23, line 33 skipping to change at page 25, line 33
Where access to a resource is only granted to clients making use of a Where access to a resource is only granted to clients making use of a
specific security association, all blocks of that resource MUST be specific security association, all blocks of that resource MUST be
subject to the same security checks; it MUST NOT be possible for subject to the same security checks; it MUST NOT be possible for
unprotected exchanges to influence blocks of an otherwise protected unprotected exchanges to influence blocks of an otherwise protected
resource. As a related consideration, where object security is resource. As a related consideration, where object security is
employed, PUT/POST should be implemented in the atomic fashion, employed, PUT/POST should be implemented in the atomic fashion,
unless the object security operation is performed on each access and unless the object security operation is performed on each access and
the creation of unusable resources can be tolerated. the creation of unusable resources can be tolerated.
6.1. Mitigating Resource Exhaustion Attacks Misleading size indications may be used by an attacker to induce
buffer overflows in poor implementations, for which the usual
considerations apply.
7.1. Mitigating Resource Exhaustion Attacks
Certain blockwise requests may induce the server to create state, Certain blockwise requests may induce the server to create state,
e.g. to create a snapshot for the blockwise GET of a fast-changing e.g. to create a snapshot for the blockwise GET of a fast-changing
resource to enable consistent access to the same version of a resource to enable consistent access to the same version of a
resource for all blocks, or to create temporary resource resource for all blocks, or to create temporary resource
representations that are collected until pressed into service by a representations that are collected until pressed into service by a
final PUT or POST with the more bit unset. All mechanisms that final PUT or POST with the more bit unset. All mechanisms that
induce a server to create state that cannot simply be cleaned up induce a server to create state that cannot simply be cleaned up
create opportunities for denial-of-service attacks. Servers SHOULD create opportunities for denial-of-service attacks. Servers SHOULD
avoid being subject to resource exhaustion based on state created by avoid being subject to resource exhaustion based on state created by
skipping to change at page 24, line 13 skipping to change at page 26, line 17
fragmentation, adaptation layer fragmentation), e.g. because there is fragmentation, adaptation layer fragmentation), e.g. because there is
application layer semantics that can be used for mitigation or application layer semantics that can be used for mitigation or
because lower layers provide security associations that can prevent because lower layers provide security associations that can prevent
attacks. However, it is less common to apply timeouts and keepalive attacks. However, it is less common to apply timeouts and keepalive
mechanisms at the application layer than at lower layers. Servers mechanisms at the application layer than at lower layers. Servers
MAY want to clean up accumulated state by timing it out (cf. response MAY want to clean up accumulated state by timing it out (cf. response
code 4.08), and clients SHOULD be prepared to run blockwise transfers code 4.08), and clients SHOULD be prepared to run blockwise transfers
in an expedient way to minimize the likelihood of running into such a in an expedient way to minimize the likelihood of running into such a
timeout. timeout.
6.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
block) instead of a 1016-byte response, considerably reducing the block) instead of a 1016-byte response, considerably reducing the
amplification provided. amplification provided.
7. 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 [I-D.ietf-core-coap] authors, and via many CoRE WG discussions.
Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. Tokens were suggested by Gilman Tolle and refined by Klaus Hartke.
Charles Palmer provided extensive editorial comments to a previous Charles Palmer provided extensive editorial comments to a previous
version of this draft, some of which the authors hope to have covered version of this draft, some of which the authors hope to have covered
in this version. 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. to a number of further editorial improvements.
8. References Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of
the Size Option, which has informed this draft.
8.1. Normative References 9. References
9.1. Normative References
[I-D.ietf-core-coap] [I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank, Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)", "Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-08 (work in progress), October 2011. draft-ietf-core-coap-08 (work in progress), October 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
8.2. Informative References 9.2. Informative References
[I-D.ietf-core-link-format]
Shelby, Z., "CoRE Link Format",
draft-ietf-core-link-format-11 (work in progress),
January 2012.
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
[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", Overview, Assumptions, Problem Statement, and Goals",
RFC 4919, August 2007. RFC 4919, August 2007.
Appendix A. Historical Note Appendix A. Historical Note
 End of changes. 17 change blocks. 
30 lines changed or deleted 104 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/