--- 1/draft-ietf-core-resource-directory-15.txt 2018-10-22 16:13:25.853417789 -0700 +++ 2/draft-ietf-core-resource-directory-16.txt 2018-10-22 16:13:26.001421370 -0700 @@ -1,24 +1,24 @@ CoRE Z. Shelby Internet-Draft ARM Intended status: Standards Track M. Koster -Expires: April 6, 2019 SmartThings +Expires: April 26, 2019 SmartThings C. Bormann Universitaet Bremen TZI P. van der Stok consultant C. Amsuess, Ed. - October 03, 2018 + October 23, 2018 CoRE Resource Directory - draft-ietf-core-resource-directory-15 + draft-ietf-core-resource-directory-16 Abstract In many M2M applications, direct discovery of resources is not practical due to sleeping nodes, disperse networks, or networks where multicast traffic is inefficient. These problems can be solved by employing an entity called a Resource Directory (RD), which hosts registrations of resources held on other servers, allowing lookups to be performed for those resources. This document specifies the web interfaces that a Resource Directory supports for web servers to @@ -34,21 +34,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on April 6, 2019. + This Internet-Draft will expire on April 26, 2019. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -100,45 +100,46 @@ Parameter . . . . . . . . . . . . . . . . . . . . . 46 10.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . 46 10.5. Multicast Address Registration . . . . . . . . . . . . . 47 11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47 11.1. Lighting Installation . . . . . . . . . . . . . . . . . 47 11.1.1. Installation Characteristics . . . . . . . . . . . . 47 11.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 48 11.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 51 11.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 52 11.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 53 - 11.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 54 + 11.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 55 11.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 55 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 55 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 14.1. Normative References . . . . . . . . . . . . . . . . . . 62 - 14.2. Informative References . . . . . . . . . . . . . . . . . 62 - Appendix A. Registration Management . . . . . . . . . . . . . . 64 + 14.2. Informative References . . . . . . . . . . . . . . . . . 63 + Appendix A. Registration Management . . . . . . . . . . . . . . 65 A.1. Registration Update . . . . . . . . . . . . . . . . . . . 65 A.2. Registration Removal . . . . . . . . . . . . . . . . . . 68 A.3. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 69 A.4. Update Endpoint Links . . . . . . . . . . . . . . . . . . 70 - A.5. Endpoint and group lookup . . . . . . . . . . . . . . . . 70 + A.5. Endpoint and group lookup . . . . . . . . . . . . . . . . 71 Appendix B. Web links and the Resource Directory . . . . . . . . 72 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 72 - B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 72 + B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 73 B.1.2. Interpreting attributes and relations . . . . . . . . 73 - B.2. A slightly more complex example . . . . . . . . . . . . . 73 + B.2. A slightly more complex example . . . . . . . . . . . . . 74 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 74 B.4. A note on differences between link-format and Link - headers . . . . . . . . . . . . . . . . . . . . . . . . . 75 - Appendix C. Syntax examples for Protocol Negotiation . . . . . . 76 - Appendix D. Modernized Link Format parsing . . . . . . . . . . . 77 - D.1. For endpoint developers . . . . . . . . . . . . . . . . . 78 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 + headers . . . . . . . . . . . . . . . . . . . . . . . . . 76 + Appendix C. Syntax examples for Protocol Negotiation . . . . . . 77 + Appendix D. Modernized Link Format parsing . . . . . . . . . . . 78 + D.1. For endpoint developers . . . . . . . . . . . . . . . . . 79 + D.2. Examples of links with differing interpretations . . . . 79 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80 1. Introduction The work on Constrained RESTful Environments (CoRE) aims at realizing the REST architecture in a suitable form for the most constrained nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) applications such as smart energy and building automation. The discovery of resources offered by a constrained server is very @@ -364,20 +365,27 @@ | Endpoint | <-- Name, Scheme, IP, Port +------------+ | | +------------+ | Resource | <-- Target, Parameters +------------+ Figure 2: The resource directory information hierarchy. + A Registrant-EP MAY keep concurrent registrations to more than one RD + at the same time if explicitly configured to do so, but that is not + expected to be supported by typical EP implementations. Any such + registrations are independent of each other. The usual expectation + when multiple discovery mechanisms or addresses are configured is + that they constitute a fallback path for a single registration. + 3.3. RD Content Model The Entity-Relationship (ER) models shown in Figure 3 and Figure 4 model the contents of /.well-known/core and the resource directory respectively, with entity-relationship diagrams [ER]. Entities (rectangles) are used for concepts that exist independently. Attributes (ovals) are used for concepts that exist only in connection with a related entity. Relations (diamonds) give a semantic meaning to the relation between entities. Numbers specify the cardinality of the relations. @@ -892,23 +900,25 @@ "ct" MAY include a space-separated sequence of Content-Format codes as specified in Section 7.2.1 of [RFC7252], indicating that multiple content-formats are available. The example below shows the required Content-Format 40 (application/link-format) indicated as well as the CBOR and JSON representation of link format. The RD resource locations /rd, /rd-lookup, and /rd-group are example values. The server in this example also indicates that it is capable of providing observation on resource lookups. [ The RFC editor is asked to replace these and later occurrences of - MCD1, TBD64 and TBD504 with the numeric ID values assigned by IANA to - application/link-format+cbor and application/link-format+json, - respectively, as they are defined in I-D.ietf-core-links-json. ] + MCD1, TBD64 and TBD504 with the assigned IPv6 site-local address for + "all CoRE Resource Directories" and the numeric ID values assigned by + IANA to application/link-format+cbor and application/link- + format+json, respectively, as they are defined in I-D.ietf-core- + links-json. ] Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* Res: 2.05 Content ;rt="core.rd";ct="40 65225", ;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs, ;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504", ;rt="core.rd-lookup-gp";ct=40 TBD64 TBD504", ;rt="core.rd-group";ct="40 TBD64 TBD504" From a management and maintenance perspective, it is necessary to @@ -1286,34 +1296,35 @@ value of the individual links as exemplified in Appendix B. An eventual (currently non-existing) "base" attribute of the link is not affected by the value of "base" parameter in the registration. 6. RD Groups This section defines the REST API for the creation, management, and lookup of endpoints for group operations. Similar to endpoint registration entries in the RD, groups may be created or removed. However unlike an endpoint entry, a group entry consists of a list of - endpoints and does not have a lifetime associated with it. In order - to make use of multicast requests with CoAP, a group MAY have a - multicast address associated with it. + endpoints and does not have a lifetime associated with it. To make + use of multicast requests with CoAP, a group MAY have a multicast + address associated with it, and should share a common set of + resources. 6.1. Register a Group - In order to create a group, a commissioning tool (CT) used to - configure groups, makes a request to the RD indicating the name of - the group to create (or update), optionally the sector the group - belongs to, and optionally the multicast address of the group. This - specification does not require that the endpoints belong to the same - sector as the group, but a Resource Directory implementation can - impose requirements on the sectors of groups and endpoints depending - on its configuration. + To create a group, a commissioning tool (CT) used to configure + groups, makes a request to the RD indicating the name of the group to + create (or update), optionally the sector the group belongs to, and + optionally the multicast address of the group. This specification + does not require that the endpoints belong to the same sector as the + group, but a Resource Directory implementation can impose + requirements on the sectors of groups and endpoints depending on its + configuration. The registration message is a list of links to registration resources of the endpoints that belong to that group. The CT can use any URI reference discovered using endpoint lookup from the same server or obtained by registering an endpoint using third party registration and enter it into a group. The commissioning tool SHOULD not send any target attributes with the links to the registration resources, and the resource directory SHOULD reject registrations that contain links with unprocessable @@ -1377,21 +1387,21 @@ The following example shows an EP registering a group with the name "lights" which has two endpoints. The RD group path /rd-group is an example RD location discovered in a request similar to Figure 6. Req: POST coap://rd.example.com/rd-group?gp=lights &base=coap://[ff35:30:2001:db8::1] Content-Format: 40 Payload: , - + Res: 2.01 Created Location-Path: /rd-group/12 A relative href value denotes the path to the registration resource of the Endpoint. When pointing to a registration resource on a different RD, the href value is a URI. 6.2. Group Removal @@ -1722,21 +1732,21 @@ accessing the RD. The contents of the RD are inserted in two ways: 1. The node hosting the discoverable endpoint fills the RD with the contents of /.well-known/core by: * Storing the contents directly into RD (see Section 5.3) * Requesting the RD to load the contents from /.well-known/core - see (section {{simple}) + (see Section 5.3.1) 2. A Commissioning Tool (CT) fills the RD with endpoint information for a set of discoverable nodes. (see Section 5.3 with base=authority parameter value) In both cases, the nodes filling the RD should be authenticated and authorized to change the contents of the RD. An Authorization Server (AS) is responsible to assign a token to the registering node to authorize the node to discover or register endpoints in a given RD [I-D.ietf-ace-oauth-authz]. @@ -2198,29 +2208,29 @@ Res: 2.01 Created Location-Path: /rd/4523 The sector name d=R2-4-015 has been added for an efficient lookup because filtering on "ep" name is more awkward. The same sector name is communicated to the two luminaries and the presence sensor by the CT. The group is specified in the RD. The base parameter is set to the site-local multicast address allocated to the group. In the POST in - the example below, these two endpoints and the endpoint of the - presence sensor are registered as members of the group. + the example below, two luminary endpoints are registered as members + of the group. They share a common resource set to which a multicast + request can be sent and executed by all members of the group. Req: POST coap://[2001:db8:4::ff]/rd-group ?gp=grp_R2-4-015&base=coap://[ff05::1] Payload: , - , - + Res: 2.01 Created Location-Path: /rd-group/501 After the filling of the RD by the CT, the application in the luminaries can learn to which groups they belong, and enable their interface for the multicast address. The luminary, knowing its sector and own IPv6 address, looks up the groups containing light resources it is assigned to: @@ -2242,20 +2252,31 @@ Content-Format: application/coap-group+json Payload: { "a": "[ff05::1]", "n": "grp_R2-4-015"} Res: 2.01 Created Location-Path: /coap-group/1 Dependent on the situation, only the address, "a", or the name, "n", is specified in the coap-group resource. + The presence sensor can learn the presence of groups that support + resources with rt=light in its own sector by sending the request: + + Req: GET coap://[2001:db8:4::ff]/rd-lookup/gp?d=R2-4-015&rt=light + + Res: 2.05 Content + ;gp="grp_R2-4-015";base="coap://[ff05::1]" + + The presence sensor learns the multicast address to use for sending + messages to the luminaries. + 11.2. OMA Lightweight M2M (LWM2M) Example This example shows how the OMA LWM2M specification makes use of Resource Directory (RD). OMA LWM2M is a profile for device services based on CoAP(OMA Name Authority). LWM2M defines a simple object model and a number of abstract interfaces and operations for device management and device service enablement. @@ -2435,20 +2458,36 @@ Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, Hannes Tschofenig, Sampo Ukkola, Linyi Tian, and Jan Newmarch have provided helpful comments, discussions and ideas to improve and shape this document. Zach would also like to thank his colleagues from the EU FP7 SENSEI project, where many of the resource directory concepts were originally developed. 13. Changelog + changes from -15 to -16 + + o Recommend a common set of resources for members of a group + + o Clarified use of multicast group in lighting example + + o Add note on concurrent registrations from one EP being possible + but not expected + + o Refresh web examples appendix to reflect current use of Modernized + Link Format + + o Add examples of URIs where Modernized Link Format matters + + o Editorial changes + changes from -14 to -15 o Rewrite of section "Security policies" o Clarify that the "base" parameter text applies both to relative references both in anchor and href o Renamed "Registree-EP" to Registrant-EP" o Talk of "relative references" and "URIs" rather than "relative" @@ -3215,20 +3258,24 @@ references is a journey through different documents ([RFC3986] defining URIs, [RFC6690] defining link-format documents based on [RFC8288] which defines link headers, and [RFC7252] providing the transport). This appendix summarizes the mechanisms and semantics at play from an entry in ".well-known/core" to a resource lookup. This text is primarily aimed at people entering the field of Constrained Restful Environments from applications that previously did not use web mechanisms. + At all examples in this section give compatible results for both + Modernized and RFC6690 Link Format; the explanation of the steps + follow Modernized Link Format. + B.1. A simple example Let's start this example with a very simple host, "2001:db8:f0::1". A client that follows classical CoAP Discovery ([RFC7252] Section 7), sends the following multicast request to learn about neighbours supporting resources with resource-type "temperature". The client sends a link-local multicast: GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature @@ -3240,45 +3287,45 @@ While the client - on the practical or implementation side - can just go ahead and create a new request to "[2001:db8:f0::1]:5683" with Uri-Path: "temp", the full resolution steps for insertion into and retrieval from the RD without any shortcuts are: B.1.1. Resolving the URIs The client parses the single returned record. The link's target (sometimes called "href") is ""/temp"", which is a relative URI that - needs resolving. As long as all involved links follow the - restrictions set forth for this document (see Appendix B.4), the base - URI is used to resolve the - reference /temp against. + needs resolving. The base URI is used to resolve the reference /temp against. The Base URI of the requested resource can be composed from the header options of the CoAP GET request by following the steps of [RFC7252] section 6.5 (with an addition at the end of 8.2) into ""coap://[2001:db8:f0::1]/.well-known/core"". - The record's target is resolved by replacing the path ""/.well-known/ - core"" from the Base URI (section 5.2 [RFC3986]) with the relative - target URI ""/temp"" into ""coap://[2001:db8:f0::1]/temp"". + Because ""/temp"" starts with a single slash, the record's target is + resolved by replacing the path ""/.well-known/core"" from the Base + URI (section 5.2 [RFC3986]) with the relative target URI ""/temp"" + into ""coap://[2001:db8:f0::1]/temp"". B.1.2. Interpreting attributes and relations Some more information but the record's target can be obtained from the payload: the resource type of the target is "temperature", and its content type is text/plain (ct=0). A relation in a web link is a three-part statement that specifies a named relation between the so-called "context resource" and the target resource, like "_This page_ has _its table of contents_ at _/ - toc.html_". In [RFC6690] link-format documents, there is an implicit - "host relation" specified with default parameter: rel="hosts". + toc.html_". In [RFC6690] and modernized link-format documents, there + is an implicit "host relation" specified with default parameter: + rel="hosts". In our example, the context resource of the link is the URI specified in the GET request "coap:://[2001:db8:f0::1]/.well-known/core". A full English expression of the "host relation" is: '"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource "coap://[2001:db8:f0::1]/temp", which is of the resource type "temperature" and can be accessed using the text/plain content format.' @@ -3319,21 +3366,21 @@ used Simple Registration to register at the resource directory that was announced to it, sending this request from its UDP port "[2001:db8:f0::1]:6553": POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1 The resource directory would have accepted the registration, and queried the simple host's ".well-known/core" by itself. As a result, the host is registered as an endpoint in the RD with the name "simple-host1". The registration is active for 90000 seconds, and - the endpoint registration Base URI is ""coap://[2001:db8:f0::1]/"" + the endpoint registration Base URI is ""coap://[2001:db8:f0::1]"" following the resolution steps described in Appendix B.1.1. It should be remarked that the Base URI constructed that way always yields a URI of the form: scheme://authority without path suffix. If the client now queries the RD as it would previously have issued a multicast request, it would go through the RD discovery steps by fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the resource lookup endpoint, and issue a request to "coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive @@ -3344,46 +3391,45 @@ This is not _literally_ the same response that it would have received from a multicast request, but it contains the equivalent statement: '"coap://[2001:db8:f0::1]" is hosting the resource "coap://[2001:db8:f0::1]/temp", which is of the resource type "temperature" and can be accessed using the text/plain content format.' (The difference is whether "/" or "/.well-known/core" hosts the - resources, which is subject of ongoing discussion about RFC6690). - - Actually, /.well-known/core does NOT host the resource but stores a - URI reference to the resource. + resources, which is one of the often misunderstood subtleties + Modernized Link Format addresses. Actually, /.well-known/core does + NOT host the resource but stores a URI reference to the resource.) To complete the examples, the client could also query all resources hosted at the endpoint with the known endpoint name "simple-host1". A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1" would return ;rt=temperature;ct=0; anchor="coap://[2001:db8:f0::1]", ;rt=light-lux;ct=0; anchor="coap://[2001:db8:f0::1]", ; anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, ; anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby" All the target and anchor references are already in absolute form there, which don't need to be resolved any further. - Had the simple host registered with a base= parameter (e.g. - "?ep=simple-host1&base=coap+tcp://simple-host1.example.com"), that - context would have been used to resolve the relative anchor values - instead, giving + Had the simple host done an equivalent full registration with a base= + parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple- + host1.example.com"), that context would have been used to resolve the + relative anchor values instead, giving ;rt=temperature;ct=0; anchor="coap+tcp://simple-host1.example.com" and analogous records. B.4. A note on differences between link-format and Link headers While link-format and Link headers look very similar and are based on the same model of typed links, there are some differences between @@ -3512,39 +3557,73 @@ interpretation only affect links where the absent anchor attribute means "coap://host/" according to RFC6690 and "coap://host/.well- known/core" according to Modernized Link format; those typically only occur in conjunction with the vaguely defined implicit "hosts" relationship. D.1. For endpoint developers When developing endpoints, i.e. when generating documents that will be submitted to a Resource Directory, the differences between - Modernized Link Format and RFC6690 can be ignored as long as all - relative references start with a slash, and any of the following - applies: + Modernized Link Format and RFC6690 can be ignored as long as + + o all relative references start with a slash, + + and any of the following applies: o There is no anchor attribute, and the context of the link does not matter to the application. Example: ";ct=40" o The anchor is a relative reference. - Example: ";anchor="/sensors/temp";rel="alternate" + Example: ";anchor="/sensors/temp";rel="alternate"" o The target is an absolute reference. Example: ";anchor="/sensors/ temp";rel="describedby"" +D.2. Examples of links with differing interpretations + + Examples of links with different interpretations from either applying + RFC6690 or Modernized Link Format are shown here. The example is + assumed to be obtained from a document. + + o "": The target is "/sensors" in RFC6690 and "/device/ + sensors" in Modernized Link Format (whereas "" would be + unambiguous). + + o "": The target is "/?which=these" in RFC6690 and + "/device/index?which=these" in Modernized Link Format. + + o ";anchor="http://example.com/calib- + proto/1234";rel="topic"" is about "http://example.com/sensors" in + RFC6690 and about "/device/sensors" in Modernized Link Format. + + This link can not be expressed in RFC6690 link format without the + server explicitly expressing most of its own URI (which is + problematic in reverse proxy scenarios or when the Uri-Host option + is not sent). + + o ";rel="alternate";anchor=""": According to RFC6690, this + states that the "/" resource has an alternative representation at + "/i", whereas Modernized Link Format says that "/devices/index" + has an alternative representation at "/i". + + The "anchor" attribute is usually left out; the link + ";rel="alternate"" is equivalent to the above and results in + the same interpretations. + Authors' Addresses + Zach Shelby ARM 150 Rose Orchard San Jose 95134 USA Phone: +1-408-203-9434 Email: zach.shelby@arm.com Michael Koster