draft-ietf-core-dynlink-06.txt		draft-ietf-core-dynlink-07.txt
	CoRE Working Group Z. Shelby		CoRE Working Group Z. Shelby
	Internet-Draft ARM		Internet-Draft ARM
	Intended status: Informational M. Koster		Intended status: Informational M. Koster
	Expires: January 4, 2019 SmartThings		Expires: April 25, 2019 SmartThings
	C. Groves		C. Groves
	J. Zhu		J. Zhu
	Huawei		Huawei
	B. Silverajan, Ed.		B. Silverajan, Ed.
	Tampere University of Technology		Tampere University of Technology
	July 03, 2018		October 22, 2018
	Dynamic Resource Linking for Constrained RESTful Environments		Dynamic Resource Linking for Constrained RESTful Environments
	draft-ietf-core-dynlink-06		draft-ietf-core-dynlink-07
	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 note		Editor note
	skipping to change at page 1, line 46 ¶		skipping to change at page 1, line 46 ¶
	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 https://datatracker.ietf.org/drafts/current/.		Drafts is at https://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 January 4, 2019.		This Internet-Draft will expire on April 25, 2019.
	Copyright Notice		Copyright Notice
	Copyright (c) 2018 IETF Trust and the persons identified as the		Copyright (c) 2018 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
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://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 40 ¶		skipping to change at page 2, line 40 ¶
	4. Binding and Resource Observation Attributes . . . . . . . . . 6		4. Binding and Resource Observation Attributes . . . . . . . . . 6
	4.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . . . 7		4.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . . . 7
	4.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . . . 7		4.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . . . 7
	4.3. Change Step (st) . . . . . . . . . . . . . . . . . . . . 7		4.3. Change Step (st) . . . . . . . . . . . . . . . . . . . . 7
	4.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . . . 8		4.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . . . 8
	4.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . . . 8		4.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . . . 8
	4.6. Notification Band (band) . . . . . . . . . . . . . . . . 8		4.6. Notification Band (band) . . . . . . . . . . . . . . . . 8
	4.7. Attribute Interactions . . . . . . . . . . . . . . . . . 9		4.7. Attribute Interactions . . . . . . . . . . . . . . . . . 9
	5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 10		5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 10
	6. Implementation Considerations . . . . . . . . . . . . . . . . 11		6. Implementation Considerations . . . . . . . . . . . . . . . . 11
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 11		7. Security Considerations . . . . . . . . . . . . . . . . . . . 12
	8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12		8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
	8.1. Interface Description . . . . . . . . . . . . . . . . . . 12		8.1. Interface Description . . . . . . . . . . . . . . . . . . 12
	8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 12		8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13
	9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13		9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13
	10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 13		10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 13
	11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 13		11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 13
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15		12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
	12.1. Normative References . . . . . . . . . . . . . . . . . . 15		12.1. Normative References . . . . . . . . . . . . . . . . . . 15
	12.2. Informative References . . . . . . . . . . . . . . . . . 15		12.2. Informative References . . . . . . . . . . . . . . . . . 16
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 15		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16
	A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 15		A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 16
	A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 16		A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 17
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
	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 [RFC7252] and a set of related		environments describe a REST protocol [RFC7252] 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 [RFC6690] is a		machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a
	standard for doing Web Linking [RFC8288] in constrained environments.		standard for doing Web Linking [RFC8288] 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 9, line 48 ¶		skipping to change at page 9, line 48 ¶
	band minimum or maximum.		band minimum or maximum.
	4.7. Attribute Interactions		4.7. Attribute Interactions
	Pmin, pmax, st, gt and lt may be present in the same query.		Pmin, pmax, st, gt and lt may be present in the same query.
	Parameters are not defined at multiple prioritization levels.		Parameters are not defined at multiple prioritization levels.
	Instead, the server state machine generates a notification whenever		Instead, the server state machine generates a notification whenever
	any of the parameter conditions are met, after which it performs a		any of the parameter conditions are met, after which it performs a
	reset on all the requested conditions. State synchronization also		reset on all the requested conditions. State synchronization also
	occurs only once even if there are multiple conditions being met at		occurs only once even if there are multiple conditions being met at
	the same time.		the same time. The reference code below illustrates how
			notifications are generated.
			bool notifiable( Resource * r ) {
			#define BAND r->band
			#define SCALAR_TYPE ( num_type == r->type )
			#define STRING_TYPE ( str_type == r->type )
			#define BOOLEAN_TYPE ( bool_type == r->type )
			#define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin )
			#define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax )
			#define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt )
			#define GT_EX ( r->v > r->gt ^ r->last_rep_v > r->gt )
			#define ST_EX ( abs( r->v - r->last_rep_v ) >= r->st )
			#define IN_BAND ( ( r->gt <= r->v && r->v <= r->lt ) || ( r->lt <= r->gt && r->gt <= r->v ) || ( r->v <= r->lt && r->lt <= r->gt ) )
			#define VB_CHANGE ( r->vb != r->last_rep_vb )
			#define VS_CHANGE ( r->vs != r->last_rep_vs )
			return (
			PMIN_EX &&
			( SCALAR_TYPE ?
			( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) ||
			( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) )
			: STRING_TYPE ?
			( VS_CHANGE || PMAX_EX )
			: BOOLEAN_TYPE ?
			( VB_CHANGE || PMAX_EX )
			: false )
			);
			}
			Figure 1: Code logic for attribute interactions for observe
			notification
	5. Binding Table		5. 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. This section defines a REST interface for		bindings on a endpoint. This section defines a REST interface for
	Binding table resources. The Binding table resource MUST support the		Binding table resources. The Binding table resource MUST support the
	Binding interface defined below. The interface supports the link-		Binding interface defined below. The interface supports the link-
	format type.		format type.
	The if= column defines the Interface Description (if=) attribute		The if= column defines the Interface Description (if=) attribute
	skipping to change at page 10, line 37 ¶		skipping to change at page 11, line 19 ¶
	| Interface | if= | Methods | Content-Formats |		| Interface | if= | Methods | Content-Formats |
	+-----------+----------+-------------------+-----------------+		+-----------+----------+-------------------+-----------------+
	| Binding | core.bnd | GET, POST, DELETE | link-format |		| Binding | core.bnd | GET, POST, DELETE | link-format |
	+-----------+----------+-------------------+-----------------+		+-----------+----------+-------------------+-----------------+
	Table 4: Binding Interface Description		Table 4: Binding Interface Description
	The Binding interface is used to manipulate a binding table. A		The Binding interface is used to manipulate a binding table. A
	request with a POST method and a content format of application/link-		request with a POST method and a content format of application/link-
	format simply appends new bindings to the table. All links in the		format simply appends new bindings to the table. All links in the
	payload MUST have a relation type "boundTo". A GET request simply		payload MUST have a relation type "boundto". A GET request simply
	returns the current state of a binding table whereas a DELETE request		returns the current state of a binding table whereas a DELETE request
	empties the table. Individual entries may be deleted from the table		empties the table. Individual entries may be deleted from the table
	by specifying the resource path in a DELETE request.		by specifying the resource path in a DELETE request.
	The following example shows requests for adding, retrieving and		The following example shows requests for adding, retrieving and
	deleting bindings in a binding table.		deleting bindings in a binding table.
	Req: POST /bnd/ (Content-Format: application/link-format)		Req: POST /bnd/ (Content-Format: application/link-format)
	<coap://sensor.example.com/s/light>;		<coap://sensor.example.com/s/light>;
	rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"		rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
	skipping to change at page 11, line 21 ¶		skipping to change at page 11, line 43 ¶
	Res: 2.05 Content (application/link-format)		Res: 2.05 Content (application/link-format)
	<coap://sensor.example.com/s/light>;		<coap://sensor.example.com/s/light>;
	rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"		rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
	Req: DELETE /bnd/a/light		Req: DELETE /bnd/a/light
	Res: 2.04 Changed		Res: 2.04 Changed
	Req: DELETE /bnd/		Req: DELETE /bnd/
	Res: 2.04 Changed		Res: 2.04 Changed
	Figure 1: Binding Interface Example		Figure 2: Binding Interface Example
	6. Implementation Considerations		6. Implementation Considerations
	When using multiple resource bindings (e.g. multiple Observations of		When using multiple resource bindings (e.g. multiple Observations of
	resource) with different bands, consideration should be given to the		resource) with different bands, consideration should be given to the
	resolution of the resource value when setting sequential bands. For		resolution of the resource value when setting sequential bands. For
	example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30).		example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30).
	If the resource value returns an integer then notifications for		If the resource value returns an integer then notifications for
	values between and inclusive of 10 and 30 will be triggered. Whereas		values between and inclusive of 10 and 30 will be triggered. Whereas
	if the resolution is to one decimal point (0.1) then notifications		if the resolution is to one decimal point (0.1) then notifications
	for values 20.1 to 20.9 will not be triggered.		for values 20.1 to 20.9 will not be triggered.
	The use of the notification band minimum and maximum allow for a		The use of the notification band minimum and maximum allow for a
	synchronization whenever a change in the resource value occurs.		synchronization whenever a change in the resource value occurs.
	Theoretically this could occur in-line with the server internal		Theoretically this could occur in-line with the server internal
	sample period for the determining the resource value. Implementors		sample period for the determining the resource value. Implementors
	SHOULD consider the resolution needed before updating the resource,		SHOULD consider the resolution needed before updating the resource,
	e.g. updating the resource when a temperature sensor value changes by		e.g. updating the resource when a temperature sensor value changes by
	0.001 degree versus 1 degree.		0.001 degree versus 1 degree.
	7. Security Considerations
	The initiation of a link binding can be delegated from a client to a		The initiation of a link binding can be delegated from a client to a
	link state machine implementation, which can be an embedded client or		link state machine implementation, which can be an embedded client or
	a configuration tool. Consequently, consideration has to be given to		a configuration tool. Implementation considerations have to be given
	what kinds of security credentials the the state machine needs to be		to how to monitor transactions made by the configuration tool with
	configured with, and what kinds of access control lists client		regards to link bindings, as well as any errors that may arise with
			establishing link bindings as well as with established link bindings.
			7. Security Considerations
			Consideration has to be given to what kinds of security credentials
			the state machine of a configuration tool or an embedded client needs
			to be configured with, and what kinds of access control lists client
	implementations should possess, so that transactions on creating link		implementations should possess, so that transactions on creating link
	bindings and handling error conditions can be processed by the state		bindings and handling error conditions can be processed by the state
	machine.		machine.
	An implementation of a client needs to be prepared to deal with
	responses to a request that differ from what is specified in this
	specification. A server implementing what the client thinks is a
	resource with one of these interface descriptions could return
	malformed representations and response codes either by accident or
	maliciously. A server sending maliciously malformed responses could
	attempt to take advantage of a poorly implemented client for example
	to crash the node or perform denial of service.
	8. IANA Considerations		8. IANA Considerations
	8.1. Interface Description		8.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: core.bnd		Attribute Value: core.bnd
	Description: The binding interface is used to manipulate a binding		Description: The binding interface is used to manipulate a binding
	skipping to change at page 13, line 13 ¶		skipping to change at page 13, line 32 ¶
	Application Data: None		Application Data: None
	9. Acknowledgements		9. Acknowledgements
	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. Christian Amsuss supplied a comprehensive review of
			draft -06.
	10. Contributors		10. Contributors
	Matthieu Vial		Matthieu Vial
	Schneider-Electric		Schneider-Electric
	Grenoble		Grenoble
	France		France
	Phone: +33 (0)47657 6522		Phone: +33 (0)47657 6522
	EMail: matthieu.vial@schneider-electric.com		EMail: matthieu.vial@schneider-electric.com
	11. Changelog		11. Changelog
	draft-ietf-core-dynlink-06		draft-ietf-core-dynlink-07
			o Added reference code to illustrate attribute interactions for
			observations
			draft-ietf-core-dynlink-06
	o Document restructure and refactoring into three main sections		o Document restructure and refactoring into three main sections
	o Clarifications on band usage		o Clarifications on band usage
	o Implementation considerations introduced		o Implementation considerations introduced
	o Additional text on security considerations		o Additional text on security considerations
	draft-ietf-core-dynlink-05		draft-ietf-core-dynlink-05
	skipping to change at page 16, line 29 ¶		skipping to change at page 17, line 29 ¶
	13 | |		13 | |
	14 | |		14 | |
	15 | | ____________		15 | | ____________
	16 ____________ |<-----+ Header: 2.05		16 ____________ |<-----+ Header: 2.05
	17 | 2.05 | 26 Cel Token: 0x4a		17 | 2.05 | 26 Cel Token: 0x4a
	18 26 Cel | | Observe: 16		18 26 Cel | | Observe: 16
	29 | | Payload: "26 Cel"		29 | | Payload: "26 Cel"
	20 | |		20 | |
	21 | |		21 | |
	Figure 2: Client Registers and Receives one Notification of the		Figure 3: Client Registers and Receives one Notification of the
	Current State and One of a New State when it passes through the		Current State and One of a New State when it passes through the
	greather than threshold of 25.		greather than threshold of 25.
	A.2. Greater Than (gt) and Period Max (pmax) example		A.2. Greater Than (gt) and Period Max (pmax) example
	Observed CLIENT SERVER Actual		Observed CLIENT SERVER Actual
	t State | | State		t State | | State
	____________ | | ____________		____________ | | ____________
	1 | |		1 | |
	2 unknown | | 18.5 Cel		2 unknown | | 18.5 Cel
	skipping to change at page 17, line 33 ¶		skipping to change at page 18, line 33 ¶
	34 | |		34 | |
	35 | |		35 | |
	36 | | ____________		36 | | ____________
	37 ____________ |<-----+ Header: 2.05		37 ____________ |<-----+ Header: 2.05
	38 | 2.05 | 26 Cel Token: 0x4a		38 | 2.05 | 26 Cel Token: 0x4a
	39 26 Cel | | Observe: 37		39 26 Cel | | Observe: 37
	40 | | Payload: "26 Cel"		40 | | Payload: "26 Cel"
	41 | |		41 | |
	42 | |		42 | |
	Figure 3: Client Registers and Receives one Notification of the		Figure 4: Client Registers and Receives one Notification of the
	Current State, one when pmax time expires and one of a new State when		Current State, one when pmax time expires and one of a new State when
	it passes through the greather than threshold of 25.		it passes through the greather than threshold of 25.
	Authors' Addresses		Authors' Addresses
	Zach Shelby		Zach Shelby
	ARM		ARM
	Kidekuja 2		Kidekuja 2
	Vuokatti 88600		Vuokatti 88600
	FINLAND		FINLAND
End of changes. 19 change blocks.
	32 lines changed or deleted		65 lines changed or added
This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/