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/