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/