draft-ietf-core-resource-directory-08.txt   draft-ietf-core-resource-directory-09.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft ARM Internet-Draft ARM
Intended status: Standards Track M. Koster Intended status: Standards Track M. Koster
Expires: January 8, 2017 SmartThings Expires: May 4, 2017 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
July 07, 2016 October 31, 2016
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-08 draft-ietf-core-resource-directory-09
Abstract Abstract
In many M2M applications, direct discovery of resources is not In many M2M applications, direct discovery of resources is not
practical due to sleeping nodes, disperse networks, or networks where practical due to sleeping nodes, disperse networks, or networks where
multicast traffic is inefficient. These problems can be solved by multicast traffic is inefficient. These problems can be solved by
employing an entity called a Resource Directory (RD), which hosts employing an entity called a Resource Directory (RD), which hosts
descriptions of resources held on other servers, allowing lookups to descriptions of resources held on other servers, allowing lookups to
be performed for those resources. This document specifies the web be performed for those resources. This document specifies the web
interfaces that a Resource Directory supports in order for web interfaces that a Resource Directory supports in order for web
servers to discover the RD and to register, maintain, lookup and servers to discover the RD and to register, maintain, lookup and
remove resources descriptions. Furthermore, new link attributes remove resource descriptions. Furthermore, new link attributes
useful in conjunction with an RD are defined. useful in conjunction with an RD are defined.
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 January 8, 2017. This Internet-Draft will expire on May 4, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 6 skipping to change at page 3, line 6
9. New Link-Format Attributes . . . . . . . . . . . . . . . . . 32 9. New Link-Format Attributes . . . . . . . . . . . . . . . . . 32
9.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 32 9.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 32
9.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 33 9.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 33
10. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 33 10. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 33
10.1. DNS-based Service discovery . . . . . . . . . . . . . . 33 10.1. DNS-based Service discovery . . . . . . . . . . . . . . 33
10.2. mapping ins to <Instance> . . . . . . . . . . . . . . . 34 10.2. mapping ins to <Instance> . . . . . . . . . . . . . . . 34
10.3. Mapping rt to <ServiceType> . . . . . . . . . . . . . . 35 10.3. Mapping rt to <ServiceType> . . . . . . . . . . . . . . 35
10.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 35 10.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 35
10.5. TXT Record key=value strings . . . . . . . . . . . . . . 35 10.5. TXT Record key=value strings . . . . . . . . . . . . . . 35
10.6. Importing resource links into DNS-SD . . . . . . . . . . 36 10.6. Importing resource links into DNS-SD . . . . . . . . . . 36
11. Security Considerations . . . . . . . . . . . . . . . . . . . 36 11. Security Considerations . . . . . . . . . . . . . . . . . . . 37
11.1. Endpoint Identification and Authentication . . . . . . . 37 11.1. Endpoint Identification and Authentication . . . . . . . 37
11.2. Access Control . . . . . . . . . . . . . . . . . . . . . 37 11.2. Access Control . . . . . . . . . . . . . . . . . . . . . 37
11.3. Denial of Service Attacks . . . . . . . . . . . . . . . 37 11.3. Denial of Service Attacks . . . . . . . . . . . . . . . 37
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
12.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 38 12.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 38
12.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 38 12.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 38
12.3. IPv6 ND Resource Directory Address Option . . . . . . . 38 12.3. IPv6 ND Resource Directory Address Option . . . . . . . 38
12.4. RD Parameter Registry . . . . . . . . . . . . . . . . . 38 12.4. RD Parameter Registry . . . . . . . . . . . . . . . . . 38
13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 39 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 39
13.1. Lighting Installation . . . . . . . . . . . . . . . . . 39 13.1. Lighting Installation . . . . . . . . . . . . . . . . . 39
skipping to change at page 5, line 11 skipping to change at page 5, line 11
All groups within a domain are unique. All groups within a domain are unique.
Endpoint Endpoint
Endpoint (EP) is a term used to describe a web server or client in Endpoint (EP) is a term used to describe a web server or client in
[RFC7252]. In the context of this specification an endpoint is [RFC7252]. In the context of this specification an endpoint is
used to describe a web server that registers resources to the used to describe a web server that registers resources to the
Resource Directory. An endpoint is identified by its endpoint Resource Directory. An endpoint is identified by its endpoint
name, which is included during registration, and is unique within name, which is included during registration, and is unique within
the associated domain of the registration. the associated domain of the registration.
Commissioning Tool Commissioning Tool (CT) is a device that assists Commissioning Tool
during the installation of the network by assigning values to Commissioning Tool (CT) is a device that assists during the
parameters, naming endpoints and groups, or adapting the installation of the network by assigning values to parameters,
installation to the needs of the applications. naming endpoints and groups, or adapting the installation to the
needs of the applications.
RDAO
Resource Directory Address Option.
3. Architecture and Use Cases 3. Architecture and Use Cases
The resource directory architecture is illustrated in Figure 1. A The resource directory architecture is illustrated in Figure 1. A
Resource Directory (RD) is used as a repository for Web Links Resource Directory (RD) is used as a repository for Web Links
[RFC5988] about resources hosted on other web servers, which are [RFC5988] about resources hosted on other web servers, which are
called endpoints (EP). An endpoint is a web server associated with a called endpoints (EP). An endpoint is a web server associated with a
scheme, IP address and port (called Context), thus a physical node scheme, IP address and port (called Context), thus a physical node
may host one or more endpoints. The RD implements a set of REST may host one or more endpoints. The RD implements a set of REST
interfaces for endpoints to register and maintain sets of Web Links interfaces for endpoints to register and maintain sets of Web Links
skipping to change at page 8, line 18 skipping to change at page 8, line 18
public consumption may provide the data to an intermediary server, or public consumption may provide the data to an intermediary server, or
broker. Sensor data are published to the intermediary upon changes broker. Sensor data are published to the intermediary upon changes
or at regular intervals. Descriptions of the sensors that resolve to or at regular intervals. Descriptions of the sensors that resolve to
links to sensor data may be published to a Resource Directory. links to sensor data may be published to a Resource Directory.
Applications wishing to consume the data can use the Resource Applications wishing to consume the data can use the Resource
Directory lookup function set to discover and resolve links to the Directory lookup function set to discover and resolve links to the
desired resources and endpoints. The Resource Directory service need desired resources and endpoints. The Resource Directory service need
not be coupled with the data intermediary service. Mapping of not be coupled with the data intermediary service. Mapping of
Resource Directories to data intermediaries may be many-to-many. Resource Directories to data intermediaries may be many-to-many.
Metadata in web link compatible representations are supplied by Metadata in web-link compatible representations are supplied by
Resource Directories, which may be internally stored as triples, or Resource Directories, which may be internally stored as triples, or
relation/attribute pairs providing metadata about resource links. relation/attribute pairs providing metadata about resource links.
External catalogs that are represented in other formats may be External catalogs that are represented in other formats may be
converted to common web linking formats for storage and access by converted to common web linking formats for storage and access by
Resource Directories. Since it is common practice for these to be Resource Directories. Since it is common practice for these to be
URN encoded, simple and lossless structural transforms should URN encoded, simple and lossless structural transforms should
generally be sufficient to store external metadata in Resource generally be sufficient to store external metadata in Resource
Directories. Directories.
The additional features of Resource Directory allow domains to be The additional features of Resource Directory allow domains to be
skipping to change at page 9, line 30 skipping to change at page 9, line 30
The Resource Directory Option (RDAO) using IPv6 neighbor Discovery The Resource Directory Option (RDAO) using IPv6 neighbor Discovery
(ND) carries information about the address of the Resource Directory (ND) carries information about the address of the Resource Directory
(RD). This information is needed when endpoints cannot discover the (RD). This information is needed when endpoints cannot discover the
Resource Directory with link-local multicast address because the Resource Directory with link-local multicast address because the
endpoint and the RD are separated by a border Router (6LBR). In many endpoint and the RD are separated by a border Router (6LBR). In many
circumstances the availability of DHCP cannot be guaranteed either circumstances the availability of DHCP cannot be guaranteed either
during commissioning of the network. The presence and the use of the during commissioning of the network. The presence and the use of the
RD is essential during commissioning. RD is essential during commissioning.
It is possible to send multiple RDAO options in one message,
indicating as many resource directory addresses.
The lifetime 0x0 means that the RD address is invalid and to be
removed.
The RDAO format is: The RDAO format is:
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length = 3 | Valid Lifetime | | Type | Length = 3 | Valid Lifetime |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reserved | | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| | | |
skipping to change at page 11, line 33 skipping to change at page 11, line 33
5.1. Simple publishing to Resource Directory Server 5.1. Simple publishing to Resource Directory Server
An endpoint that wants to make itself discoverable occasionally sends An endpoint that wants to make itself discoverable occasionally sends
a POST request to the "/.well-known/core" URI of any candidate a POST request to the "/.well-known/core" URI of any candidate
directory server that it finds. The body of the POST request is directory server that it finds. The body of the POST request is
empty, which triggers the resource directory server to perform GET empty, which triggers the resource directory server to perform GET
requests at the requesting server's default discovery URI to obtain requests at the requesting server's default discovery URI to obtain
the link-format payload to register. the link-format payload to register.
The endpoint MAY include registration parameters in the POST request The endpoint MAY include registration parameters in the POST request
as per Section 6.3 as per Section 6.3.
The following example shows an endpoint using simple publishing, by The following example shows an endpoint using simple publishing, by
simply sending an empty POST to a resource directory. simply sending an empty POST to a resource directory.
Req:(to RD server from [ff02::1]) Req:(to RD server from [ff02::1])
POST coap://rd.example.com/.well-known/core?lt=6000 POST coap://rd.example.com/.well-known/core?lt=6000
Content-Format: 40 Content-Format: 40
payload: payload:
skipping to change at page 15, line 20 skipping to change at page 15, line 20
Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd*
Res: 2.05 Content Res: 2.05 Content
</rd>;rt="core.rd";ct=40, </rd>;rt="core.rd";ct=40,
</rd-lookup>;rt="core.rd-lookup";ct=40, </rd-lookup>;rt="core.rd-lookup";ct=40,
</rd-group>;rt="core.rd-group";ct=40 </rd-group>;rt="core.rd-group";ct=40
The following example shows the way of indicating that a client may The following example shows the way of indicating that a client may
request alternate content-formats. The Content-Format code attribute request alternate content-formats. The Content-Format code attribute
"ct" MAY include a space-separated sequence of Content-Format codes "ct" MAY include a space-separated sequence of Content-Format codes
as specified in [RFC7252], indicating that multiple content-formats as specified in Section 7.2.1 of [RFC7252], indicating that multiple
are available. The example below shows the required ct=40 content-formats are available. The example below shows the required
(application/link-format) indicated as well as a vendor-specific Content-Format 40 (application/link-format) indicated as well as a
content format (21225). more application-specific content format (picked as 65225 in this
example; this is in the experimental space, not an assigned value).
The base RD resource values /rd, /rd-lookup, and /rd-group are
example values.
Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd*
Res: 2.05 Content Res: 2.05 Content
</rd>;rt="core.rd";ct="40 21225", </rd>;rt="core.rd";ct="40 65225",
</rd-lookup>;rt="core.rd-lookup";ct="40 21225", </rd-lookup>;rt="core.rd-lookup";ct="40 65225",
</rd-group>;rt="core.rd-group";ct="40 21225" </rd-group>;rt="core.rd-group";ct="40 65225"
6.3. Registration 6.3. Registration
After discovering the location of an RD Function Set, an endpoint MAY After discovering the location of an RD Function Set, an endpoint MAY
register its resources using the registration interface. This register its resources using the registration interface. This
interface accepts a POST from an endpoint containing the list of interface accepts a POST from an endpoint containing the list of
resources to be added to the directory as the message payload in the resources to be added to the directory as the message payload in the
CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link- CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link-
format+json), or CBOR CoRE Link Format (application/link-format+cbor) format+json), or CBOR CoRE Link Format (application/link-format+cbor)
[I-D.ietf-core-links-json], along with query string parameters [I-D.ietf-core-links-json], along with query string parameters
skipping to change at page 16, line 5 skipping to change at page 16, line 8
optional. It is expected that other specifications will define optional. It is expected that other specifications will define
further parameters (see Section 12.4). The RD then creates a new further parameters (see Section 12.4). The RD then creates a new
resource or updates an existing resource in the RD and returns its resource or updates an existing resource in the RD and returns its
location. An endpoint MUST use that location when refreshing location. An endpoint MUST use that location when refreshing
registrations using this interface. Endpoint resources in the RD are registrations using this interface. Endpoint resources in the RD are
kept active for the period indicated by the lifetime parameter. The kept active for the period indicated by the lifetime parameter. The
endpoint is responsible for refreshing the entry within this period endpoint is responsible for refreshing the entry within this period
using either the registration or update interface. The registration using either the registration or update interface. The registration
interface MUST be implemented to be idempotent, so that registering interface MUST be implemented to be idempotent, so that registering
twice with the same endpoint parameter does not create multiple RD twice with the same endpoint parameter does not create multiple RD
entries. A new registration may be created at any time to supercede entries. A new registration may be created at any time to supersede
an existing registration, replacing the registration parameters and an existing registration, replacing the registration parameters and
links. links.
The registration request interface is specified as follows: The registration request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /{+rd}{?ep,d,et,lt,con} URI Template: /{+rd}{?ep,d,et,lt,con}
URI Template Variables: URI Template Variables:
rd := RD Function Set path (mandatory). This is the path of the rd := RD Function Set path (mandatory). This is the path of the
RD Function Set, as obtained from discovery. An RD SHOULD use RD Function Set, as obtained from discovery. The value "rd" is
the value "rd" for this variable whenever possible. recommended for this variable.
ep := Endpoint name (mandatory). The endpoint name is an ep := Endpoint name (mandatory). The endpoint name is an
identifier that MUST be unique within a domain. The maximum identifier that MUST be unique within a domain. The maximum
length of this parameter is 63 bytes. length of this parameter is 63 bytes.
d := Domain (optional). The domain to which this endpoint d := Domain (optional). The domain to which this endpoint
belongs. The maximum length of this parameter is 63 bytes. belongs. The maximum length of this parameter is 63 bytes.
When this parameter is elided, the RD MAY associate the When this parameter is elided, the RD MAY associate the
endpoint with a configured default domain. The domain value is endpoint with a configured default domain. The domain value is
needed to export the endpoint to DNS-SD (see Section 10). needed to export the endpoint to DNS-SD (see Section 10).
skipping to change at page 17, line 26 skipping to change at page 17, line 28
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following example shows an endpoint with the name "node1" The following example shows an endpoint with the name "node1"
registering two resources to an RD using this interface. The registering two resources to an RD using this interface. The
resulting location /rd/4521 is just an example of an RD generated location "/rd" is an example value of an RD base location.
location.
Req: POST coap://rd.example.com/rd?ep=node1 Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
Res: 2.01 Created Res: 2.01 Created
Location: /rd/4521 Location: /rd/4521
skipping to change at page 18, line 18 skipping to change at page 18, line 18
registration with an RD. To use the interface, the endpoint sends a registration with an RD. To use the interface, the endpoint sends a
POST request to the resource returned in the Location option in the POST request to the resource returned in the Location option in the
response to the first registration. response to the first registration.
An update MAY update the lifetime or context registration parameters An update MAY update the lifetime or context registration parameters
"lt", "con" as in Section 6.3 ) if they have changed since the last "lt", "con" as in Section 6.3 ) if they have changed since the last
registration or update. Parameters that have not changed SHOULD NOT registration or update. Parameters that have not changed SHOULD NOT
be included in an update. Adding parameters that have not changed be included in an update. Adding parameters that have not changed
increases the size of the message but does not have any other increases the size of the message but does not have any other
implications. Parameters MUST be included as query parameters in an implications. Parameters MUST be included as query parameters in an
update operation as in {registration}. update operation as in Section 6.3.
Upon receiving an update request, an RD MUST reset the timeout for Upon receiving an update request, an RD MUST reset the timeout for
that endpoint and update the scheme, IP address and port of the that endpoint and update the scheme, IP address and port of the
endpoint, using the source address of the update, or the context endpoint, using the source address of the update, or the context
("con") parameter if present. If the lifetime parameter "lt" is ("con") parameter if present. If the lifetime parameter "lt" is
included in the received update request, the RD MUST update the included in the received update request, the RD MUST update the
lifetime of the registration and set the timeout equal to the new lifetime of the registration and set the timeout equal to the new
lifetime. lifetime.
An update MAY optionally add or replace links for the endpoint by An update MAY optionally add or replace links for the endpoint by
skipping to change at page 19, line 36 skipping to change at page 19, line 36
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following example shows an endpoint updating its registration at The following example shows an endpoint updating its registration at
an RD using this interface. an RD using this interface with the example location value: /rd/4521.
Req: POST /rd/4521 Req: POST /rd/4521
Res: 2.04 Changed Res: 2.04 Changed
The following example shows an endpoint updating its registration The following example shows an endpoint updating its registration
with a new lifetime and context, changing an existing link, and with a new lifetime and context, changing an existing link, and
adding a new link using this interface. With the initial adding a new link using this interface with the example location
registration the client set the following values: value /rd/4521. With the initial registration the client set the
following values:
o lifetime (lt)=500 o lifetime (lt)=500
o context (con)=coap://local-proxy-old.example.com:5683 o context (con)=coap://local-proxy-old.example.com:5683
o resource= </sensors/temp>;ct=41;rt="foobar";if="sensor" o resource= </sensors/temp>;ct=41;rt="foobar";if="sensor"
Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683" Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683"
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-f";if="sensor", </sensors/temp>;ct=41;rt="temperature-f";if="sensor",
skipping to change at page 20, line 49 skipping to change at page 20, line 49
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following examples shows successful removal of the endpoint from The following examples shows successful removal of the endpoint from
the RD. the RD with example location value /rd/4521.
Req: DELETE /rd/4521 Req: DELETE /rd/4521
Res: 2.02 Deleted Res: 2.02 Deleted
6.6. Read Endpoint Links 6.6. Read Endpoint Links
Some endpoints may wish to manage their links as a collection, and Some endpoints may wish to manage their links as a collection, and
may need to read the current set of links in order to determine link may need to read the current set of links in order to determine link
maintenance operations. maintenance operations.
skipping to change at page 22, line 5 skipping to change at page 22, line 5
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following examples show successful read of the endpoint links The following examples show successful read of the endpoint links
from the RD. from the RD, with example location value /rd/4521.
Req: GET /rd/4521 Req: GET /rd/4521
Res: 2.01 Content Res: 2.01 Content
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
6.7. Update Endpoint Links 6.7. Update Endpoint Links
skipping to change at page 23, line 33 skipping to change at page 23, line 33
Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource
does not exist (e.g. may have expired). does not exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following examples show an endpoint adding </sensors/humid>, The following examples show an endpoint adding </sensors/humid>,
modifying </sensors/temp>, and removing </sensors/light> links in RD modifying </sensors/temp>, and removing </sensors/light> links in RD
using the Update Endpoint Links function. using the Update Endpoint Links function with the example location
value /rd/4521.
The following example shows an EP adding the link </sensors/ The following example shows an EP adding the link </sensors/
humid>;ct=41;rt="humid-s";if="sensor" to the collection of links at humid>;ct=41;rt="humid-s";if="sensor" to the collection of links at
the location /rd/4521. the location /rd/4521.
Req: PATCH /rd/4521 Req: PATCH /rd/4521
Payload: Payload:
[{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}] [{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}]
Content-Format: Content-Format:
application/merge-patch+json application/merge-patch+json
Res: 2.04 Changed Res: 2.04 Changed
The following example shows an EP modifying all links at the location The following example shows an EP modifying all links at the example
/rd/4521 which are identified by href="/sensors/temp", from the location /rd/4521 which are identified by href="/sensors/temp", from
initial link-value of </sensors/temp>;rt="temperature" to the new the initial link-value of </sensors/temp>;rt="temperature" to the new
link-value </sensors/temp>;rt="temperature-c";if="sensor" by changing link-value </sensors/temp>;rt="temperature-c";if="sensor" by changing
the value of the link attribute "rt" and adding the link attribute the value of the link attribute "rt" and adding the link attribute
if="sensor" using the PATCH operation with the supplied merge- if="sensor" using the PATCH operation with the supplied merge-
patch+json document payload. patch+json document payload.
Req: PATCH /rd/4521?href="/sensors/temp" Req: PATCH /rd/4521?href="/sensors/temp"
Payload: Payload:
{"rt": "temperature-c", "if": "sensor"}, {"rt": "temperature-c", "if": "sensor"},
Content-Format: Content-Format:
application/merge-patch+json application/merge-patch+json
Res: 2.04 Changed Res: 2.04 Changed
This example shows an EP removing all links at the location /rd/4521 This example shows an EP removing all links at the example location
which are identified by href="/sensors/light". /rd/4521 which are identified by href="/sensors/light".
Req: PATCH /rd/4521?href="/sensors/light" Req: PATCH /rd/4521?href="/sensors/light"
Payload: Payload:
{null} {null}
Content-Format: Content-Format:
application/merge-patch+json application/merge-patch+json
Res: 2.04 Changed Res: 2.04 Changed
skipping to change at page 25, line 26 skipping to change at page 25, line 26
Interaction: CT -> RD Interaction: CT -> RD
Method: POST Method: POST
URI Template: /{+rd-group}{?gp,d,con} URI Template: /{+rd-group}{?gp,d,con}
URI Template Variables: URI Template Variables:
rd-group := RD Group Function Set path (mandatory). This is the rd-group := RD Group Function Set path (mandatory). This is the
path of the RD Group Function Set. An RD SHOULD use the value path of the RD Group Function Set. The value "rd-group" is
"rd-group" for this variable whenever possible. recommended for this variable.
gp := Group Name (mandatory). The name of the group to be gp := Group Name (mandatory). The name of the group to be
created or replaced, unique within that domain. The maximum created or replaced, unique within that domain. The maximum
length of this parameter is 63 bytes. length of this parameter is 63 bytes.
d := Domain (optional). The domain to which this group belongs. d := Domain (optional). The domain to which this group belongs.
The maximum length of this parameter is 63 bytes. Optional. The maximum length of this parameter is 63 bytes. Optional.
When this parameter is elided, the RD MAY associate the When this parameter is elided, the RD MAY associate the
endpoint with a configured default domain. The domain value is endpoint with a configured default domain. The domain value is
needed to export the endpoint to DNS-SD (see Section 10) needed to export the endpoint to DNS-SD (see Section 10)
skipping to change at page 26, line 23 skipping to change at page 26, line 23
Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not
registered in the RD (e.g. may have expired). registered in the RD (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following example shows an EP registering a group with the name The following example shows an EP registering a group with the name
"lights" which has two endpoints to an RD using this interface. The "lights" which has two endpoints to an RD using this interface. The
resulting location /rd-group/12 is just an example of an RD generated base location value /rd-group is an example of an RD base location.
group location.
Req: POST coap://rd.example.com/rd-group?gp=lights Req: POST coap://rd.example.com/rd-group?gp=lights
Content-Format: 40 Content-Format: 40
Payload: Payload:
<>;ep="node1", <>;ep="node1",
<>;ep="node2" <>;ep="node2"
Res: 2.01 Created Res: 2.01 Created
Location: /rd-group/12 Location: /rd-group/12
skipping to change at page 27, line 31 skipping to change at page 27, line 28
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following examples shows successful removal of the group from the The following examples shows successful removal of the group from the
RD. RD with the example location value /rd-group/12.
Req: DELETE /rd-group/12 Req: DELETE /rd-group/12
Res: 2.02 Deleted Res: 2.02 Deleted
8. RD Lookup Function Set 8. RD Lookup Function Set
In order for an RD to be used for discovering resources registered In order for an RD to be used for discovering resources registered
with it, a lookup interface can be provided using this function set. with it, a lookup interface can be provided using this function set.
This lookup interface is defined as a default, and it is assumed that This lookup interface is defined as a default, and it is assumed that
skipping to change at page 28, line 16 skipping to change at page 28, line 14
Each endpoint and resource lookup result returns respectively the Each endpoint and resource lookup result returns respectively the
scheme (IP address and port) followed by the path part of the URI of scheme (IP address and port) followed by the path part of the URI of
every endpoint and resource inside angle brackets ("<>") and followed every endpoint and resource inside angle brackets ("<>") and followed
by the other parameters. by the other parameters.
The target of these links SHOULD be the actual location of the The target of these links SHOULD be the actual location of the
domain, endpoint or resource, but MAY be an intermediate proxy e.g. domain, endpoint or resource, but MAY be an intermediate proxy e.g.
in the case of an HTTP lookup interface for CoAP endpoints. in the case of an HTTP lookup interface for CoAP endpoints.
The domain lookup returns every lookup domain with a "/rd" value The domain lookup returns every lookup domain with a base RD resource
encapsulated within angle brackets. value (e.g. "/rd") encapsulated within angle brackets.
In case that a group does not implement any multicast address, the In case that a group does not implement any multicast address, the
group lookup returns every group lookup with a "/rd-group" value group lookup returns every group lookup with a group base resource
encapsulated within angle brackets. Otherwise, the group lookup value encapsulated within angle brackets (e.g. "/rd/look-up").
returns the multicast address of the group inside angle brackets. Otherwise, the group lookup returns the multicast address of the
group inside angle brackets.
Using the Accept Option, the requester can control whether this list Using the Accept Option, the requester can control whether this list
is returned in CoRE Link Format ("application/link-format", default) is returned in CoRE Link Format ("application/link-format", default)
or its alternate content-formats ("application/link-format+json" or or its alternate content-formats ("application/link-format+json" or
"application/link-format+cbor"). "application/link-format+cbor").
The page and count parameters are used to obtain lookup results in The page and count parameters are used to obtain lookup results in
specified increments using pagination, where count specifies how many specified increments using pagination, where count specifies how many
links to return and page specifies which subset of links organized in links to return and page specifies which subset of links organized in
sequential pages , each containing 'count' links, starting with link sequential pages, each containing 'count' links, starting with link
zero and page zero. Thus, specifying count of 10 and page of 0 will zero and page zero. Thus, specifying count of 10 and page of 0 will
return the first 10 links in the result set (links 0-9). Count = 10 return the first 10 links in the result set (links 0-9). Count = 10
and page = 1 will return the next 'page' containing links 10-19, and and page = 1 will return the next 'page' containing links 10-19, and
so on. so on.
Multiple query parameters MAY be included in a lookup, all included Multiple query parameters MAY be included in a lookup, all included
parameters MUST match for a resource to be returned. The parameters MUST match for a resource to be returned. The
character'*' MAY be included at the end of a parameter value as a character'*' MAY be included at the end of a parameter value as a
wildcard operator. wildcard operator.
skipping to change at page 29, line 6 skipping to change at page 29, line 4
the registered attributes and relations. In addition, this interface the registered attributes and relations. In addition, this interface
MAY be used with queries that specify domains, endpoints, and groups. MAY be used with queries that specify domains, endpoints, and groups.
For example, a domain lookup filtering on groups would return a list For example, a domain lookup filtering on groups would return a list
of domains that contain the specified groups. An endpoint lookup of domains that contain the specified groups. An endpoint lookup
filtering on groups would return a list of endpoints that are in the filtering on groups would return a list of endpoints that are in the
specified groups. specified groups.
The lookup interface is specified as follows: The lookup interface is specified as follows:
Interaction: Client -> RD Interaction: Client -> RD
Method: GET Method: GET
URI Template: /{+rd-lookup-base}/{lookup- URI Template: /{+rd-lookup-base}/{lookup-
type}{?d,ep,gp,et,rt,page,count,resource-param} type}{?d,ep,gp,et,rt,page,count,resource-param}
URI Template Variables: URI Template Variables:
rd-lookup-base := RD Lookup Function Set path (mandatory). This rd-lookup-base := RD Lookup Function Set path (mandatory). This
is the path of the RD Lookup Function Set. An RD SHOULD use the is the path of the RD Lookup Function Set. The recommended
value "rd-lookup" for this variable whenever possible. value for this variable is: "rd-lookup".
lookup-type := ("d", "ep", "res", "gp") (mandatory) This variable lookup-type := ("d", "ep", "res", "gp") (mandatory) This variable
is used to select the kind of lookup to perform (domain, is used to select the kind of lookup to perform (domain,
endpoint, resource, or group). endpoint, resource, or group).
ep := Endpoint name (optional). Used for endpoint, group and ep := Endpoint name (optional). Used for endpoint, group and
resource lookups. resource lookups.
d := Domain (optional). Used for domain, group, endpoint and d := Domain (optional). Used for domain, group, endpoint and
resource lookups. resource lookups.
skipping to change at page 30, line 38 skipping to change at page 30, line 38
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The examples in this section assume a CoAP host with IP address The examples in this section assume a CoAP host with IP address
FDFD::123 and a default CoAP port 61616. HTTP hosts are possible and FDFD::123 and a default CoAP port 61616. HTTP hosts are possible and
do not change the nature of the examples.\ do not change the nature of the examples.\
The following example shows a client performing a resource lookup: The following example shows a client performing a resource lookup
with the example look-up location /rd-lookup/:
Req: GET /rd-lookup/res?rt=temperature Req: GET /rd-lookup/res?rt=temperature
Res: 2.05 Content Res: 2.05 Content
<coap://[FDFD::123]:61616/temp>;rt="temperature" <coap://[FDFD::123]:61616/temp>;rt="temperature"
The following example shows a client performing an endpoint type The following example shows a client performing an endpoint type
lookup: lookup:
Req: GET /rd-lookup/ep?et=power-node Req: GET /rd-lookup/ep?et=power-node
skipping to change at page 32, line 30 skipping to change at page 32, line 30
<coap://[FDFD::123]:61616/res/9>;rt=sensor;ct=60 <coap://[FDFD::123]:61616/res/9>;rt=sensor;ct=60
9. New Link-Format Attributes 9. New Link-Format Attributes
When using the CoRE Link Format to describe resources being When using the CoRE Link Format to describe resources being
discovered by or posted to a resource directory service, additional discovered by or posted to a resource directory service, additional
information about those resources is useful. This specification information about those resources is useful. This specification
defines the following new attributes for use in the CoRE Link Format defines the following new attributes for use in the CoRE Link Format
[RFC6690]: [RFC6690]:
link-extension = ( "ins" "=" quoted-string ) ; Max 63 bytes link-extension = ( "ins" "=" (ptoken | quoted-string) )
; The token or string is max 63 bytes
link-extension = ( "exp" ) link-extension = ( "exp" )
9.1. Resource Instance attribute 'ins' 9.1. Resource Instance attribute 'ins'
The Resource Instance "ins" attribute is an identifier for this The Resource Instance "ins" attribute is an identifier for this
resource, which makes it possible to distinguish it from other resource, which makes it possible to distinguish it from other
similar resources. This attribute is similar in use to the similar resources. This attribute is similar in use to the
<Instance> portion of a DNS-SD record (see Section 10.1, and SHOULD <Instance> portion of a DNS-SD record (see Section 10.1, and SHOULD
be unique across resources with the same Resource Type attribute in be unique across resources with the same Resource Type attribute in
the domain it is used. A Resource Instance might be a descriptive the domain it is used. A Resource Instance might be a descriptive
skipping to change at page 36, line 19 skipping to change at page 36, line 19
10.6. Importing resource links into DNS-SD 10.6. Importing resource links into DNS-SD
Assuming the ability to query a Resource Directory or multicast a GET Assuming the ability to query a Resource Directory or multicast a GET
(?exp) over the local link, CoAP resource discovery may be used to (?exp) over the local link, CoAP resource discovery may be used to
populate the DNS-SD database in an automated fashion. CoAP resource populate the DNS-SD database in an automated fashion. CoAP resource
descriptions (links) can be exported to DNS-SD for exposure to descriptions (links) can be exported to DNS-SD for exposure to
service discovery by using the Resource Instance attribute as the service discovery by using the Resource Instance attribute as the
basis for a unique service name, composed with the Resource Type as basis for a unique service name, composed with the Resource Type as
the <ServiceType>, and registered in the correct <Domain>. The agent the <ServiceType>, and registered in the correct <Domain>. The agent
responsible for exporting records to the DNS zone file SHOULD be responsible for exporting records to the DNS zone file SHOULD be
authenticated to the DNS server. The following example shows an authenticated to the DNS server. The following example, using the
agent discovering a resource to be exported: example lookup location /rd-lookup, shows an agent discovering a
resource to be exported:
Req: GET /rd-lookup/res?exp Req: GET /rd-lookup/res?exp
Res: 2.05 Content Res: 2.05 Content
<coap://[FDFD::1234]:5683/light/1>; <coap://[FDFD::1234]:5683/light/1>;
exp;rt="dali.light";ins="Spot"; exp;rt="dali.light";ins="Spot";
d="office";ep="node1" d="office";ep="node1"
The agent subsequently registers the following DNS-SD RRs, assuming a The agent subsequently registers the following DNS-SD RRs, assuming a
zone name "example.com" prefixed with "office": zone name "example.com" prefixed with "office":
skipping to change at page 39, line 38 skipping to change at page 39, line 38
| | | | another Resource Directory | | | | | another Resource Directory |
+-----------+-------+---------------+-------------------------------+ +-----------+-------+---------------+-------------------------------+
Table 1: RD Parameters Table 1: RD Parameters
The IANA policy for future additions to the sub-registry is "Expert The IANA policy for future additions to the sub-registry is "Expert
Review" as described in [RFC5226]. Review" as described in [RFC5226].
13. Examples 13. Examples
Examples are added here.
13.1. Lighting Installation 13.1. Lighting Installation
This example shows a simplified lighting installation which makes use This example shows a simplified lighting installation which makes use
of the Resource Directory (RD) with a CoAP interface to facilitate of the Resource Directory (RD) with a CoAP interface to facilitate
the installation and start up of the application code in the lights the installation and start up of the application code in the lights
and sensors. In particular, the example leads to the definition of a and sensors. In particular, the example leads to the definition of a
group and the enabling of the corresponding multicast address. No group and the enabling of the corresponding multicast address. No
conclusions must be drawn on the realization of actual installation conclusions must be drawn on the realization of actual installation
or naming procedures, because the example only "emphasizes" some of or naming procedures, because the example only "emphasizes" some of
the issues that may influence the use of the RD and does not pretend the issues that may influence the use of the RD and does not pretend
to be normative. to be normative. The example uses the recommended values for the
base resources: "/rd", "/rd-lookup", and "/rd-group".
13.1.1. Installation Characteristics 13.1.1. Installation Characteristics
The example assumes that the installation is managed. That means The example assumes that the installation is managed. That means
that a Commissioning Tool (CT) is used to authorize the addition of that a Commissioning Tool (CT) is used to authorize the addition of
nodes, name them, and name their services. The CT can be connected nodes, name them, and name their services. The CT can be connected
to the installation in many ways: the CT can be part of the to the installation in many ways: the CT can be part of the
installation network, connected by WiFi to the installation network, installation network, connected by WiFi to the installation network,
or connected via GPRS link, or other method. or connected via GPRS link, or other method.
skipping to change at page 43, line 46 skipping to change at page 43, line 46
[RFC7390]. [RFC7390].
Req: POST //[FDFD::ABCD:1]/coap-group Req: POST //[FDFD::ABCD:1]/coap-group
Content-Format: application/coap-group+json Content-Format: application/coap-group+json
{ "a": "[FF05::1]", { "a": "[FF05::1]",
"n": "grp_R2-4-015"} "n": "grp_R2-4-015"}
Res: 2.01 Created Res: 2.01 Created
Location-Path: /coap-group/1 Location-Path: /coap-group/1
Dependent on the situation only the address ,"a", or the name, "n", Dependent on the situation, only the address, "a", or the name, "n",
is specified in the coap-group resource. is specified in the coap-group resource.
13.1.3. DNS entries 13.1.3. DNS entries
It may be profitable to discover the light groups for applications, It may be profitable to discover the light groups for applications,
which are unaware ot the existence of the RD. An agent needs to which are unaware ot the existence of the RD. An agent needs to
query the RD to return all groups which are exported to be inserted query the RD to return all groups which are exported to be inserted
into DNS. into DNS.
Req: GET /rd-lookup/gp?exp Req: GET /rd-lookup/gp?exp
skipping to change at page 49, line 7 skipping to change at page 49, line 7
Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders
Brandt, Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have Brandt, Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have
provided helpful comments, discussions and ideas to improve and shape provided helpful comments, discussions and ideas to improve and shape
this document. Section 9 is based on an earlier draft by Kerry Lynn. this document. Section 9 is based on an earlier draft by Kerry Lynn.
Zach would also like to thank his colleagues from the EU FP7 SENSEI Zach would also like to thank his colleagues from the EU FP7 SENSEI
project, where many of the resource directory concepts were project, where many of the resource directory concepts were
originally developed. originally developed.
15. Changelog 15. Changelog
changes from -08 to -09
o clarified the "example use" of the base RD resource values /rd,
/rd-lookup, and /rd-group.
o changed "ins" ABNF notation.
o various editorial improvements, including in examples
o clarifications for RDAO
changes from -07 to -08 changes from -07 to -08
o removed link target value returned from domain and group lookup o removed link target value returned from domain and group lookup
types types
o Maximum length of domain parameter 63 bytes for consistency with o Maximum length of domain parameter 63 bytes for consistency with
group group
o removed option for simple POST of link data, don't require a o removed option for simple POST of link data, don't require a
.well-known/core resource to accept POST data and handle it in a .well-known/core resource to accept POST data and handle it in a
skipping to change at page 52, line 27 skipping to change at page 52, line 40
during updates. during updates.
o Changed the lookup interface to accept endpoint and Domain as o Changed the lookup interface to accept endpoint and Domain as
query string parameters to control the scope of a lookup. query string parameters to control the scope of a lookup.
16. References 16. References
16.1. Normative References 16.1. Normative References
[I-D.ietf-core-links-json] [I-D.ietf-core-links-json]
Li, K., Rahman, A., and D. Bormann, "Representing CoRE Li, K., Rahman, A., and C. Bormann, "Representing CoRE
Formats in JSON and CBOR", draft-ietf-core-links-json-05 Formats in JSON and CBOR", draft-ietf-core-links-json-06
(work in progress), April 2016. (work in progress), July 2016.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>. <http://www.rfc-editor.org/info/rfc3986>.
 End of changes. 39 change blocks. 
61 lines changed or deleted 87 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/