draft-ietf-core-resource-directory-10.txt   draft-ietf-core-resource-directory-11.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: September 14, 2017 SmartThings Expires: January 4, 2018 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
March 13, 2017 C. Amsuess, Ed.
Energy Harvesting Solutions
July 03, 2017
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-10 draft-ietf-core-resource-directory-11
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
skipping to change at page 1, line 44 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at 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 September 14, 2017. This Internet-Draft will expire on January 4, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 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
skipping to change at page 2, line 25 skipping to change at page 2, line 25
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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5
3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6 3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Use Case: Home and Building Automation . . . . . . . . . 7 3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7 3.3. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 7
4. Finding a Resource Directory . . . . . . . . . . . . . . . . 8 3.4. Use Case: Home and Building Automation . . . . . . . . . 8
4.1. Resource Directory Address Option (RDAO) . . . . . . . . 9 3.5. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 8
5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 10 4. Finding a Resource Directory . . . . . . . . . . . . . . . . 9
5.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 11 4.1. Resource Directory Address Option (RDAO) . . . . . . . . 10
5.2. Base URI Discovery . . . . . . . . . . . . . . . . . . . 11 5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 11
5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 13 5.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 12
5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 16 5.2. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 12
5.3.2. Simple publishing to Resource Directory Server . . . 17 5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 14
5.3.3. Third-party registration . . . . . . . . . . . . . . 17 5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 17
5.3.4. Plurality of link references in a Registration . . . 18 5.3.2. Simple publishing to Resource Directory Server . . . 18
5.4. Operations on the Registration Resource . . . . . . . . . 18 5.3.3. Third-party registration . . . . . . . . . . . . . . 18
5.4.1. Registration Update . . . . . . . . . . . . . . . . . 19 5.3.4. Plurality of link references in a Registration . . . 19
5.4.2. Registration Removal . . . . . . . . . . . . . . . . 21 5.4. Operations on the Registration Resource . . . . . . . . . 19
5.4.3. Read Endpoint Links . . . . . . . . . . . . . . . . . 22 5.4.1. Registration Update . . . . . . . . . . . . . . . . . 20
5.4.4. Update Endpoint Links . . . . . . . . . . . . . . . . 23 5.4.2. Registration Removal . . . . . . . . . . . . . . . . 22
6. RD Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.4.3. Read Endpoint Links . . . . . . . . . . . . . . . . . 23
6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 27 5.4.4. Update Endpoint Links . . . . . . . . . . . . . . . . 24
6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 29 6. RD Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 28
8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 30
8.1. Endpoint Identification and Authentication . . . . . . . 35 7. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 35 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36
8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 36 8.1. Endpoint Identification and Authentication . . . . . . . 36
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 36
9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 36 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 37
9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 36
9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 36 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 37 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 37
10.1. Lighting Installation . . . . . . . . . . . . . . . . . 37 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 37
10.1.1. Installation Characteristics . . . . . . . . . . . . 38 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 37
10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 39 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 38
10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 42 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 38
10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 42 10.1.1. Installation Characteristics . . . . . . . . . . . . 39
10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 44 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 40
10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 45 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 43
10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 46 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 43
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 45
12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 46 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 46
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 47
13.1. Normative References . . . . . . . . . . . . . . . . . . 50 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
13.2. Informative References . . . . . . . . . . . . . . . . . 51 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 51
13.1. Normative References . . . . . . . . . . . . . . . . . . 51
13.2. Informative References . . . . . . . . . . . . . . . . . 52
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53
1. Introduction 1. Introduction
The work on Constrained RESTful Environments (CoRE) aims at realizing The work on Constrained RESTful Environments (CoRE) aims at realizing
the REST architecture in a suitable form for the most constrained the REST architecture in a suitable form for the most constrained
nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and
networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M)
applications such as smart energy and building automation. applications such as smart energy and building automation.
The discovery of resources offered by a constrained server is very The discovery of resources offered by a constrained server is very
skipping to change at page 5, line 20 skipping to change at page 5, line 21
Commissioning Tool (CT) is a device that assists during the Commissioning Tool (CT) is a device that assists during the
installation of the network by assigning values to parameters, installation of the network by assigning values to parameters,
naming endpoints and groups, or adapting the installation to the naming endpoints and groups, or adapting the installation to the
needs of the applications. needs of the applications.
RDAO RDAO
Resource Directory Address Option. Resource Directory Address Option.
3. Architecture and Use Cases 3. Architecture and Use Cases
3.1. Principles
The Resource Directory is primarily a tool to make discovery
operations more efficient than querying /.well-known/core on all
connected device, or across boundaries that would be limiting those
operations.
It provides a cache (in the high-level sense, not as defined in
[RFC7252]/[RFC2616]) of data that could otherwise only be obtained by
directly querying the /.well-known/core resource on the target
device, or by accessing those resources with a multicast request.
From that, it follows that no information should be stored in the
resource directory that cannot be discovered from querying the
described device's /.well-known/core resource directly.
It also follows that data in the resource directory can only be
provided by the device whose descriptions are cached or a dedicated
Commissioning Tool (CT). These CTs are thought to act on behalf
agents too constrained, or generally unable, to present that
information themselves. No other client can modify data in the
resource directory or even expect those changes to propagate back to
its source.
3.2. Architecture
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
(called resource directory registration entries), and for clients to (called resource directory registration entries), and for clients to
lookup resources from the RD or maintain groups. Endpoints lookup resources from the RD or maintain groups. Endpoints
themselves can also act as clients. An RD can be logically segmented themselves can also act as clients. An RD can be logically segmented
skipping to change at page 6, line 43 skipping to change at page 7, line 24
| Endpoint | <-- Name, Scheme, IP, Port | Endpoint | <-- Name, Scheme, IP, Port
+------------+ +------------+
| |
| |
+------------+ +------------+
| Resource | <-- Target, Parameters | Resource | <-- Target, Parameters
+------------+ +------------+
Figure 2: The resource directory information hierarchy. Figure 2: The resource directory information hierarchy.
3.1. Use Case: Cellular M2M 3.3. Use Case: Cellular M2M
Over the last few years, mobile operators around the world have Over the last few years, mobile operators around the world have
focused on development of M2M solutions in order to expand the focused on development of M2M solutions in order to expand the
business to the new type of users: machines. The machines are business to the new type of users: machines. The machines are
connected directly to a mobile network using an appropriate embedded connected directly to a mobile network using an appropriate embedded
air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short
and wide range wireless interfaces. From the system design point of and wide range wireless interfaces. From the system design point of
view, the ambition is to design horizontal solutions that can enable view, the ambition is to design horizontal solutions that can enable
utilization of machines in different applications depending on their utilization of machines in different applications depending on their
current availability and capabilities as well as application current availability and capabilities as well as application
skipping to change at page 7, line 33 skipping to change at page 8, line 13
stored in the RD. The users, for example mobile applications for stored in the RD. The users, for example mobile applications for
environment monitoring, contact the RD, look up the endpoints capable environment monitoring, contact the RD, look up the endpoints capable
of providing information about the environment using appropriate set of providing information about the environment using appropriate set
of link parameters, obtain information on how to contact them (URLs of link parameters, obtain information on how to contact them (URLs
of the proxy server) and then initiate interaction to obtain of the proxy server) and then initiate interaction to obtain
information that is finally processed, displayed on the screen and information that is finally processed, displayed on the screen and
usually stored in a database. Similarly, fleet management systems usually stored in a database. Similarly, fleet management systems
provide the appropriate link parameters to the RD to look up for EPs provide the appropriate link parameters to the RD to look up for EPs
deployed on the vehicles the application is responsible for. deployed on the vehicles the application is responsible for.
3.2. Use Case: Home and Building Automation 3.4. Use Case: Home and Building Automation
Home and commercial building automation systems can benefit from the Home and commercial building automation systems can benefit from the
use of M2M web services. The discovery requirements of these use of M2M web services. The discovery requirements of these
applications are demanding. Home automation usually relies on run- applications are demanding. Home automation usually relies on run-
time discovery to commission the system, whereas in building time discovery to commission the system, whereas in building
automation a combination of professional commissioning and run-time automation a combination of professional commissioning and run-time
discovery is used. Both home and building automation involve peer- discovery is used. Both home and building automation involve peer-
to-peer interactions between endpoints, and involve battery-powered to-peer interactions between endpoints, and involve battery-powered
sleeping devices. sleeping devices.
3.3. Use Case: Link Catalogues 3.5. Use Case: Link Catalogues
Resources may be shared through data brokers that have no knowledge Resources may be shared through data brokers that have no knowledge
beforehand of who is going to consume the data. Resource Directory beforehand of who is going to consume the data. Resource Directory
can be used to hold links about resources and services hosted can be used to hold links about resources and services hosted
anywhere to make them discoverable by a general class of anywhere to make them discoverable by a general class of
applications. applications.
For example, environmental and weather sensors that generate data for For example, environmental and weather sensors that generate data for
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
skipping to change at page 11, line 21 skipping to change at page 12, line 21
Resource Directory implementations using this specification MUST Resource Directory implementations using this specification MUST
support the application/link-format content format (ct=40). support the application/link-format content format (ct=40).
Resource Directories implementing this specification MAY support Resource Directories implementing this specification MAY support
additional content formats. additional content formats.
Any additional content format supported by a Resource Directory Any additional content format supported by a Resource Directory
implementing this specification MUST have an equivalent serialization implementing this specification MUST have an equivalent serialization
in the application/link-format content format. in the application/link-format content format.
5.2. Base URI Discovery 5.2. URI Discovery
Before an endpoint can make use of an RD, it must first know the RD's Before an endpoint can make use of an RD, it must first know the RD's
address and port, and the base URI information for its REST API. address and port, and the URI path information for its REST APIs.
This section defines discovery of the RD and its base URI using the This section defines discovery of the RD and its URIs using the well-
well-known interface of the CoRE Link Format [RFC6690]. It is known interface of the CoRE Link Format [RFC6690]. It is however
however expected that RDs will also be discoverable via other methods expected that RDs will also be discoverable via other methods
depending on the deployment. depending on the deployment.
Discovery of the RD base URI is performed by sending either a Discovery of the RD registration URI path is performed by sending
multicast or unicast GET request to "/.well-known/core" and including either a multicast or unicast GET request to "/.well-known/core" and
a Resource Type (rt) parameter [RFC6690] with the value "core.rd" in including a Resource Type (rt) parameter [RFC6690] with the value
the query string. Likewise, a Resource Type parameter value of "core.rd" in the query string. Likewise, a Resource Type parameter
"core.rd-lookup*" is used to discover the base URI for RD Lookup value of "core.rd-lookup*" is used to discover the URIs for RD Lookup
operations, and "core.gp" is used to discover the base URI for RD operations, and "core.gp" is used to discover the URI path for RD
Group operations. Upon success, the response will contain a payload Group operations. Upon success, the response will contain a payload
with a link format entry for each RD function discovered, indicating with a link format entry for each RD function discovered, indicating
the base URI of the RD function returned and the corresponding the URI path of the RD function returned and the corresponding
Resource Type. When performing multicast discovery, the multicast IP Resource Type. When performing multicast discovery, the multicast IP
address used will depend on the scope required and the multicast address used will depend on the scope required and the multicast
capabilities of the network. capabilities of the network.
A Resource Directory MAY provide hints about the content-formats it A Resource Directory MAY provide hints about the content-formats it
supports in the links it exposes or registers, using the "ct" link supports in the links it exposes or registers, using the "ct" link
attribute, as shown in the example below. Clients MAY use these attribute, as shown in the example below. Clients MAY use these
hints to select alternate content-formats for interaction with the hints to select alternate content-formats for interaction with the
Resource Directory. Resource Directory.
skipping to change at page 12, line 33 skipping to change at page 13, line 33
"core.rd-group" or "core.rd*" "core.rd-group" or "core.rd*"
Content-Format: application/link-format (if any) Content-Format: application/link-format (if any)
Content-Format: application/link-format+json (if any) Content-Format: application/link-format+json (if any)
Content-Format: application/link-format+cbor (if any) Content-Format: application/link-format+cbor (if any)
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.05 "Content" with an application/link-format, Success: 2.05 "Content" or 200 "OK" with an application/link-format,
application/link-format+json, or application/link-format+cbor application/link-format+json, or application/link-format+cbor
payload containing one or more matching entries for the RD payload containing one or more matching entries for the RD
resource. resource.
Failure: 4.04 "Not Found" is returned in case no matching entry is Failure: 4.04 "Not Found" or 404 "Not Found" is returned in case no
found for a unicast request. matching entry is found for a unicast request.
Failure: 4.00 "Bad Request" is returned in case of a malformed Failure: 4.00 "Bad Request" or 400 "Bad Request" is returned in case
request for a unicast request. of a malformed request for a unicast request.
Failure: No error response to a multicast request. Failure: No error response to a multicast request.
HTTP support : YES (Unicast only) HTTP support : YES (Unicast only)
The following example shows an endpoint discovering an RD using this The following example shows an endpoint discovering an RD using this
interface, thus learning that the base RD resource is, in this interface, thus learning that the RD registration resource is, in
example, at /rd and that the content-format delivered by the server this example, at /rd, and that the content-format delivered by the
hosting the resource is application/link-format (ct=40). Note that server hosting the resource is application/link-format (ct=40). Note
it is up to the RD to choose its base RD resource, although that it is up to the RD to choose its RD resource paths.
diagnostics and debugging is facilitated by using the base paths
specified here where possible.
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/ep>;rt="core.rd-lookup-ep";ct=40, </rd-lookup/ep>;rt="core.rd-lookup-ep";ct=40,
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40", </rd-lookup/res>;rt="core.rd-lookup-res";ct=40,
</rd-lookup/gp>;rt="core.rd-lookup-gp";ct=40,
</rd-lookup/d>;rt="core.rd-lookup-d";ct=40,
</rd-group>;rt="core.rd-group";ct=40 </rd-group>;rt="core.rd-group";ct=40
Figure 4: Example discovery exchange
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 Section 7.2.1 of [RFC7252], indicating that multiple as specified in Section 7.2.1 of [RFC7252], indicating that multiple
content-formats are available. The example below shows the required content-formats are available. The example below shows the required
Content-Format 40 (application/link-format) indicated as well as a Content-Format 40 (application/link-format) indicated as well as a
more application-specific content format (picked as 65225 in this more application-specific content format (picked as 65225 in this
example; this is in the experimental space, not an assigned value). example; this is in the experimental space, not an assigned value).
The base RD resource values /rd, /rd-lookup, and /rd-group are The RD resource paths /rd, /rd-lookup, and /rd-group are example
example values. values. This server only implements some of the interfaces described
in this document.
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 65225", </rd>;rt="core.rd";ct="40 65225",
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40 65225", </rd-lookup/res>;rt="core.rd-lookup-res";ct="40 65225",
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 65225", </rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 65225",
</rd-group>;rt="core.rd-group";ct="40 65225" </rd-group>;rt="core.rd-group";ct="40 65225"
5.3. Registration 5.3. Registration
skipping to change at page 14, line 17 skipping to change at page 15, line 21
entries. A new registration may be created at any time to supersede 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 Base URI path (mandatory). This is the path of the RD, rd := RD registration URI (mandatory). This is the location of
as obtained from discovery. The value "rd" is recommended for the RD, as obtained from discovery.
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. endpoint with a configured default domain.
skipping to change at page 14, line 45 skipping to change at page 15, line 48
endpoint. This parameter SHOULD be less than 63 bytes. endpoint. This parameter SHOULD be less than 63 bytes.
lt := Lifetime (optional). Lifetime of the registration in lt := Lifetime (optional). Lifetime of the registration in
seconds. Range of 60-4294967295. If no lifetime is included seconds. Range of 60-4294967295. If no lifetime is included
in the initial registration, a default value of 86400 (24 in the initial registration, a default value of 86400 (24
hours) SHOULD be assumed. If the lt parameter is not included hours) SHOULD be assumed. If the lt parameter is not included
in a registration refresh or update operation, the most in a registration refresh or update operation, the most
recently supplied value SHALL be re-used. recently supplied value SHALL be re-used.
con := Context (optional). This parameter sets the scheme, con := Context (optional). This parameter sets the scheme,
address and port at which this server is available in the form address, port and path at which this server is available in the
scheme://host:port/path. In the absence of this parameter the form scheme://host:port/path. In the absence of this parameter
scheme of the protocol, source address and source port of the the scheme of the protocol, source address and source port of
register request are assumed. This parameter is mandatory when the register request are assumed. This parameter is mandatory
the directory is filled by a third party such as an when the directory is filled by a third party such as an
commissioning tool. When con is used, scheme and host are commissioning tool. When con is used, scheme and host are
mandatory and port and path parameters are optional. If the mandatory and port and path parameters are optional. If the
endpoint uses an ephemeral port to register with, it MUST endpoint uses an ephemeral port to register with, it MUST
include the con: parameter in the registration to provide a include the con: parameter in the registration to provide a
valid network path. If the endpoint which is located behind a valid network path. If the endpoint which is located behind a
NAT gateway is registering with a Resource Directory which is NAT gateway is registering with a Resource Directory which is
on the network service side of the NAT gateway, the endpoint on the network service side of the NAT gateway, the endpoint
MUST use a persistent port for the outgoing registration in MUST use a persistent port for the outgoing registration in
order to provide the NAT gateway with a valid network address order to provide the NAT gateway with a valid network address
for replies and incoming requests. for replies and incoming requests.
skipping to change at page 15, line 44 skipping to change at page 16, line 47
registration content with links resulting in plurality of registration content with links resulting in plurality of
references; see Section 5.3.4. references; see Section 5.3.4.
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
location "/rd" is an example value of an RD base location. location "/rd" is an example RD location discovered in a request
similar to Figure 4.
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
A Resource Directory may optionally support HTTP. Here is an example A Resource Directory may optionally support HTTP. Here is an example
of the same registration operation above, when done using HTTP. of the same registration operation above, when done using HTTP.
Req: POST /rd?ep=node1 HTTP/1.1 Req: POST /rd?ep=node1&con=http://[2001:db8::1:1] HTTP/1.1
Host : example.com Host : example.com
Content-Type: application/link-format Content-Type: application/link-format
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: 201 Created Res: 201 Created
Location: /rd/4521 Location: /rd/4521
5.3.1. Simple Registration 5.3.1. Simple Registration
skipping to change at page 17, line 47 skipping to change at page 18, line 47
Accept: 40 Accept: 40
Res: 2.05 Content Res: 2.05 Content
payload: payload:
</sen/temp> </sen/temp>
5.3.3. Third-party registration 5.3.3. Third-party registration
For some applications, even Simple Directory Discovery may be too For some applications, even Simple Registration may be too taxing for
taxing for certain very constrained devices, in particular if the certain very constrained devices, in particular if the security
security requirements become too onerous. requirements become too onerous.
In a controlled environment (e.g. building control), the Resource In a controlled environment (e.g. building control), the Resource
Directory can be filled by a third device, called a commissioning Directory can be filled by a third device, called a commissioning
tool. The commissioning tool can fill the Resource Directory from a tool. The commissioning tool can fill the Resource Directory from a
database or other means. For that purpose the scheme, IP address and database or other means. For that purpose the scheme, IP address and
port of the registered device is indicated in the Context parameter port of the registered device is indicated in the Context parameter
of the registration described in Section 5.3. of the registration described in Section 5.3.
5.3.4. Plurality of link references in a Registration 5.3.4. Plurality of link references in a Registration
skipping to change at page 18, line 35 skipping to change at page 19, line 35
reference between different registrations. Resource Directory reference between different registrations. Resource Directory
operations which are rejected due to reference plurality SHOULD be operations which are rejected due to reference plurality SHOULD be
returned the "Conflict" code, indicating that there is someting wrong returned the "Conflict" code, indicating that there is someting wrong
with the request. with the request.
5.4. Operations on the Registration Resource 5.4. Operations on the Registration Resource
After the initial registration, an endpoint should retain the After the initial registration, an endpoint should retain the
returned location of the Registration Resource for further returned location of the Registration Resource for further
operations, including refreshing the registration in order to extend operations, including refreshing the registration in order to extend
the lifetie and "keep-alive" the registration. If the lifetime of the lifetime and "keep-alive" the registration. If the lifetime of
the registration expires, the RD SHOULD NOT respond to discovery the registration expires, the RD SHOULD NOT respond to discovery
queries with information from the endpoint. The RD SHOULD continue queries with information from the endpoint. The RD SHOULD continue
to provide access to the Registration Resource after a registration to provide access to the Registration Resource after a registration
time-out occurs in order to enable the registering endpoint to time-out occurs in order to enable the registering endpoint to
eventually refresh the registration. The RD MAY eventually remove eventually refresh the registration. The RD MAY eventually remove
the registration resource for the purpose of resource recovery and the registration resource for the purpose of resource recovery and
garbage collection. If the Registration Resource is removed, the garbage collection. If the Registration Resource is removed, the
endpoint will need to re-register. endpoint will need to re-register.
The Registration Resource may also be used to inspect the The Registration Resource may also be used to inspect the
registration resource using GET, update the registration link registration resource using GET, update the registration link
contents using PATCH, or cancel the registration using DELETE. contents using PATCH (as introduced in [RFC8132]), or cancel the
registration using DELETE.
These operations are described in this section. These operations are described in this section.
In accordance with Section 5.3.4, operations which would result in In accordance with Section 5.3.4, operations which would result in
plural link references within the context of a registration resource plural link references within the context of a registration resource
SHOULD be rejected using the "Conflict" result code. SHOULD be rejected using the "Conflict" result code.
5.4.1. Registration Update 5.4.1. Registration Update
The update interface is used by an endpoint to refresh or update its The update interface is used by an endpoint to refresh or update its
skipping to change at page 20, line 4 skipping to change at page 21, line 4
In addition to the use of POST, as described in this section, there In addition to the use of POST, as described in this section, there
is an alternate way to add, replace, and delete links using PATCH as is an alternate way to add, replace, and delete links using PATCH as
described in Section 5.4.4. described in Section 5.4.4.
The update registration request interface is specified as follows: The update registration request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /{+location}{?lt,con} URI Template: {+location}{?lt,con}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location returned by the RD as a result
result of a successful earlier registration. of a successful earlier registration.
lt := Lifetime (optional). Lifetime of the registration in lt := Lifetime (optional). Lifetime of the registration in
seconds. Range of 60-4294967295. If no lifetime is included, seconds. Range of 60-4294967295. If no lifetime is included,
the previous last lifetime set on a previous update or the the previous last lifetime set on a previous update or the
original registration (falling back to 86400) SHOULD be used. original registration (falling back to 86400) SHOULD be used.
con := Context (optional). This parameter sets the scheme, con := Context (optional). This parameter sets the scheme,
address and port at which this server is available in the form address and port at which this server is available in the form
scheme://host:port/path. In the absence of this parameter the scheme://host:port/path. In the absence of this parameter the
scheme of the protocol, source address and source port of the scheme of the protocol, source address and source port of the
skipping to change at page 21, line 45 skipping to change at page 22, line 45
the RD if it knows it will no longer be available (for example on the RD if it knows it will no longer be available (for example on
shut-down). This is accomplished using a removal interface on the RD shut-down). This is accomplished using a removal interface on the RD
by performing a DELETE on the endpoint resource. by performing a DELETE on the endpoint resource.
The removal request interface is specified as follows: The removal request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: DELETE Method: DELETE
URI Template: /{+location} URI Template: {+location}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location returned by the RD as a result
result of a successful earlier registration. of a successful earlier registration.
The following responses codes are defined for this interface: The following responses codes are defined for this interface:
Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion
Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed
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).
skipping to change at page 22, line 45 skipping to change at page 23, line 45
If no links are selected, the Resource Directory SHOULD return an If no links are selected, the Resource Directory SHOULD return an
empty payload. empty payload.
The read request interface is specified as follows: The read request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: GET Method: GET
URI Template: /{+location}{?href,rel,rt,if,ct} URI Template: {+location}{?href,rel,rt,if,ct}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location returned by the RD as a result
result of a successful earlier registration. of a successful earlier registration.
href,rel,rt,if,ct := link relations and attributes specified in href,rel,rt,if,ct := link relations and attributes specified in
the query in order to select particular links based on their the query in order to select particular links based on their
relations and attributes. "href" denotes the URI target of the relations and attributes. "href" denotes the URI target of the
link. See [RFC6690] Sec. 4.1 link. See [RFC6690] Sec. 4.1
The following responses codes are defined for this interface: The following responses codes are defined for this interface:
Success: 2.05 "Content" or 200 "OK" upon success with an Success: 2.05 "Content" or 200 "OK" upon success with an
"application/link-format", "application/link-format+cbor", or "application/link-format", "application/link-format+cbor", or
skipping to change at page 24, line 38 skipping to change at page 25, line 38
If the PATCH payload results in the modification of link target, If the PATCH payload results in the modification of link target,
context, or relation values, that is "href", "rel", or "anchor", the context, or relation values, that is "href", "rel", or "anchor", the
request SHOULD be rejected with a "Conflict" result code. request SHOULD be rejected with a "Conflict" result code.
The update request interface is specified as follows: The update request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: PATCH Method: PATCH
URI Template: /{+location}{?href,rel,rt,if,ct} URI Template: {+location}{?href,rel,rt,if,ct}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location returned by the RD as a result
result of a successful earlier registration. of a successful earlier registration.
href,rel,rt,if,ct := link relations and attributes specified in href,rel,rt,if,ct := link relations and attributes specified in
the query in order to select particular links based on their the query in order to select particular links based on their
relations and attributes. "href" denotes the URI target of the relations and attributes. "href" denotes the URI target of the
link. See [RFC6690] Sec. 4.1 link. See [RFC6690] Sec. 4.1
Content-Format: application/merge-patch+json (mandatory) Content-Format: application/merge-patch+json (mandatory)
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.04 "Changed" 0r 204 "No Content" in the update was Success: 2.04 "Changed" 0r 204 "No Content" in the update was
skipping to change at page 27, line 46 skipping to change at page 28, line 46
Configuration of the endpoints themselves is out of scope of this Configuration of the endpoints themselves is out of scope of this
specification. Such an interface for managing the group membership specification. Such an interface for managing the group membership
of an endpoint has been defined in [RFC7390]. of an endpoint has been defined in [RFC7390].
The registration request interface is specified as follows: The registration request interface is specified as follows:
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 Base URI path (mandatory). This is the path rd-group := RD Group URI (mandatory). This is the location of
of the RD Group REST API. The value "rd-group" is recommended the RD Group REST API.
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. endpoint with a configured default domain.
skipping to change at page 29, line 4 skipping to change at page 29, line 47
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
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
base location value /rd-group is an example of an RD base location. RD group path /rd-group is an example RD location discovered in a
request similar to Figure 4.
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 29, line 30 skipping to change at page 30, line 27
location of the group registration resource which was returned when location of the group registration resource which was returned when
intially registering the group. Removing a group MUST NOT remove the intially registering the group. Removing a group MUST NOT remove the
endpoints of the group from the RD. endpoints of the group from the RD.
The removal request interface is specified as follows: The removal request interface is specified as follows:
Interaction: CT -> RD Interaction: CT -> RD
Method: DELETE Method: DELETE
URI Template: /{+location} URI Template: {+location}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location returned by the RD as a result
result of a successful group registration. of a successful group registration.
The following responses codes are defined for this interface: The following responses codes are defined for this interface:
Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
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.
skipping to change at page 31, line 45 skipping to change at page 32, line 41
wildcard operator. wildcard operator.
RD Lookup requests MAY use any set of query parameters to match the RD Lookup requests MAY use any set of query parameters to match the
registered attributes and relations. In addition, this interface MAY registered attributes and relations. In addition, this interface MAY
be used with queries that specify domains, endpoints, and groups. 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.
Clients that are interested in a lookup result repeatedly or
continuously can use mechanisms like ETag caching, resource
observation ([RFC7641]), or any future mechanism that might allow
more efficient observations of collections. These are advertised,
detected and used according to their own specifications and can be
used with the lookup interface as with any other resource.
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: {+type-lookup-
URI Template: /{+rd-lookup-base}/{lookup- location}{?d,res,ep,gp,et,rt,page,count,resource-param}
type}{?d,res,ep,gp,et,rt,page,count,resource-param}
URI Template Variables: URI Template Variables:
rd-lookup-base := RD Lookup Base URI path (mandatory). This is type-lookup-location := RD Lookup URI for a given lookup type
the base path for RD Lookup requests. The recommended value (mandatory). The address is discovered as described in
for this variable is: "rd-lookup". Section 5.2.
lookup-type := ("ep", "res") (mandatory), ("d","gp") (optional)
This variable is used to select the type of lookup to perform
(endpoint, resource, domain, or group). The values are
recommended defaults and MAY use other values as needed. The
supported lookup-types SHOULD be listed in .well-known/core
using the specified resource types.
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.
res := resource (optional). Used for domain, group, endpoint and res := resource (optional). Used for domain, group, endpoint and
resource lookups. resource lookups.
skipping to change at page 33, line 35 skipping to change at page 34, line 30
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 CoAP hosts with a default CoAP The examples in this section assume CoAP hosts with a default CoAP
port 61616. HTTP hosts are possible and do not change the nature of port 61616. HTTP hosts are possible and do not change the nature of
the examples. 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/: with the example resource look-up locations discovered in Figure 4:
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 35, line 49 skipping to change at page 36, line 49
directory SHOULD be mutually authenticated using Pre-Shared Key, Raw directory SHOULD be mutually authenticated using Pre-Shared Key, Raw
Public Key or Certificate based security. Endpoints using a Public Key or Certificate based security. Endpoints using a
Certificate MUST include the Endpoint identifier as the Subject of Certificate MUST include the Endpoint identifier as the Subject of
the Certificate, and this identifier MUST be checked by a resource the Certificate, and this identifier MUST be checked by a resource
directory to match the Endpoint identifier included in the directory to match the Endpoint identifier included in the
Registration message. Registration message.
8.2. Access Control 8.2. Access Control
Access control SHOULD be performed separately for the RD Access control SHOULD be performed separately for the RD
registration, Lookup, and group API base paths, as different registration, Lookup, and group API paths, as different endpoints may
endpoints may be authorized to register with an RD from those be authorized to register with an RD from those authorized to lookup
authorized to lookup endpoints from the RD. Such access control endpoints from the RD. Such access control SHOULD be performed in as
SHOULD be performed in as fine-grained a level as possible. For fine-grained a level as possible. For example access control for
example access control for lookups could be performed either at the lookups could be performed either at the domain, endpoint or resource
domain, endpoint or resource level. level.
8.3. Denial of Service Attacks 8.3. Denial of Service Attacks
Services that run over UDP unprotected are vulnerable to unknowingly Services that run over UDP unprotected are vulnerable to unknowingly
become part of a DDoS attack as UDP does not require return become part of a DDoS attack as UDP does not require return
routability check. Therefore, an attacker can easily spoof the routability check. Therefore, an attacker can easily spoof the
source IP of the target entity and send requests to such a service source IP of the target entity and send requests to such a service
which would then respond to the target entity. This can be used for which would then respond to the target entity. This can be used for
large-scale DDoS attacks on the target. Especially, if the service large-scale DDoS attacks on the target. Especially, if the service
returns a response that is order of magnitudes larger than the returns a response that is order of magnitudes larger than the
skipping to change at page 37, line 26 skipping to change at page 38, line 26
+----------+-------+---------------+--------------------------------+ +----------+-------+---------------+--------------------------------+
| Endpoint | ep | | Name of the endpoint, max 63 | | Endpoint | ep | | Name of the endpoint, max 63 |
| Name | | | bytes | | Name | | | bytes |
| Lifetime | lt | 60-4294967295 | Lifetime of the registration | | Lifetime | lt | 60-4294967295 | Lifetime of the registration |
| | | | in seconds | | | | | in seconds |
| Domain | d | | Domain to which this endpoint | | Domain | d | | Domain to which this endpoint |
| | | | belongs | | | | | belongs |
| Endpoint | et | | Semantic name of the endpoint | | Endpoint | et | | Semantic name of the endpoint |
| Type | | | | | Type | | | |
| Context | con | URI | The scheme, address and port | | Context | con | URI | The scheme, address and port |
| | | | at which this server is | | | | | and path at which this server |
| | | | available | | | | | is available |
| Resource | res | | Name of the resource | | Resource | res | | Name of the resource |
| Name | | | | | Name | | | |
| Group | gp | | Name of a group in the RD | | Group | gp | | Name of a group in the RD |
| Name | | | | | Name | | | |
| Page | page | Integer | Used for pagination | | Page | page | Integer | Used for pagination |
| Count | count | Integer | Used for pagination | | Count | count | Integer | Used for pagination |
+----------+-------+---------------+--------------------------------+ +----------+-------+---------------+--------------------------------+
Table 2: RD Parameters Table 2: RD Parameters
skipping to change at page 38, line 8 skipping to change at page 39, line 8
10.1. Lighting Installation 10.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. The example uses the recommended values for the to be normative.
base resources: "/rd", "/rd-lookup", and "/rd-group".
10.1.1. Installation Characteristics 10.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 40, line 5 skipping to change at page 41, line 5
| luminary1 | lm_R2-4-015_wndw | /light/right | light | | luminary1 | lm_R2-4-015_wndw | /light/right | light |
| luminary2 | lm_R2-4-015_door | /light/left | light | | luminary2 | lm_R2-4-015_door | /light/left | light |
| luminary2 | lm_R2-4-015_door | /light/middle | light | | luminary2 | lm_R2-4-015_door | /light/middle | light |
| luminary2 | lm_R2-4-015_door | /light/right | light | | luminary2 | lm_R2-4-015_door | /light/right | light |
| Presence | ps_R2-4-015_door | /ps | p-sensor | | Presence | ps_R2-4-015_door | /ps | p-sensor |
| sensor | | | | | sensor | | | |
+----------------+------------------+---------------+---------------+ +----------------+------------------+---------------+---------------+
Table 4: Resource Directory identifiers Table 4: Resource Directory identifiers
It is assumed that the CT knows of the RD's address, and has
performed URI discovery on it that gave a response like the one in
the Section 5.2 example.
The CT inserts the endpoints of the luminaries and the sensor in the The CT inserts the endpoints of the luminaries and the sensor in the
RD using the Context parameter (con) to specify the interface RD using the Context parameter (con) to specify the interface
address: address:
Req: POST coap://[FDFD::ABCD:0]/rd Req: POST coap://[FDFD::ABCD:0]/rd
?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1] ?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1]&d=R2-4-015
Payload: Payload:
</light/left>;rt="light"; d="R2-4-015", </light/left>;rt="light",
</light/middle>;rt="light"; d="R2-4-015", </light/middle>;rt="light",
</light/right>;rt="light";d="R2-4-015" </light/right>;rt="light"
Res: 2.01 Created Res: 2.01 Created
Location: /rd/4521 Location: /rd/4521
Req: POST coap://[FDFD::ABCD:0]/rd Req: POST coap://[FDFD::ABCD:0]/rd
?ep=lm_R2-4-015_door&con=coap://[FDFD::ABCD:2] ?ep=lm_R2-4-015_door&con=coap://[FDFD::ABCD:2]&d=R2-4-015
Payload: Payload:
</light/left>;rt="light"; d="R2-4-015", </light/left>;rt="light",
</light/middle>;rt="light"; d="R2-4-015", </light/middle>;rt="light",
</light/right>;rt="light"; d="R2-4-015" </light/right>;rt="light"
Res: 2.01 Created Res: 2.01 Created
Location: /rd/4522 Location: /rd/4522
Req: POST coap://[FDFD::ABCD:0]/rd Req: POST coap://[FDFD::ABCD:0]/rd
?ep=ps_R2-4-015_door&con=coap://[FDFD::ABCD:3] ?ep=ps_R2-4-015_door&con=coap://[FDFD::ABCD:3]d&d=R2-4-015
Payload: Payload:
</ps>;rt="p-sensor"; d="R2-4-015" </ps>;rt="p-sensor"
Res: 2.01 Created Res: 2.01 Created
Location: /rd/4523 Location: /rd/4523
The domain name d="R2-4-015" has been added for an efficient lookup The domain name d=R2-4-015 has been added for an efficient lookup
because filtering on "ep" name is more awkward. The same domain name because filtering on "ep" name is more awkward. The same domain name
is communicated to the two luminaries and the presence sensor by the is communicated to the two luminaries and the presence sensor by the
CT. CT.
The group is specified in the RD. The Context parameter is set to The group is specified in the RD. The Context parameter is set to
the site-local multicast address allocated to the group. In the POST the site-local multicast address allocated to the group. In the POST
in the example below, these two endpoints and the endpoint of the in the example below, these two endpoints and the endpoint of the
presence sensor are registered as members of the group. presence sensor are registered as members of the group.
Req: POST coap://[FDFD::ABCD:0]/rd-group Req: POST coap://[FDFD::ABCD:0]/rd-group
?gp=grp_R2-4-015;con="coap//[FF05::1]" ?gp=grp_R2-4-015&con=coap://[FF05::1]
Payload: Payload:
<>ep=lm_R2-4-015_wndw, <>;ep=lm_R2-4-015_wndw,
<>ep=lm_R2-4-015_door, <>;ep=lm_R2-4-015_door,
<>ep=ps_R2-4-015_door <>;ep=ps_R2-4-015_door
Res: 2.01 Created Res: 2.01 Created
Location: /rd-group/501 Location: /rd-group/501
After the filling of the RD by the CT, the application in the After the filling of the RD by the CT, the application in the
luminaries can learn to which groups they belong, and enable their luminaries can learn to which groups they belong, and enable their
interface for the multicast address. interface for the multicast address.
The luminary, knowing its domain, queries the RD for the endpoint The luminary, knowing its domain, queries the RD for the endpoint
with rt=light and d=R2-4-015. The RD returns all endpoints in the with rt=light and d=R2-4-015. The RD returns all endpoints in the
skipping to change at page 42, line 41 skipping to change at page 43, line 41
Registration interface. Registration interface.
LWM2M does not provide for registration domains and does not LWM2M does not provide for registration domains and does not
currently use the rd-group or rd-lookup interfaces. currently use the rd-group or rd-lookup interfaces.
The LWM2M specification describes a set of interfaces and a resource The LWM2M specification describes a set of interfaces and a resource
model used between a LWM2M device and an LWM2M server. Other model used between a LWM2M device and an LWM2M server. Other
interfaces, proxies, and applications are currently out of scope for interfaces, proxies, and applications are currently out of scope for
LWM2M. LWM2M.
The location of the LWM2M Server and RD base URI path is provided by The location of the LWM2M Server and RD URI path is provided by the
the LWM2M Bootstrap process, so no dynamic discovery of the RD is LWM2M Bootstrap process, so no dynamic discovery of the RD is used.
used. LWM2M Servers and endpoints are not required to implement the LWM2M Servers and endpoints are not required to implement the /.well-
./well-known/core resource. known/core resource.
10.2.1. The LWM2M Object Model 10.2.1. The LWM2M Object Model
The OMA LWM2M object model is based on a simple 2 level class The OMA LWM2M object model is based on a simple 2 level class
hierarchy consisting of Objects and Resources. hierarchy consisting of Objects and Resources.
An LWM2M Resource is a REST endpoint, allowed to be a single value or An LWM2M Resource is a REST endpoint, allowed to be a single value or
an array of values of the same data type. an array of values of the same data type.
An LWM2M Object is a resource template and container type that An LWM2M Object is a resource template and container type that
skipping to change at page 44, line 13 skipping to change at page 45, line 13
/1/0/1 /1/0/1
The base uri is empty, the Object ID is 1, the instance ID is 0, the The base uri is empty, the Object ID is 1, the instance ID is 0, the
resource ID is 1, and the resource instance is "undefined". This resource ID is 1, and the resource instance is "undefined". This
example URI points to internal resource 1, which represents the example URI points to internal resource 1, which represents the
registration lifetime configured, in instance 0 of a type 1 object registration lifetime configured, in instance 0 of a type 1 object
(LWM2M Server Object). (LWM2M Server Object).
10.2.2. LWM2M Register Endpoint 10.2.2. LWM2M Register Endpoint
LWM2M defines a registration interface based on the REST API, LWM2M defines a registration interface based on the REST API,
described in Section 5. The base URI path of the LWM2M Resource described in Section 5. The RD registration URI path of the LWM2M
Directory is specified to be "/rd" as recommended in Section 5.3. Resource Directory is specified to be "/rd".
LWM2M endpoints register object IDs, for example </1>, to indicate LWM2M endpoints register object IDs, for example </1>, to indicate
that a particular object type is supported, and register object that a particular object type is supported, and register object
instances, for example </1/0>, to indicate that a particular instance instances, for example </1/0>, to indicate that a particular instance
of that object type exists. of that object type exists.
Resources within the LWM2M object instance are not registered with Resources within the LWM2M object instance are not registered with
the RD, but may be discovered by reading the resource links from the the RD, but may be discovered by reading the resource links from the
object instance using GET with a CoAP Content-Format of application/ object instance using GET with a CoAP Content-Format of application/
link-format. Resources may also be read as a structured object by link-format. Resources may also be read as a structured object by
skipping to change at page 50, line 23 skipping to change at page 51, line 23
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.
13. References 13. References
13.1. Normative References 13.1. Normative References
[I-D.ietf-core-links-json] [I-D.ietf-core-links-json]
Li, K., Rahman, A., and C. Bormann, "Representing CoRE Li, K., Rahman, A., and C. Bormann, "Representing
Formats in JSON and CBOR", draft-ietf-core-links-json-06 Constrained RESTful Environments (CoRE) Link Format in
(work in progress), July 2016. JSON and CBOR", draft-ietf-core-links-json-08 (work in
progress), April 2017.
[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>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", RFC 5226,
DOI 10.17487/RFC5226, May 2008, DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>. <http://www.rfc-editor.org/info/rfc5226>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>. <http://www.rfc-editor.org/info/rfc5988>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012, DOI 10.17487/RFC6570, March 2012,
<http://www.rfc-editor.org/info/rfc6570>. <http://www.rfc-editor.org/info/rfc6570>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>. <http://www.rfc-editor.org/info/rfc6690>.
[RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
DOI 10.17487/RFC7396, October 2014, DOI 10.17487/RFC7396, October 2014,
<http://www.rfc-editor.org/info/rfc7396>. <http://www.rfc-editor.org/info/rfc7396>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<http://www.rfc-editor.org/info/rfc8132>.
13.2. Informative References 13.2. Informative References
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616,
DOI 10.17487/RFC2616, June 1999,
<http://www.rfc-editor.org/info/rfc2616>.
[RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C.
Bormann, "Neighbor Discovery Optimization for IPv6 over Bormann, "Neighbor Discovery Optimization for IPv6 over
Low-Power Wireless Personal Area Networks (6LoWPANs)", Low-Power Wireless Personal Area Networks (6LoWPANs)",
RFC 6775, DOI 10.17487/RFC6775, November 2012, RFC 6775, DOI 10.17487/RFC6775, November 2012,
<http://www.rfc-editor.org/info/rfc6775>. <http://www.rfc-editor.org/info/rfc6775>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>. <http://www.rfc-editor.org/info/rfc7230>.
skipping to change at page 51, line 36 skipping to change at page 52, line 47
[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>.
[RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
the Constrained Application Protocol (CoAP)", RFC 7390, the Constrained Application Protocol (CoAP)", RFC 7390,
DOI 10.17487/RFC7390, October 2014, DOI 10.17487/RFC7390, October 2014,
<http://www.rfc-editor.org/info/rfc7390>. <http://www.rfc-editor.org/info/rfc7390>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>.
Authors' Addresses Authors' Addresses
Zach Shelby Zach Shelby
ARM ARM
150 Rose Orchard 150 Rose Orchard
San Jose 95134 San Jose 95134
USA USA
Phone: +1-408-203-9434 Phone: +1-408-203-9434
Email: zach.shelby@arm.com Email: zach.shelby@arm.com
skipping to change at line 2382 skipping to change at page 53, line 40
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org Email: cabo@tzi.org
Peter van der Stok Peter van der Stok
consultant consultant
Phone: +31-492474673 (Netherlands), +33-966015248 (France) Phone: +31-492474673 (Netherlands), +33-966015248 (France)
Email: consultancy@vanderstok.org Email: consultancy@vanderstok.org
URI: www.vanderstok.org URI: www.vanderstok.org
Christian Amsuess (editor)
Energy Harvesting Solutions
Hollandstr. 12/4
1020
Austria
Phone: +43-664-9790639
Email: c.amsuess@energyharvesting.at
 End of changes. 67 change blocks. 
163 lines changed or deleted 218 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/