draft-ietf-core-dynlink-01.txt		draft-ietf-core-dynlink-02.txt
	CoRE Working Group Z. Shelby		CoRE Working Group Z. Shelby
	Internet-Draft ARM		Internet-Draft ARM
	Intended status: Informational Z. Vial		Intended status: Informational Z. Vial
	Expires: May 1, 2017 Schneider-Electric		Expires: August 28, 2017 Schneider-Electric
	M. Koster		M. Koster
	SmartThings		SmartThings
	C. Groves		C. Groves
	Huawei		Huawei
	October 28, 2016		February 24, 2017
	Dynamic Resource Linking for Constrained RESTful Environments		Dynamic Resource Linking for Constrained RESTful Environments
	draft-ietf-core-dynlink-01		draft-ietf-core-dynlink-02
	Abstract		Abstract
	For CoAP [RFC7252] Dynamic linking of state updates between		For CoAP [RFC7252] Dynamic linking of state updates between
	resources, either on an endpoint or between endpoints, is defined		resources, either on an endpoint or between endpoints, is defined
	with the concept of Link Bindings. This specification defines		with the concept of Link Bindings. This specification defines
	conditional observation attributes that work with Link Bindings or		conditional observation attributes that work with Link Bindings or
	with CoAP Observe [RFC7641].		with CoAP Observe [RFC7641].
	Editor's note:		Editor's note:
	o The git repository for the draft is found at https://github.com/		o The git repository for the draft is found at https://github.com/
	core-wg/dynlink		core-wg/dynlink
	o Examples need to be added.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	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 May 1, 2017.		This Internet-Draft will expire on August 28, 2017.
	Copyright Notice		Copyright Notice
	Copyright (c) 2016 IETF Trust and the persons identified as the		Copyright (c) 2017 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
	skipping to change at page 2, line 29 ¶		skipping to change at page 2, line 29 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
	3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 3		3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 3
	3.1. Binding Methods . . . . . . . . . . . . . . . . . . . . . 4		3.1. Binding Methods . . . . . . . . . . . . . . . . . . . . . 4
	3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5		3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5
	3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5		3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5
	3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 5		3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 5
	3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 5		3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6
	3.3. Binding Attributes . . . . . . . . . . . . . . . . . . . 6		3.3. Binding Attributes . . . . . . . . . . . . . . . . . . . 6
	3.3.1. Bind Method (bind) . . . . . . . . . . . . . . . . . 6		3.3.1. Bind Method (bind) . . . . . . . . . . . . . . . . . 6
	3.3.2. Minimum Period (pmin) . . . . . . . . . . . . . . . . 6		3.3.2. Minimum Period (pmin) . . . . . . . . . . . . . . . . 6
	3.3.3. Maximum Period (pmax) . . . . . . . . . . . . . . . . 6		3.3.3. Maximum Period (pmax) . . . . . . . . . . . . . . . . 7
	3.3.4. Change Step (st) . . . . . . . . . . . . . . . . . . 7		3.3.4. Change Step (st) . . . . . . . . . . . . . . . . . . 7
	3.3.5. Greater Than (gt) . . . . . . . . . . . . . . . . . . 7		3.3.5. Greater Than (gth) . . . . . . . . . . . . . . . . . 7
	3.3.6. Less Than (lt) . . . . . . . . . . . . . . . . . . . 7		3.3.6. Less Than (lth) . . . . . . . . . . . . . . . . . . . 7
	3.3.7. Attribute Interactions . . . . . . . . . . . . . . . 8		3.3.7. Attribute Interactions . . . . . . . . . . . . . . . 8
	4. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 8		4. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 8
	4.1. Binding Interface Description . . . . . . . . . . . . . . 8		4.1. Binding Interface Description . . . . . . . . . . . . . . 8
	4.2. Resource Observation Attributes . . . . . . . . . . . . . 9		4.2. Resource Observation Attributes . . . . . . . . . . . . . 9
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 10		5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
	6.1. Interface Description . . . . . . . . . . . . . . . . . . 11		6.1. Interface Description . . . . . . . . . . . . . . . . . . 11
	6.2. Link Relations Type . . . . . . . . . . . . . . . . . . . 11		6.2. Link Relations Type . . . . . . . . . . . . . . . . . . . 11
	7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12		7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11
	8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12		8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13		9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
	9.1. Normative References . . . . . . . . . . . . . . . . . . 13		9.1. Normative References . . . . . . . . . . . . . . . . . . 13
	9.2. Informative References . . . . . . . . . . . . . . . . . 13		9.2. Informative References . . . . . . . . . . . . . . . . . 13
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 13
			A.1. Greater Than (gth) example . . . . . . . . . . . . . . . 13
			A.2. Greater Than (gth) and Period Max (pmax) example . . . . 14
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
	1. Introduction		1. Introduction
	IETF Standards for machine to machine communication in constrained		IETF Standards for machine to machine communication in constrained
	environments describe a REST protocol and a set of related		environments describe a REST protocol and a set of related
	information standards that may be used to represent machine data and		information standards that may be used to represent machine data and
	machine metadata in REST interfaces. CoRE Link-format is a standard		machine metadata in REST interfaces. CoRE Link-format is a standard
	for doing Web Linking [RFC5988] in constrained environments.		for doing Web Linking [RFC5988] in constrained environments.
	This specification introduces the concept of a Link Binding, which		This specification introduces the concept of a Link Binding, which
	skipping to change at page 6, line 24 ¶		skipping to change at page 6, line 31 ¶
	| Attribute | Parameter | Value |		| Attribute | Parameter | Value |
	+--------------------+-----------+------------------+		+--------------------+-----------+------------------+
	| Binding method | bind | xsd:string |		| Binding method | bind | xsd:string |
	| | | |		| | | |
	| Minimum Period (s) | pmin | xsd:integer (>0) |		| Minimum Period (s) | pmin | xsd:integer (>0) |
	| | | |		| | | |
	| Maximum Period (s) | pmax | xsd:integer (>0) |		| Maximum Period (s) | pmax | xsd:integer (>0) |
	| | | |		| | | |
	| Change Step | st | xsd:decimal (>0) |		| Change Step | st | xsd:decimal (>0) |
	| | | |		| | | |
	| Greater Than | gt | xsd:decimal |		| Greater Than | gth | xsd:decimal |
	| | | |		| | | |
	| Less Than | lt | xsd:decimal |		| Less Than | lth | xsd:decimal |
	+--------------------+-----------+------------------+		+--------------------+-----------+------------------+
	Table 2: Binding Attributes Summary		Table 2: Binding Attributes Summary
	3.3.1. Bind Method (bind)		3.3.1. Bind Method (bind)
	This is the identifier of a binding method which defines the rules to		This is the identifier of a binding method which defines the rules to
	synchronize the destination resource. This attribute is mandatory.		synchronize the destination resource. This attribute is mandatory.
	3.3.2. Minimum Period (pmin)		3.3.2. Minimum Period (pmin)
	skipping to change at page 7, line 26 ¶		skipping to change at page 7, line 34 ¶
	synchronization occurs. STinit is then set to the state		synchronization occurs. STinit is then set to the state
	synchronization value and new state synchronizations are based on a		synchronization value and new state synchronizations are based on a
	change step against this value. The change step MUST be greater than		change step against this value. The change step MUST be greater than
	zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad		zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad
	Request" (or equivalent).		Request" (or equivalent).
	Note: Due to the state synchronization based update of STint it may		Note: Due to the state synchronization based update of STint it may
	result in that resource value received in two sequential state		result in that resource value received in two sequential state
	synchronizations differs by more than st.		synchronizations differs by more than st.
	3.3.5. Greater Than (gt)		3.3.5. Greater Than (gth)
	When present, Greater Than indicates the upper limit value the		When present, Greater Than indicates the upper limit value the
	resource value SHOULD cross before triggering a new state		resource value SHOULD cross before triggering a new state
	synchronization. State synchronization only occurs when the resource		synchronization. State synchronization only occurs when the resource
	value exceeds the specified upper limit value. The actual resource		value exceeds the specified upper limit value. The actual resource
	value is used for the synchronization rather than the gt value. If		value is used for the synchronization rather than the gth value. If
	the value continues to rise, no new state synchronizations are		the value continues to rise, no new state synchronizations are
	generated as a result of gt. If the value drops below the upper		generated as a result of gth. If the value drops below the upper
	limit value and then exceeds the upper limit then a new state		limit value and then exceeds the upper limit then a new state
	synchronization is generated.		synchronization is generated.
	3.3.6. Less Than (lt)		3.3.6. Less Than (lth)
	When present, Less Than indicates the lower limit value the resource		When present, Less Than indicates the lower limit value the resource
	value SHOULD cross before triggering a new state synchronization.		value SHOULD cross before triggering a new state synchronization.
	State synchronization only occurs when the resource value is less		State synchronization only occurs when the resource value is less
	than the specified lower limit value. The actual resource value is		than the specified lower limit value. The actual resource value is
	used for the synchronization rather than the lt value. If the value		used for the synchronization rather than the lth value. If the value
	continues to fall no new state synchronizations are generated as a		continues to fall no new state synchronizations are generated as a
	result of lt. If the value rises above the lower limit value and		result of lth. If the value rises above the lower limit value and
	then drops below the lower limit then a new state synchronization is		then drops below the lower limit then a new state synchronization is
	generated.		generated.
	3.3.7. Attribute Interactions		3.3.7. Attribute Interactions
	Pmin, pmax, st, gt and lt may be present in the same query.		Pmin, pmax, st, gth and lth may be present in the same query.
	If pmin and pmax are present in a query then they take precedence		If pmin and pmax are present in a query then they take precedence
	over the other parameters. Thus even if st, gt or lt are met, if		over the other parameters. Thus even if st, gth or lth are met, if
	pmin has not been exceeded then no state synchronization occurs.		pmin has not been exceeded then no state synchronization occurs.
	Likewise if st, gt or lt have not been met and pmax time has expired		Likewise if st, gth or lth have not been met and pmax time has
	then state synchronization occurs. The current value of the resource		expired then state synchronization occurs. The current value of the
	is used for the synchronization. If pmin time is exceeded and st, gt		resource is used for the synchronization. If pmin time is exceeded
	or lt are met then the current value of the resource is synchronized.		and st, gth or lth are met then the current value of the resource is
	If st is also included, a state synchronization resulting from pmin		synchronized. If st is also included, a state synchronization
	or pmax updates STinit with the synchronized value.		resulting from pmin or pmax updates STinit with the synchronized
			value.
	If gt and lt are included gt MUST be greater than lt otherwise an		If gth and lth are included gth MUST be greater than lth otherwise an
	error CoAP error code 4.00 "Bad Request" (or equivalent) MUST be		error CoAP error code 4.00 "Bad Request" (or equivalent) MUST be
	returned.		returned.
	If st is included in a query with a gt or lt attribute then state		If st is included in a query with a gth or lth attribute then state
	synchronizations occur only when the conditions described by st AND		synchronizations occur only when the conditions described by st AND
	gt or st AND gl are met.		gth or st AND gl are met.
	4. Binding Table		4. Binding Table
	The binding table is a special resource that gives access to the		The binding table is a special resource that gives access to the
	bindings on a endpoint. A binding table resource MUST support the		bindings on a endpoint. A binding table resource MUST support the
	Binding interface defined below. A profile SHOULD allow only one		Binding interface defined below. A profile SHOULD allow only one
	resource table per endpoint.		resource table per endpoint.
	4.1. Binding Interface Description		4.1. Binding Interface Description
	skipping to change at page 10, line 23 ¶		skipping to change at page 10, line 29 ¶
	+----------------+------------------+------------------+		+----------------+------------------+------------------+
	| Resource | Parameter | Data Format |		| Resource | Parameter | Data Format |
	+----------------+------------------+------------------+		+----------------+------------------+------------------+
	| Minimum Period | /{resource}?pmin | xsd:integer (>0) |		| Minimum Period | /{resource}?pmin | xsd:integer (>0) |
	| | | |		| | | |
	| Maximum Period | /{resource}?pmax | xsd:integer (>0) |		| Maximum Period | /{resource}?pmax | xsd:integer (>0) |
	| | | |		| | | |
	| Change Step | /{resource}?st | xsd:decimal (>0) |		| Change Step | /{resource}?st | xsd:decimal (>0) |
	| | | |		| | | |
	| Less Than | /{resource}?lt | xsd:decimal |		| Less Than | /{resource}?lth | xsd:decimal |
	| | | |		| | | |
	| Greater Than | /{resource}?gt | xsd:decimal |		| Greater Than | /{resource}?gth | xsd:decimal |
	+----------------+------------------+------------------+		+----------------+------------------+------------------+
	Table 4: Resource Observation Attribute Summary		Table 4: Resource Observation Attribute Summary
	Minimum Period: As per Section 3.3.2		Minimum Period: As per Section 3.3.2
	Maximum Period: As per Section 3.3.3		Maximum Period: As per Section 3.3.3
	Change Step: As per Section 3.3.4		Change Step: As per Section 3.3.4
	skipping to change at page 11, line 12 ¶		skipping to change at page 11, line 16 ¶
	attempt to take advantage of a poorly implemented client for example		attempt to take advantage of a poorly implemented client for example
	to crash the node or perform denial of service.		to crash the node or perform denial of service.
	6. IANA Considerations		6. IANA Considerations
	6.1. Interface Description		6.1. Interface Description
	The specification registers the "binding" CoRE interface description		The specification registers the "binding" CoRE interface description
	link target attribute value as per [RFC6690].		link target attribute value as per [RFC6690].
	Attribute Value: binding		Attribute Value: core.binding
	Editor's note: RFC6690 actually indicates the use of core. for CoRE
	WG documents. Therefore it probably is more correct to register
	core.binding . However this may cause a problem for existing
	implementations. One approach may be to register two attributes
	"binding" and "core.binding."
	Description: The binding interface is used to manipulate a binding		Description: The binding interface is used to manipulate a binding
	table which describes the link bindings between source and		table which describes the link bindings between source and
	destination resources for the purposes of synchronizing their		destination resources for the purposes of synchronizing their
	content.		content.
	Reference: This specification. Note to RFC editor: please insert the		Reference: This specification. Note to RFC editor: please insert the
	RFC of this specification.		RFC of this specification.
	Notes: None		Notes: None
	skipping to change at page 12, line 17 ¶		skipping to change at page 12, line 11 ¶
	Acknowledgement is given to colleagues from the SENSEI project who		Acknowledgement is given to colleagues from the SENSEI project who
	were critical in the initial development of the well-known REST		were critical in the initial development of the well-known REST
	interface concept, to members of the IPSO Alliance where further		interface concept, to members of the IPSO Alliance where further
	requirements for interface types have been discussed, and to Szymon		requirements for interface types have been discussed, and to Szymon
	Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have		Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have
	provided useful discussion and input to the concepts in this		provided useful discussion and input to the concepts in this
	specification.		specification.
	8. Changelog		8. Changelog
			draft-ietf-core-dynlink-02
			o General: Changed the name of the greater than attribute "gt" to
			"gth" and the name of the less than attribute "lt" to "lth" due to
			conlict with the core resource directory draft lifetime "lt"
			attribute.
			o Clause 6.1: Addressed the editor's note by changing the link
			target attribute to "core.binding".
			o Added Appendix A for examples.
	draft-ietf-core-dynlink-01		draft-ietf-core-dynlink-01
	o General: The term state synchronization has been introduced to		o General: The term state synchronization has been introduced to
	describe the process of synchronization between destination and		describe the process of synchronization between destination and
	source resources.		source resources.
	o General: The document has been restructured the make the		o General: The document has been restructured the make the
	information flow better.		information flow better.
	o Clause 3.1: The descriptions of the binding attributes have been		o Clause 3.1: The descriptions of the binding attributes have been
	skipping to change at page 13, line 34 ¶		skipping to change at page 13, line 40 ¶
	[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained		[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
	Application Protocol (CoAP)", RFC 7252,		Application Protocol (CoAP)", RFC 7252,
	DOI 10.17487/RFC7252, June 2014,		DOI 10.17487/RFC7252, June 2014,
	<http://www.rfc-editor.org/info/rfc7252>.		<http://www.rfc-editor.org/info/rfc7252>.
	[RFC7641] Hartke, K., "Observing Resources in the Constrained		[RFC7641] Hartke, K., "Observing Resources in the Constrained
	Application Protocol (CoAP)", RFC 7641,		Application Protocol (CoAP)", RFC 7641,
	DOI 10.17487/RFC7641, September 2015,		DOI 10.17487/RFC7641, September 2015,
	<http://www.rfc-editor.org/info/rfc7641>.		<http://www.rfc-editor.org/info/rfc7641>.
			Appendix A. Examples
			This appendix provides some examples of the use of binding attribute
			/ observe attributes.
			Note: For brevity the only the method or response code is shown in
			the header field.
			A.1. Greater Than (gth) example
			Observed CLIENT SERVER Actual
			t State | | State
			____________ | | ____________
			1 | |
			2 unknown | | 18.5 Cel
			3 +----->| Header: GET
			4 | GET | Token: 0x4a
			5 | | Uri-Path: temperature
			6 | | Uri-Query: gth="25"
			7 | | Observe: 0 (register)
			8 | |
			9 ____________ |<-----+ Header: 2.05
			10 | 2.05 | Token: 0x4a
			11 18.5 Cel | | Observe: 9
			12 | | Payload: "18.5 Cel"
			13 | |
			14 | |
			15 | | ____________
			16 ____________ |<-----+ Header: 2.05
			17 | 2.05 | 26 Cel Token: 0x4a
			18 26 Cel | | Observe: 16
			29 | | Payload: "26 Cel"
			20 | |
			21 | |
			Figure 2: Client Registers and Receives one Notification of the
			Current State and One of a New State when it passes through the
			greather than threshold of 25.
			A.2. Greater Than (gth) and Period Max (pmax) example
			Observed CLIENT SERVER Actual
			t State | | State
			____________ | | ____________
			1 | |
			2 unknown | | 18.5 Cel
			3 +----->| Header: GET
			4 | GET | Token: 0x4a
			5 | | Uri-Path: temperature
			6 | | Uri-Query: pmax="20";gth="25"
			7 | | Observe: 0 (register)
			8 | |
			9 ____________ |<-----+ Header: 2.05
			10 | 2.05 | Token: 0x4a
			11 18.5 Cel | | Observe: 9
			12 | | Payload: "18.5 Cel"
			13 | |
			14 | |
			15 | |
			16 | |
			17 | |
			18 | |
			19 | |
			20 | |
			21 | |
			22 | |
			23 | |
			24 | |
			25 | |
			26 | |
			27 | |
			28 | |
			29 | | ____________
			30 ____________ |<-----+ Header: 2.05
			31 | 2.05 | 23 Cel Token: 0x4a
			32 23 Cel | | Observe: 30
			33 | | Payload: "23 Cel"
			34 | |
			35 | |
			36 | | ____________
			37 ____________ |<-----+ Header: 2.05
			38 | 2.05 | 26 Cel Token: 0x4a
			39 26 Cel | | Observe: 37
			40 | | Payload: "26 Cel"
			41 | |
			42 | |
			Figure 3: Client Registers and Receives one Notification of the
			Current State, one when pmax time expires and one of a new State when
			it passes through the greather than threshold of 25.
	Authors' Addresses		Authors' Addresses
	Zach Shelby		Zach Shelby
	ARM		ARM
	150 Rose Orchard		150 Rose Orchard
	San Jose 95134		San Jose 95134
	FINLAND		FINLAND
	Phone: +1-408-203-9434		Phone: +1-408-203-9434
	Email: zach.shelby@arm.com		Email: zach.shelby@arm.com
	skipping to change at page 14, line 16 ¶		skipping to change at page 16, line 24 ¶
	665 Clyde Avenue		665 Clyde Avenue
	Mountain View 94043		Mountain View 94043
	USA		USA
	Email: michael.koster@smartthings.com		Email: michael.koster@smartthings.com
	Christian Groves		Christian Groves
	Huawei		Huawei
	Australia		Australia
	Email: Christian.Groves@nteczone.com		Email: cngroves.std@gmail.com
End of changes. 31 change blocks.
	41 lines changed or deleted		140 lines changed or added
This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/