draft-ietf-core-block-03.txt   draft-ietf-core-block-04.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: November 5, 2011 Sensinode Expires: January 12, 2012 Sensinode
May 3, 2011 July 11, 2011
Blockwise transfers in CoAP Blockwise transfers in CoAP
draft-ietf-core-block-03 draft-ietf-core-block-04
Abstract Abstract
CoAP is a RESTful transfer protocol for constrained nodes and CoAP is a RESTful transfer protocol for constrained nodes and
networks. CoAP is based on datagram transport, which limits the networks. CoAP is based on datagram transport, which limits the
maximum size of resource representations that can be transferred maximum size of resource representations that can be transferred
without too much fragmentation. The Block options provide a minimal without too much fragmentation. The Block options provide a minimal
way to transfer larger representations in a block-wise fashion. way to transfer larger representations in a block-wise fashion.
Status of this Memo Status of this Memo
skipping to change at page 1, line 35 skipping to change at page 1, line 35
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 November 5, 2011. This Internet-Draft will expire on January 12, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 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 2, line 22 skipping to change at page 2, line 22
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. HTTP Mapping Considerations . . . . . . . . . . . . . . . 15 3.1. HTTP Mapping Considerations . . . . . . . . . . . . . . . 15
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18
5.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 18 5.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 18
5.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 19 5.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 19
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.1. Normative References . . . . . . . . . . . . . . . . . . . 21 7.1. Normative References . . . . . . . . . . . . . . . . . . . 21
7.2. Informative References . . . . . . . . . . . . . . . . . . 21 7.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. Backwards Compatibility . . . . . . . . . . . . . . . 22 Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23
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 19 skipping to change at page 5, line 19
+------+----------+--------+--------+--------+---------------+ +------+----------+--------+--------+--------+---------------+
| Type | C/E | Name | Format | Length | Default | | Type | C/E | Name | Format | Length | Default |
+------+----------+--------+--------+--------+---------------+ +------+----------+--------+--------+--------+---------------+
| 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) | | 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) |
| | | | | | | | | | | | | |
| 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) | | 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) |
+------+----------+--------+--------+--------+---------------+ +------+----------+--------+--------+--------+---------------+
Table 1: Block Option Numbers Table 1: Block Option Numbers
The Block1 Option pertains to request payloads, and the Block2 Option The Block1 Option pertains to request payloads (the _first_ part of
pertains to response payloads. (Note that either option can be used the request-response exchange, hence Block1), and the Block2 Option
in both requests and responses, see more below.) pertains to response payloads (the _second_ part of the request-
response exchange). (Note that either option can be used in both
requests and responses, see more below.)
Implementation of either Block option is intended to be optional. Implementation of either Block option is intended to be optional.
However, when it is present in a CoAP message, it MUST be processed However, when it is present in a CoAP message, it MUST be processed
(or the message rejected); therefore it is identified as a critical (or the message rejected); therefore it is identified as a critical
option. option.
The size of the blocks should not be fixed by the protocol. On the The size of the blocks is not fixed by the protocol. To keep the
other hand, implementation should be as simple as possible. The implementation as simple as possible, the Block options support a
Block options therefore support a small range of power-of-two block small range of power-of-two block sizes, from 2^4 (16) to 2^10 (1024)
sizes, from 2^4 (16) to 2^10 (1024) bytes. One of these eight values bytes. One of these seven values can be encoded in three bits (0 for
can be encoded in three bits (0 for 2^4 to 6 for 2^10 bytes), which 2^4 to 6 for 2^10 bytes), which we call the "SZX" (size exponent);
we call the "SZX" (size exponent); the actual block size is then "1 the actual block size is then "1 << (SZX + 4)". (The actual size of
<< (SZX + 4)". (The actual size of the final block in a block-wise the final block in a block-wise transfer may be less than or equal to
transfer may be less than or equal to the power-of-two block size.) the power-of-two block size.)
When a resource representation is larger than can be comfortably When a resource representation is larger than can be comfortably
transferred in a single UDP datagram, a Block option can be used to transferred in a single UDP datagram, a Block option can be used to
indicate a block-wise transfer. The value of the option is a 1-, 2- indicate a block-wise transfer. The value of the option is a 1-, 2-
or 3-byte integer, the four least significant bits of which indicate or 3-byte integer, the four least significant bits of which indicate
the size and whether the current block-wise transfer is the last the size and whether the current block-wise transfer is the last
block being transferred (indicated by the M or "more" bit). The block being transferred (indicated by the M or "more" bit). The
option value divided by sixteen (the NUM field) is the number of the option value divided by sixteen (the NUM field) is the number of the
block currently being transferred, starting from zero. The current block currently being transferred, starting from zero. The current
transfer is therefore about the "size" bytes starting at byte "block transfer is therefore about the "size" bytes starting at byte "block
skipping to change at page 6, line 30 skipping to change at page 6, line 30
| NUM |M| SZX | | NUM |M| SZX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 1: Block option value Figure 1: Block option value
(Note that, as an implementation convenience, the option value with (Note that, as an implementation convenience, the option value with
the last 4 bits masked out, shifted to the left by the value of SZX, the last 4 bits masked out, shifted to the left by the value of SZX,
gives the byte position of the block.) gives the byte position of the block.)
NUM: Block Number. The block number is a variable-size (4, 12, or NUM: Block Number. The block number is a variable-size (4, 12, or
20 bit) unsigned integer indicating the block number being 20 bit) unsigned integer (uint, see Appendix A of
requested or provided. Block number 0 indicates the first block [I-D.ietf-core-coap]) indicating the block number being requested
of a representation. or provided. Block number 0 indicates the first block of a
representation.
M: More Flag. This flag, if unset, indicates that this block is the M: More Flag (not last block). This flag, if unset, indicates that
last in a representation. When set it indicates that there are this block is the last in a representation. When set it indicates
one or more additional blocks available. When a Block2 Option is that there are one or more additional blocks available. When a
used in a request to retrieve a specific block number, the M bit Block2 Option is used in a request to retrieve a specific block
MUST be sent as zero and ignored on reception. (In a Block1 number, the M bit MUST be sent as zero and ignored on reception.
Option in a response, the M flag is used to indicate atomicity, (In a Block1 Option in a response, the M flag is used to indicate
see below.) atomicity, see below.)
SZX: Block Size. The block size is a three-bit unsigned integer SZX: Block Size. The block size is a three-bit unsigned integer
indicating the size of a block to the power of two. Thus block indicating the size of a block to the power of two. Thus block
size = 2^(SZX + 4). The allowed values of SZX are 0 to 6, i.e., size = 2^(SZX + 4). The allowed values of SZX are 0 to 6, i.e.,
the minimum block size is 2^(0+4) = 16 and the maximum is 2^(6+4) the minimum block size is 2^(0+4) = 16 and the maximum is 2^(6+4)
= 1024. The value 7 for SZX (which would indicate a block size of = 1024. The value 7 for SZX (which would indicate a block size of
2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00 2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00
Bad Request response code upon reception in a request. Bad Request response code upon reception in a request.
The Block options are used in one of three roles: The Block options are used in one of three roles:
o In a request (e.g., GET), the Block2 Option gives the block number o In a request (e.g., GET), the Block2 Option gives the block number
requested to be returned in the response and suggests a block size requested to be returned in the response and suggests a block size
(in the case of block number 0) or echoes the block size of (in the case of block number 0) or echoes the block size of
previous blocks received (in the case of block numbers other than previous blocks received (in the case of block numbers other than
0). In thise case, the M bit has no function and MUST be set to 0). In this case, the M bit has no function and MUST be set to
zero. zero.
o A Block2 Option in a response (e.g., for GET), or a Block1 Option o A Block2 Option in a response (e.g., for GET), or a Block1 Option
in a request (e.g., PUT or POST), describes what block number is in a request (e.g., PUT or POST), describes what block number is
contained in the payload of this message, and whether further contained in the payload of this message, and whether further
blocks are required to complete the transfer of that body (M bit). blocks are required to complete the transfer of that body (M bit).
If the M bit is set, the size of the payload body in bytes MUST If the M bit is set, the size of the payload body in bytes MUST
indeed be the power of two given by the block size. With certain indeed be the power of two given by the block size. With certain
exceptions given below, all blocks for a REST transfer MUST use exceptions given below, all blocks for a REST transfer MUST use
the same block size, except for the last block (M bit not set). the same block size, except for the last block (M bit not set).
skipping to change at page 19, line 8 skipping to change at page 19, line 8
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), 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 accreted state by timing it out (cf. response MAY want to clean up accumulated state by timing it out (cf. response
code 4.08), and clients SHOULD be prepared to run blockwise transfers code 4.08), and clients SHOULD be prepared to run blockwise transfers
in an expedient way to minimize the likelihood of running into such a in an expedient way to minimize the likelihood of running into such a
timeout. timeout.
5.2. Mitigating Amplification Attacks 5.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
skipping to change at page 21, line 12 skipping to change at page 21, line 12
version of this draft, some of which the authors hope to have covered version of this draft, some of which the authors hope to have covered
in this version. in this version.
7. References 7. References
7.1. Normative References 7.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-05 (work in progress), March 2011. draft-ietf-core-coap-07 (work in progress), July 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
7.2. Informative References 7.2. Informative References
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
Appendix A. Backwards Compatibility Appendix A. Historical Note
(This section to be removed by RFC editor or on July 1st, 2011.)
An earlier version of this draft used a single option: An earlier version of this draft used a single option:
+------+----------+-------+--------+--------+---------------+ +------+----------+-------+--------+--------+---------------+
| Type | C/E | Name | Format | Length | Default | | Type | C/E | Name | Format | Length | Default |
+------+----------+-------+--------+--------+---------------+ +------+----------+-------+--------+--------+---------------+
| 13 | Critical | Block | uint | 1-3 B | 0 (see below) | | 13 | Critical | Block | uint | 1-3 B | 0 (see below) |
+------+----------+-------+--------+--------+---------------+ +------+----------+-------+--------+--------+---------------+
This option was interpreted as either Block1 or Block2 depending on Note that this option number has since been reallocated in
context: [I-D.ietf-core-coap]; no backwards compatibility is provided after
July 1st, 2011.
o In the request for a GET, the original Block Option was
interpreted as a Block2 Option, i.e. to give the block number
requested and suggest a block size (block number 0) or echo the
block size of previous blocks received (block numbers other than
0).
o In the response for a GET, the original Block Option was
interpreted as a Block2 Option, i.e. to describes what block
number is contained in the response payload, and whether further
blocks are required to complete the transfer of that body (M bit).
o In the request for a PUT or POST, the original Block Option was
interpreted as a Block1 Option, i.e. to describes what block
number is contained in the request payload, and whether further
blocks are required to complete the transfer of that body (M bit).
o In the response for a PUT or POST, the original Block Option was
interpreted as a Block1 Option, i.e. to indicate what block number
is being acknowledged and to indicate whether the response is
final (M bit).
In summary, the semantics was dependent on the method code in a
request, and on the method code of the corresponding request in a
response. This lack of a direction indication also made it
impossible to transfer large PUT/POST responses in a block-wise
manner, because the original Block Option was already "spent" for
block-wise transfer of the request payload.
For interoperability with implementations of the previous draft-
block, implementations may honor original Block Options (option
number 13) until July 1st, 2011, at which time the option number 13
will be available for reallocation.
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
 End of changes. 13 change blocks. 
67 lines changed or deleted 36 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/