draft-ietf-core-block-08.txt		draft-ietf-core-block-09.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: August 18, 2012 Sensinode		Expires: February 15, 2013 Sensinode
	February 15, 2012		August 14, 2012
	Blockwise transfers in CoAP		Blockwise transfers in CoAP
	draft-ietf-core-block-08		draft-ietf-core-block-09
	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 August 18, 2012.		This Internet-Draft will expire on February 15, 2013.
	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 10		skipping to change at page 3, line 10
	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 . . . . . . . . . . . . . . . . . . . . . . . . . 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. Structure of a Block Option . . . . . . . . . . . . . . . 7
	3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13		2.3. Block Options in Requests and Responses . . . . . . . . . 9
			2.4. Using the Block Options . . . . . . . . . . . . . . . . . 10
			3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
	4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20		4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20
	5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22		5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 25		7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
	7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25		7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25
	7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26		7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26
	8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27		8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28		9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	9.1. Normative References . . . . . . . . . . . . . . . . . . . 28		9.1. Normative References . . . . . . . . . . . . . . . . . . . 28
	9.2. Informative References . . . . . . . . . . . . . . . . . . 28		9.2. Informative References . . . . . . . . . . . . . . . . . . 28
	skipping to change at page 4, line 41		skipping to change at page 4, line 41
	addition, not all resource representations will fit into a single		addition, not all resource representations will fit into a single
	link layer packet of a constrained network, which may cause		link layer packet of a constrained network, which may cause
	adaptation layer fragmentation even if IP layer fragmentation is not		adaptation layer fragmentation even if IP layer fragmentation is not
	required. Using fragmentation (either at the adaptation layer or at		required. Using fragmentation (either at the adaptation layer or at
	the IP layer) to enable the transport of larger representations is		the IP layer) to enable the transport of larger representations is
	possible up to the maximum size of the underlying datagram protocol		possible up to the maximum size of the underlying datagram protocol
	(such as UDP), but the fragmentation/reassembly process burdens the		(such as UDP), but the fragmentation/reassembly process burdens the
	lower layers with conversation state that is better managed in the		lower layers with conversation state that is better managed in the
	application layer.		application layer.
	This specification defines a pair of CoAP options to enable _block-		The present specification defines a pair of CoAP options to enable
	wise_ access to resource representations. The Block options provide		_block-wise_ access to resource representations. The Block options
	a minimal way to transfer larger resource representations in a block-		provide a minimal way to transfer larger resource representations in
	wise fashion. The overriding objective is to avoid creating		a block-wise fashion. The overriding objective is to avoid the need
	conversation state at the server for block-wise GET requests. (It is		for creating conversation state at the server for block-wise GET
	impossible to fully avoid creating conversation state for POST/PUT,		requests. (It is impossible to fully avoid creating conversation
	if the creation/replacement of resources is to be atomic; where that		state for POST/PUT, if the creation/replacement of resources is to be
	property is not needed, there is no need to create server		atomic; where that property is not needed, there is no need to create
	conversation state in this case, either.)		server conversation state in this case, either.)
	In summary, this specification adds a pair of Block options to CoAP		In summary, this specification adds a pair of Block options to CoAP
	that can be used for block-wise transfers. Benefits of using these		that can be used for block-wise transfers. Benefits of using these
	options include:		options include:
	o Transfers larger than can be accommodated in constrained-network		o Transfers larger than what can be accommodated in constrained-
	link-layer packets can be performed in smaller blocks.		network link-layer packets can be performed in smaller blocks.
	o No hard-to-manage conversation state is created at the adaptation		o No hard-to-manage conversation state is created at the adaptation
	layer or IP layer for fragmentation.		layer or IP layer for fragmentation.
	o The transfer of each block is acknowledged, enabling		o The transfer of each block is acknowledged, enabling
	retransmission if required.		retransmission if required.
	o Both sides have a say in the block size that actually will be		o Both sides have a say in the block size that actually will be
	used.		used.
	o The resulting exchanges are easy to understand using packet		o The resulting exchanges are easy to understand using packet
	analyzer tools and thus quite accessible to debugging.		analyzer tools and thus quite accessible to debugging.
	o If needed, the Block options can also be used as is to provide		o If needed, the Block options can also be used (without changes) to
	random access to power-of-two sized blocks within a resource		provide random access to power-of-two sized blocks within a
	representation.		resource representation.
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	document are to be interpreted as described in RFC 2119, BCP 14		document are to be interpreted as described in RFC 2119, BCP 14
	[RFC2119] and indicate requirement levels for compliant CoAP		[RFC2119] and indicate requirement levels for compliant CoAP
	implementations.		implementations.
	In this document, the term "byte" is used in its now customary sense		In this document, the term "byte" is used in its now customary sense
	as a synonym for "octet".		as a synonym for "octet".
	skipping to change at page 7, line 30		skipping to change at page 7, line 30
	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.
	However, when it is present in a CoAP message, it MUST be processed		However, when it is present in a CoAP message, it MUST be processed
	(or the message rejected); therefore it is identified as a critical		(or the message rejected); therefore it is identified as a critical
	option. It MUST NOT occur more than once.		option. It MUST NOT occur more than once.
			2.2. Structure of a Block Option
	Three items of information may need to be transferred in a Block		Three items of information may need to be transferred in a Block
	option:		option:
	o The size of the block (SZX);		o The size of the block (SZX);
	o whether more blocks are following (M);		o whether more blocks are following (M);
	o the relative number of the block (NUM) within a sequence of blocks		o the relative number of the block (NUM) within a sequence of blocks
	with the given size.		with the given size.
	skipping to change at page 8, line 38		skipping to change at page 8, line 38
	three least significant bits of the option value (i.e., "val & 7"		three least significant bits of the option value (i.e., "val & 7"
	where "val" is the value of the option).		where "val" is the value of the option).
	The fourth least significant bit, the M or "more" bit ("val & 8"),		The fourth least significant bit, the M or "more" bit ("val & 8"),
	indicates whether more blocks are following or the current block-wise		indicates whether more blocks are following or the current block-wise
	transfer is the last block being transferred.		transfer is the last block being transferred.
	The option value divided by sixteen (the NUM field) is the sequence		The option value divided by sixteen (the NUM field) is the sequence
	number of the block currently being transferred, starting from zero.		number of the block currently being transferred, starting from zero.
	The current transfer is therefore about the "size" bytes starting at		The current transfer is therefore about the "size" bytes starting at
	byte "NUM << (SZX + 4)". (Note that, as an implementation		byte "NUM << (SZX + 4)".
	convenience, "(val & ~0xF) << (val & 7)", i.e. the option value with
	the last 4 bits masked out, shifted to the left by the value of SZX,		Implementation note: As an implementation convenience, "(val & ~0xF)
	gives the byte position of the block.)		<< (val & 7)", i.e. the option value with the last 4 bits masked
			out, shifted to the left by the value of SZX, gives the byte
			position of the block being transferred.
	The default value of both the Block1 and the Block2 Option is zero,		The default value of both the Block1 and the Block2 Option is zero,
	indicating that the current block is the first and only block of the		indicating that the current block is the first and only block of the
	transfer (block number 0, M bit not set); however, there is no		transfer (block number 0, M bit not set); however, there is no
	explicit size implied by this default value.		explicit size implied by this default value.
	More specifically, within the option value of a Block1 or Block2		More specifically, within the option value of a Block1 or Block2
	Option, the meaning of the option fields is defined as follows:		Option, the meaning of the option fields is defined as follows:
	NUM: Block Number. The block number is a variable-size (4, 12, or		NUM: Block Number. The block number is a variable-size (4, 12, or
	skipping to change at page 9, line 28		skipping to change at page 9, line 28
	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		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		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 and MUST		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 in a		lead to a 4.00 Bad Request response code upon reception in a
	request.		request.
			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 (e.g., a		o In descriptive usage, i.e. a Block2 Option in a response (e.g., a
	2.05 response for GET), or a Block1 Option in a request (e.g., PUT		2.05 response for GET), or a Block1 Option in a request (e.g., PUT
	or POST):		or POST):
	* The NUM field in the option value describes what block number		* The NUM field in the option value describes what block number
	is contained in the payload of this message.		is contained in the payload of this message.
	* The M bit indicates whether further blocks are required to		* The M bit indicates whether further blocks are required to
	skipping to change at page 10, line 44		skipping to change at page 10, line 48
	* Finally, the SZX block size given in a control Block1 Option		* Finally, the SZX block size given in a control Block1 Option
	indicates the largest block size preferred by the server for		indicates the largest block size preferred by the server for
	transfers toward the resource that is the same or smaller than		transfers toward the resource that is the same or smaller than
	the one used in the initial exchange; the client SHOULD use		the one used in the initial exchange; the client SHOULD use
	this block size or a smaller one in all further requests in the		this block size or a smaller one in all further requests in the
	transfer sequence, even if that means changing the block size		transfer sequence, even if that means changing the block size
	(and possibly scaling the block number accordingly) from now		(and possibly scaling the block number accordingly) from now
	on.		on.
	2.2. Using the Block Options		2.4. Using the Block Options
	Using one or both Block options, a single REST operation can be split		Using one or both Block options, a single REST operation can be split
	into multiple CoAP message exchanges. As specified in		into multiple CoAP message exchanges. As specified in
	[I-D.ietf-core-coap], each of these message exchanges uses their own		[I-D.ietf-core-coap], each of these message exchanges uses their own
	CoAP Message ID.		CoAP Message ID.
	When a request is answered with a response carrying a Block2 Option		When a request is answered with a response carrying a Block2 Option
	with the M bit set, the requester may retrieve additional blocks of		with the M bit set, the requester may retrieve additional blocks of
	the resource representation by sending further requests with the same		the resource representation by sending further requests with the same
	options and a Block2 Option giving the block number and block size		options and a Block2 Option giving the block number and block size
	skipping to change at page 11, line 17		skipping to change at page 11, line 21
	Option to zero and the server MUST ignore it on reception.		Option to zero and the server MUST ignore it on reception.
	To influence the block size used in a response, the requester also		To influence the block size used in a response, the requester also
	uses the Block2 Option, giving the desired size, a block number of		uses the Block2 Option, giving the desired size, a block number of
	zero and an M bit of zero. A server MUST use the block size		zero and an M bit of zero. A server MUST use the block size
	indicated or a smaller size. Any further block-wise requests for		indicated or a smaller size. Any further block-wise requests for
	blocks beyond the first one MUST indicate the same block size that		blocks beyond the first one MUST indicate the same block size that
	was used by the server in the response for the first request that		was used by the server in the response for the first request that
	gave a desired size using a Block2 Option.		gave a desired size using a Block2 Option.
	Once the Block2 Option is used by the requester, all requests in a		Once the Block2 Option is used by the requester and a first response
	single block-wise transfer MUST ultimately use the same size, except		has been received with a possibly adjusted block size, all further
	that there may not be enough content to fill the last block (the one		requests in a single block-wise transfer SHOULD ultimately use the
	returned with the M bit not set). (Note that the client may start		same size, except that there may not be enough content to fill the
	using the Block2 Option in a second request after a first request		last block (the one returned with the M bit not set). (Note that the
	without a Block2 Option resulted in a Block option in the response.)		client may start using the Block2 Option in a second request after a
	The server SHOULD use the block size indicated in the request option		first request without a Block2 Option resulted in a Block option in
	or a smaller size, but the requester MUST take note of the actual		the response.) The server SHOULD use the block size indicated in the
	block size used in the response it receives to its initial request		request option or a smaller size, but the requester MUST take note of
	and proceed to use it in subsequent requests. The server behavior		the actual block size used in the response it receives to its initial
	MUST ensure that this client behavior results in the same block size		request and proceed to use it in subsequent requests. The server
	for all responses in a sequence (except for the last one with the M		behavior MUST ensure that this client behavior results in the same
	bit not set, and possibly the first one if the initial request did		block size for all responses in a sequence (except for the last one
	not contain a Block2 Option).		with the M bit not set, and possibly the first one if the initial
			request did not contain a Block2 Option).
	Block-wise transfers can be used to GET resources the representations		Block-wise transfers can be used to GET resources the representations
	of which are entirely static (not changing over time at all, such as		of which are entirely static (not changing over time at all, such as
	in a schema describing a device), or for dynamically changing		in a schema describing a device), or for dynamically changing
	resources. In the latter case, the Block2 Option SHOULD be used in		resources. In the latter case, the Block2 Option SHOULD be used in
	conjunction with the ETag Option, to ensure that the blocks being		conjunction with the ETag Option, to ensure that the blocks being
	reassembled are from the same version of the representation: The		reassembled are from the same version of the representation: The
	server SHOULD include an ETag option in each response. If an ETag		server SHOULD include an ETag option in each response. If an ETag
	option is available, the client's reassembler, when reassembling the		option is available, the client's reassembler, when reassembling the
	representation from the blocks being exchanged, MUST compare ETag		representation from the blocks being exchanged, MUST compare ETag
	Options. If the ETag Options do not match in a GET transfer, the		Options. If the ETag Options do not match in a GET transfer, the
	requester has the option of attempting to retrieve fresh values for		requester has the option of attempting to retrieve fresh values for
	the blocks it retrieved first. To minimize the resulting		the blocks it retrieved first. To minimize the resulting
	inefficiency, the server MAY cache the current value of a		inefficiency, the server MAY cache the current value of a
	representation for an ongoing sequence of requests. The client MAY		representation for an ongoing sequence of requests. (The server may
	facilitate identifying the sequence by using the Token Option with a		identify the sequence by the combination of the requesting end-point
	non-default value. Note well that this specification makes no		and the URI being the same in each block-wise request.) Note well
	requirement for the server to establish any state; however, servers		that this specification makes no requirement for the server to
	that offer quickly changing resources may thereby make it impossible		establish any state; however, servers that offer quickly changing
	for a client to ever retrieve a consistent set of blocks.		resources may thereby make it impossible for a client to ever
			retrieve a consistent set of blocks.
	In a request with a request payload (e.g., PUT or POST), the Block1		In a request with a request payload (e.g., PUT or POST), the Block1
	Option refers to the payload in the request (descriptive usage).		Option refers to the payload in the request (descriptive usage).
	In response to a request with a payload (e.g., a PUT or POST		In response to a request with a payload (e.g., a PUT or POST
	transfer), the block size given in the Block1 Option indicates the		transfer), the block size given in the Block1 Option indicates the
	block size preference of the server for this resource (control		block size preference of the server for this resource (control
	usage). Obviously, at this point the first block has already been		usage). Obviously, at this point the first block has already been
	transferred by the client without benefit of this knowledge. Still,		transferred by the client without benefit of this knowledge. Still,
	the client SHOULD heed the preference and, for all further blocks,		the client SHOULD heed the preference and, for all further blocks,
	skipping to change at page 12, line 44		skipping to change at page 12, line 49
	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 the Block1 than requested is a		4.13 response with a smaller SZX in the Block1 than requested is a
	hint to try a smaller SZX.)		hint to try a smaller SZX.)
	If multiple concurrently proceeding block-wise request payload		Note that there is no way to perform multiple concurrently proceeding
	transfer (e.g., PUT or POST) operations are possible, the requester		block-wise request payload transfer (e.g., PUT or POST) operations to
	SHOULD use the Token Option to clearly separate the different		the same URI. Starting a new block-wise sequence of requests to the
	sequences. In this case, when reassembling the representation from		same URI (before an old sequence from the same endpoint was finished)
	the blocks being exchanged to enable atomic processing, the		simply overwrites the context the server may still be keeping. (This
	reassembler MUST compare any Token Options present (and, as usual,		is probably exactly what one wants in this case - the client may
	taking an absent Token Option to default to the empty Token). If		simply have restarted and lost its knowledge of the previous
	atomic processing is not desired, there is no need to process the		sequence.)
	Token Option (but it is still returned in the response as usual).
	3. Examples		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
	skipping to change at page 13, line 42		skipping to change at page 14, 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 [I-D.ietf-core-link-format]) and sends a size		format description [RFC6690]) and sends a size proposal. All ACK
	proposal. All ACK messages except for the last carry 64 bytes of		messages except for the last carry 64 bytes of payload; the last one
	payload; the last one carries between 1 and 64 bytes.		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 16, line 32		skipping to change at page 17, line 32
	: ... :		: ... :
	: :		: :
	| CON [MID=1238], GET, /status, 2/5/0/64 ------> |		| CON [MID=1238], GET, /status, 2/5/0/64 ------> |
	| |		| |
	| <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 |		| <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 |
	Figure 6: Blockwise GET with late negotiation and lost ACK		Figure 6: Blockwise GET with late negotiation and lost ACK
	The following examples demonstrate a PUT exchange; a POST exchange		The following examples demonstrate a PUT exchange; a POST exchange
	looks the same, with different requirements on atomicity/idempotence.		looks the same, with different requirements on atomicity/idempotence.
	To ensure that the blocks relate to the same version of the resource		Note that, similar to GET, the responses to the requests that have a
	representation carried in the request, the client in Figure 7 sets		more bit in the request Block1 Option are provisional; only the final
	the Token to "v17" in all requests. Note that, similar to GET, the		response tells the client that the PUT succeeded.
	responses to the requests that have a more bit in the request Block1
	Option are provisional; only the final response tells the client that
	the PUT succeeded.
	CLIENT SERVER		CLIENT SERVER
	| |		| |
	| CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> |		| CON [MID=1234], PUT, /options, 1/0/1/128 ------> |
	| |		| |
	| <------ ACK [MID=1234], 2.04 Changed, 1/0/1/128 |		| <------ ACK [MID=1234], 2.04 Changed, 1/0/1/128 |
	| |		| |
	| CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> |		| CON [MID=1235], PUT, /options, 1/1/1/128 ------> |
	| |		| |
	| <------ ACK [MID=1235], 2.04 Changed, 1/1/1/128 |		| <------ ACK [MID=1235], 2.04 Changed, 1/1/1/128 |
	| |		| |
	| CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> |		| CON [MID=1236], PUT, /options, 1/2/0/128 ------> |
	| |		| |
	| <------ 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, v17, 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, v17, 1/1/1/128 ------> |		| CON [MID=1235], PUT, /options, 1/1/1/128 ------> |
	| |		| |
	| <------ ACK [MID=1235], 2.04 Changed, 1/1/0/128 |		| <------ ACK [MID=1235], 2.04 Changed, 1/1/0/128 |
	| |		| |
	| CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> |		| CON [MID=1236], PUT, /options, 1/2/0/128 ------> |
	| |		| |
	| <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 |		| <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 |
	Figure 8: Simple stateless blockwise PUT		Figure 8: Simple stateless blockwise PUT
	Finally, a server receiving a blockwise PUT or POST may want to		Finally, a server receiving a blockwise PUT or POST may want to
	indicate a smaller block size preference (Figure 9). In this case,		indicate a smaller block size preference (Figure 9). In this case,
	the client SHOULD continue with a smaller block size; if it does, it		the client SHOULD continue with a smaller block size; if it does, it
	MUST adjust the block number to properly count in that smaller size.		MUST adjust the block number to properly count in that smaller size.
	CLIENT SERVER		CLIENT SERVER
	| |		| |
	| CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> |		| CON [MID=1234], PUT, /options, 1/0/1/128 ------> |
	| |		| |
	| <------ ACK [MID=1234], 2.04 Changed, 1/0/1/32 |		| <------ ACK [MID=1234], 2.04 Changed, 1/0/1/32 |
	| |		| |
	| CON [MID=1235], PUT, /options, v17, 1/4/1/32 ------> |		| CON [MID=1235], PUT, /options, 1/4/1/32 ------> |
	| |		| |
	| <------ ACK [MID=1235], 2.04 Changed, 1/4/1/32 |		| <------ ACK [MID=1235], 2.04 Changed, 1/4/1/32 |
	| |		| |
	| CON [MID=1236], PUT, /options, v17, 1/5/1/32 ------> |		| CON [MID=1236], PUT, /options, 1/5/1/32 ------> |
	| |		| |
	| <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 |		| <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 |
	| |		| |
	| CON [MID=1237], PUT, /options, v17, 1/6/0/32 ------> |		| CON [MID=1237], PUT, /options, 1/6/0/32 ------> |
	| |		| |
	| <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 |		| <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 |
	Figure 9: Simple atomic blockwise PUT with negotiation		Figure 9: Simple atomic blockwise PUT with negotiation
	Block options may be used in both directions of a single exchange.		Block options may be used in both directions of a single exchange.
	The following example demonstrates a blockwise POST request,		The following example demonstrates a blockwise POST request,
	resulting in a separate blockwise response. The client in Figure 10		resulting in a separate blockwise response.
	sets the Token to "37a" in all requests, which is echoed in all
	response CONs in the separate response.
	CLIENT SERVER		CLIENT SERVER
	| |		| |
	| CON [MID=1234], POST, /soap, 37a, 1/0/1/128 ------> |		| CON [MID=1234], POST, /soap, 1/0/1/128 ------> |
	| |		| |
	| <------ ACK [MID=1234], 2.01 Created, 1/0/1/128 |		| <------ ACK [MID=1234], 2.01 Created, 1/0/1/128 |
	| |		| |
	| CON [MID=1235], POST, /soap, 37a, 1/1/1/128 ------> |		| CON [MID=1235], POST, /soap, 1/1/1/128 ------> |
	| |		| |
	| <------ ACK [MID=1235], 2.01 Created, 1/1/1/128 |		| <------ ACK [MID=1235], 2.01 Created, 1/1/1/128 |
	| |		| |
	| CON [MID=1236], POST, /soap, 37a, 1/2/0/128 ------> |		| CON [MID=1236], POST, /soap, 1/2/0/128 ------> |
	| |		| |
	| <------ ACK [MID=1236], 0, 1/2/0/128 |		| <------ ACK [MID=1236], 0, 1/2/0/128 |
	| |		| |
	| <------ CON [MID=4712], 2.01 Created, 37a, 2/0/1/128 |		| <------ CON [MID=4712], 2.01 Created, 2/0/1/128 |
	| |		| |
	| ACK [MID=4712], 0, 2/0/1/128 ------> |		| ACK [MID=4712], 0, 2/0/1/128 ------> |
	| |		| |
	| <------ CON [MID=4713], 2.01 Created, 37a, 2/1/1/128 |		| <------ CON [MID=4713], 2.01 Created, 2/1/1/128 |
	| |		| |
	| ACK [MID=4713], 0, 2/1/1/128 ------> |		| ACK [MID=4713], 0, 2/1/1/128 ------> |
	| |		| |
	| <------ CON [MID=4714], 2.01 Created, 37a, 2/2/1/128 |		| <------ CON [MID=4714], 2.01 Created, 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, 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. The Size Option		4. The Size Option
	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		estimate attribute "sz" provided in a resource description [RFC6690].
	[I-D.ietf-core-link-format]. However, the size may vary dynamically,		However, the size may vary dynamically, so a more up-to-date
	so a more up-to-date indication may be useful.		indication may be useful.
	The Size Option may be used for three purposes:		The Size Option may be used for three purposes:
	o in a request, to ask the server to provide a size estimate in the		o in a request, to ask the server to provide a size estimate along
	response ("size request"). For this usage, the value MUST be set		with the usual response ("size request"). For this usage, the
	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.
	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.
			In the latter two cases ("size indication"), the value of the option
			is the current estimate, measured in bytes.
	A size request can be easily distinguished from a size indication, as		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		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		indication of 0 would either be overridden by the actual size of the
	payload for a PUT or POST or would not be useful.		payload for a PUT or POST or would not be useful.
	In the latter two cases ("size indication"), the value of the option		Apart from conveying/asking for size information, the Size option has
	is the current estimate, measured in bytes.		no other effect on the processing of the request or response. If the
			client wants to minimize the size of the payload in the resulting
			response, it should add a Block2 option to the request with a small
			block size (e.g., setting SZX=0).
	The Size Option is "elective", i.e., a client MUST be prepared for		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		the server to ignore the size estimate request. The Size Option MUST
	NOT occur more than once.		NOT occur more than once.
	+------+----------+------+--------+--------+---------+		+------+----------+------+--------+--------+---------+
	| Type | C/E | Name | Format | Length | Default |		| Type | C/E | Name | Format | Length | Default |
	+------+----------+------+--------+--------+---------+		+------+----------+------+--------+--------+---------+
	| 18 | Elective | Size | uint | 0-4 B | (none) |		| 18 | Elective | Size | uint | 0-4 B | (none) |
	+------+----------+------+--------+--------+---------+		+------+----------+------+--------+--------+---------+
	skipping to change at page 25, 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.
			A stateless server might be susceptible to an attack where the
			adversary sends a Block1 (e.g., PUT) block with a high block number:
			A naive implementation might exhaust its resources by creating a huge
			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
	skipping to change at page 27, line 9		skipping to change at page 27, line 9
	an attacker by offering large resource representations only in		an attacker by offering large resource representations only in
	relatively small blocks. With this, e.g., for a 1000 byte resource,		relatively small blocks. With this, e.g., for a 1000 byte resource,
	a 10-byte request might result in an 80-byte response (with a 64-byte		a 10-byte request might result in an 80-byte response (with a 64-byte
	block) instead of a 1016-byte response, considerably reducing the		block) instead of a 1016-byte response, considerably reducing the
	amplification provided.		amplification provided.
	8. Acknowledgements		8. Acknowledgements
	Much of the content of this draft is the result of discussions with		Much of the content of this draft is the result of discussions with
	the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions.		the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions.
	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 as well as a solution
			to the 4.13 ambiguity problem.
	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.		the Size Option, which has informed this draft.
	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., 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-11 (work in progress), July 2012.
	[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
	[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", Ph.D. Dissertation,
			University of California, Irvine, 2000, <http://
			www.ics.uci.edu/~fielding/pubs/dissertation/
			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",		Overview, Assumptions, Problem Statement, and Goals",
	RFC 4919, August 2007.		RFC 4919, August 2007.
			[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
			Format", RFC 6690, August 2012.
	Appendix A. Historical Note		Appendix A. Historical Note
	(This appendix to be deleted by the RFC editor.)		(This appendix to be deleted by the RFC editor.)
	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) |
	skipping to change at page 30, line 14		skipping to change at page 30, line 14
	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
	Fax: +49-421-218-7000
	Email: cabo@tzi.org		Email: cabo@tzi.org
	Zach Shelby (editor)		Zach Shelby (editor)
	Sensinode		Sensinode
	Kidekuja 2		Kidekuja 2
	Vuokatti 88600		Vuokatti 88600
	Finland		Finland
	Phone: +358407796297		Phone: +358407796297
	Email: zach@sensinode.com		Email: zach@sensinode.com
End of changes. 47 change blocks.
	102 lines changed or deleted		116 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/