draft-ietf-core-block-13.txt		draft-ietf-core-block-14.txt
	CoRE Working Group C. Bormann		CoRE Working Group C. Bormann
	Internet-Draft Universitaet Bremen TZI		Internet-Draft Universitaet Bremen TZI
	Intended status: Standards Track Z. Shelby, Ed.		Intended status: Standards Track Z. Shelby, Ed.
	Expires: April 23, 2014 Sensinode		Expires: April 24, 2014 Sensinode
	October 20, 2013		October 21, 2013
	Blockwise transfers in CoAP		Blockwise transfers in CoAP
	draft-ietf-core-block-13		draft-ietf-core-block-14
	Abstract		Abstract
	CoAP is a RESTful transfer protocol for constrained nodes and		CoAP is a RESTful transfer protocol for constrained nodes and
	networks. Basic CoAP messages work well for the small payloads we		networks. Basic CoAP messages work well for the small payloads we
	expect from temperature sensors, light switches, and similar		expect from temperature sensors, light switches, and similar
	building-automation devices. Occasionally, however, applications		building-automation devices. Occasionally, however, applications
	will need to transfer larger payloads -- for instance, for		will need to transfer larger payloads -- for instance, for
	firmware updates. With HTTP, TCP does the grunt work of slicing		firmware updates. With HTTP, TCP does the grunt work of slicing
	large payloads up into multiple packets and ensuring that they all		large payloads up into multiple packets and ensuring that they all
	skipping to change at page 2, line 10		skipping to change at page 2, line 10
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at http://datatracker.ietf.org/drafts/current/.		Drafts is at http://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on April 23, 2014.		This Internet-Draft will expire on April 24, 2014.
	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 . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4		2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4
	2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 5		2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5
	2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6		2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6
	2.3. Block Options in Requests and Responses . . . . . . . . . 8		2.3. Block Options in Requests and Responses . . . . . . . . . 8
	2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 9		2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10
	2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11		2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11
	2.6. Combining Blockwise Transfers with the Observe Option . . 12		2.6. Combining Blockwise Transfers with the Observe Option . . 12
	2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13		2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13
	2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13		2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13
	3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 13		2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14
	3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 14		2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14
	3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 16		2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14
	3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 18		2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14
	3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 19		3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14
	4. The Size Options . . . . . . . . . . . . . . . . . . . . . . 22		3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15
	5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 23		3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24		3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 25		3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 21
	7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 26		4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 24
	7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 26		5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 25
	8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27		7. Security Considerations . . . . . . . . . . . . . . . . . . . 28
	9.1. Normative References . . . . . . . . . . . . . . . . . . 27		7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 28
	9.2. Informative References . . . . . . . . . . . . . . . . . 28		7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28		8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29
			9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
			9.1. Normative References . . . . . . . . . . . . . . . . . . 30
			9.2. Informative References . . . . . . . . . . . . . . . . . 30
			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 5, line 33		skipping to change at page 5, line 37
	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
	a small range of power-of-two block sizes, from 2**4 (16) to 2**10		a small range of power-of-two block sizes, from 2**4 (16) to 2**10
	(1024) bytes. As bodies often will not evenly divide into the power-		(1024) bytes. As bodies often will not evenly divide into the power-
	of-two block size chosen, the size need not be reached in the final		of-two block size chosen, the size need not be reached in the final
	block (but even for the final block, the chosen power-of-two size		block (but even for the final block, the chosen power-of-two size
	will still be indicated in the block size field of the Block option).		will still be indicated in the block size field of the Block option).
	2.1. The Block Options		2.1. The Block2 and Block1 Options
	+------+---+---+---+---+--------+--------+--------+---------+		+------+---+---+---+---+--------+--------+--------+---------+
	| Type | C | U | N | R | Name | Format | Length | Default |		| Type | C | U | N | R | Name | Format | Length | Default |
	+------+---+---+---+---+--------+--------+--------+---------+		+------+---+---+---+---+--------+--------+--------+---------+
	| 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) |		| 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) |
	| | | | | | | | | |		| | | | | | | | | |
	| 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) |		| 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) |
	+------+---+---+---+---+--------+--------+--------+---------+		+------+---+---+---+---+--------+--------+--------+---------+
	Table 1: Block Option Numbers		Table 1: Block Option Numbers
	skipping to change at page 11, line 40		skipping to change at page 12, line 6
	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. In this case, all success responses to non-final blocks		is received. In this case, all success responses to non-final blocks
	carry the response code 2.31 (Continue). If not all previous blocks		carry the response code 2.31 (Continue, Section 2.9.1). If not all
	are available at the server at the time of processing the final		previous blocks are available at the server at the time of processing
	block, the transfer fails and error code 4.08 (Request Entity		the final block, the transfer fails and error code 4.08 (Request
	Incomplete) MUST be returned. A server MAY also return a 4.08 error		Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY
	code for any (final or non-final) Block1 transfer that is not in		also return a 4.08 error code for any (final or non-final) Block1
	sequence; clients that do not have specific mechanisms to handle this		transfer that is not in sequence; clients that do not have specific
	case therefore SHOULD always start with block zero and send the		mechanisms to handle this case therefore SHOULD always start with
	following blocks in order.		block zero and send the following blocks in order.
	The error code 4.13 (Request Entity Too Large) can be returned at any		The error code 4.13 (Request Entity Too Large) can be returned at any
	time by a server that does not currently have the resources to store		time by a server that does not currently have the resources to store
	blocks for a block-wise request payload transfer that it would intend		blocks for a block-wise request payload transfer that it would intend
	to implement in an atomic fashion. (Note that a 4.13 response to a		to implement in an atomic fashion. (Note that a 4.13 response to a
	request that does not employ Block1 is a hint for the client to try		request that does not employ Block1 is a hint for the client to try
	sending Block1, and a 4.13 response with a smaller SZX in its Block1		sending Block1, and a 4.13 response with a smaller SZX in its Block1
	option than requested is a hint to try a smaller SZX.)		option than requested is a hint to try a smaller SZX.)
	The Block1 option provides no way for a single endpoint to perform		The Block1 option provides no way for a single endpoint to perform
	skipping to change at page 13, line 16		skipping to change at page 13, line 30
	2.7. Combining Block1 and Block2		2.7. Combining Block1 and Block2
	In PUT and particularly in POST exchanges, both the request body and		In PUT and particularly in POST exchanges, both the request body and
	the response body may be large enough to require the use of block-		the response body may be large enough to require the use of block-
	wise transfers. First, the Block1 transfer of the request body		wise transfers. First, the Block1 transfer of the request body
	proceeds as usual. In the exchange of the last slice of this block-		proceeds as usual. In the exchange of the last slice of this block-
	wise transfer, the response carries the first slice of the Block2		wise transfer, the response carries the first slice of the Block2
	transfer (NUM is zero). To continue this Block2 transfer, the client		transfer (NUM is zero). To continue this Block2 transfer, the client
	continues to send requests similar to the requests in the Block1		continues to send requests similar to the requests in the Block1
	phase, bute leaves out the Block1 options and includes a Block2		phase, but leaves out the Block1 options and includes a Block2
	request option with non-zero NUM.		request option with non-zero NUM.
	Block2 transfers that retrieve the response body for a request that		Block2 transfers that retrieve the response body for a request that
	used Block1 MUST be performed in sequential order.		used Block1 MUST be performed in sequential order.
	2.8. Combining Block2 with Multicast		2.8. Combining Block2 with Multicast
	A client can use the Block2 option in a multicast GET request with		A client can use the Block2 option in a multicast GET request with
	NUM = 0 to aid in limiting the size of the response.		NUM = 0 to aid in limiting the size of the response.
	skipping to change at page 13, line 39		skipping to change at page 14, line 5
	limit the size of the response.		limit the size of the response.
	In both cases, the client retrieves any further blocks using unicast		In both cases, the client retrieves any further blocks using unicast
	exchanges; in the unicast requests, the client SHOULD heed any block		exchanges; in the unicast requests, the client SHOULD heed any block
	size preferences indicated by the server in the response to the		size preferences indicated by the server in the response to the
	multicast request.		multicast request.
	Other uses of the Block options in conjunction with multicast		Other uses of the Block options in conjunction with multicast
	messages are for further study.		messages are for further study.
	3. Examples		2.9. Response Codes
			Two response codes are defined by this specification beyond those
			already defined in [I-D.ietf-core-coap], and another response code is
			extended in its meaning.
			TODO: Add or appropriate useful response codes for Block2 problems
			(overshoot beyond end of representation, unsupported out-of-order
			access).
			2.9.1. 2.31 Continue
			This new success status code indicates that the transfer of this
			block of the request body was successful and that the serve
			encourages sending further blocks, but that a final outcome of the
			whole block-wise request cannot yet be determined. No payload is
			returned with this response code.
			2.9.2. 4.08 Request Entity Incomplete
			This new client error status code indicates that the server has not
			received the blocks of the request body that it needs to proceed.
			The client has not sent all blocks, not sent them in the order
			required by the server, or has sent them long enough ago that the
			server has already discarded them.
			2.9.3. 4.13 Request Entity Too Large
			In [I-D.ietf-core-coap], section 5.9.2.9, the response code 4.13
			(Request Entity Too Large) is defined to be like HTTP 413 "Request
			Entity Too Large". [I-D.ietf-core-coap] also recommends that this
			response SHOULD include a Size1 Option Section 4 to indicate the
			maximum size of request entity the server is able and willing to
			handle, unless the server is not in a position to make this
			information available.
			The present specification allows the server to return this response
			code at any time during a Block1 transfer to indicate that it does
			not currently have the resources to store blocks for a transfer that
			it would intend to implement in an atomic fashion. It also allows
			the server to return a 4.13 response to a request that does not
			employ Block1 as a hint for the client to try sending Block1.
			Finally, a 4.13 response to a request with a Block1 option (control
			usage, see Section 2.3) where the response carries a smaller SZX in
			its Block1 option is a hint to try that smaller SZX.
			3. Examples
	This section gives a number of short examples with message flows for		This section gives a number of short examples with message flows for
	a block-wise GET, and for a PUT or POST. These examples demonstrate		a block-wise GET, and for a PUT or POST. These examples demonstrate
	the basic operation, the operation in the presence of		the basic operation, the operation in the presence of
	retransmissions, and examples for the operation of the block size		retransmissions, and examples for the operation of the block size
	negotiation.		negotiation.
	In all these examples, a Block option is shown in a decomposed way		In all these examples, a Block option is shown in a decomposed way
	indicating the kind of Block option (1 or 2) followed by a colon, and		indicating the kind of Block option (1 or 2) followed by a colon, and
	then the block number (NUM), more bit (M), and block size exponent		then the block number (NUM), more bit (M), and block size exponent
	(2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33		(2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33
	skipping to change at page 22, line 21		skipping to change at page 24, line 28
	| | Block2: 4/0/64		| | Block2: 4/0/64
	| |		| |
	|<-----+ Header: 2.05 0x61451638		|<-----+ Header: 2.05 0x61451638
	| 2.05 | Token: 0xfc		| 2.05 | Token: 0xfc
	| | Block2: 4/0/64		| | Block2: 4/0/64
	| | ETag: 6f00f392		| | ETag: 6f00f392
	| | Payload: [53 bytes]		| | Payload: [53 bytes]
	Figure 13: Observe sequence with early negotiation		Figure 13: Observe sequence with early negotiation
	4. The Size Options		4. The Size2 and Size1 Options
	In many cases when transferring a large resource representation block		In many cases when transferring a large resource representation block
	by block, it is advantageous to know the total size early in the		by block, it is advantageous to know the total size early in the
	process. Some indication may be available from the maximum size		process. Some indication may be available from the maximum size
	estimate attribute "sz" provided in a resource description [RFC6690].		estimate attribute "sz" provided in a resource description [RFC6690].
	However, the size may vary dynamically, so a more up-to-date		However, the size may vary dynamically, so a more up-to-date
	indication may be useful.		indication may be useful.
	This specification defines two CoAP Options, Size1 for indicating the		This specification defines two CoAP Options, Size1 for indicating the
	size of the representation transferred in requests, and Size2 for		size of the representation transferred in requests, and Size2 for
	skipping to change at page 27, line 26		skipping to change at page 29, line 45
	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.
	Charles Palmer provided extensive editorial comments to a previous		Charles Palmer provided extensive editorial comments to a previous
	version of this draft, some of which the authors hope to have covered		version of this draft, some of which the authors hope to have covered
	in this version. Esko Dijk reviewed a more recent version, leading		in this version. Esko Dijk reviewed a more recent version, leading
	to a number of further editorial improvements, a solution to the 4.13		to a number of further editorial improvements, a solution to the 4.13
	ambiguity problem, and the section about combining Block and		ambiguity problem, and the section about combining Block and
	multicast. Markus Becker proposed getting rid of an ill-conceived		multicast. Markus Becker proposed getting rid of an ill-conceived
	default value for the Block2 and Block1 options.		default value for the Block2 and Block1 options. Peter Bigot
			insisted on a more systematic coverage of the options and response
			code.
	Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of		Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of
	the Size Option, which has informed this draft. Klaus Hartke wrote		the Size Option, which has informed this draft. Klaus Hartke wrote
	some of the text describing the interaction of Block2 with Observe.		some of the text describing the interaction of Block2 with Observe.
	Matthias Kovatsch provided a number of significant simplifications of		Matthias Kovatsch provided a number of significant simplifications of
	the protocol.		the protocol.
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	[I-D.ietf-core-coap]		[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-18		Application Protocol (CoAP)", draft-ietf-core-coap-18
End of changes. 14 change blocks.
	35 lines changed or deleted		87 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/