draft-ietf-core-resource-directory-19.txt   draft-ietf-core-resource-directory-20.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: July 15, 2019 SmartThings Expires: September 12, 2019 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
C. Amsuess, Ed. C. Amsuess, Ed.
January 11, 2019 March 11, 2019
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-19 draft-ietf-core-resource-directory-20
Abstract Abstract
In many M2M applications, direct discovery of resources is not In many IoT 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 contains employing an entity called a Resource Directory (RD), which contains
information about resources held on other servers, allowing lookups information about resources held on other servers, allowing lookups
to be performed for those resources. The input to an RD is composed to be performed for those resources. The input to an RD is composed
of links and the output is composed of links constructed from the of links and the output is composed of links constructed from the
information stored in the RD. This document specifies the web information stored in the RD. This document specifies the web
interfaces that a Resource Directory supports for web servers to interfaces that a Resource Directory supports for web servers to
discover the RD and to register, maintain, lookup and remove discover the RD and to register, maintain, lookup and remove
information on resources. Furthermore, new target attributes useful information on resources. Furthermore, new target attributes useful
skipping to change at page 1, line 47 skipping to change at page 1, line 47
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 15, 2019. This Internet-Draft will expire on September 12, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 32 skipping to change at page 2, line 32
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 6 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 6
3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 7
3.3. RD Content Model . . . . . . . . . . . . . . . . . . . . 8 3.3. RD Content Model . . . . . . . . . . . . . . . . . . . . 8
3.4. Link-local addresses and zone identifiers . . . . . . . . 12 3.4. Link-local addresses and zone identifiers . . . . . . . . 12
3.5. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 12 3.5. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 12
3.6. Use Case: Home and Building Automation . . . . . . . . . 13 3.6. Use Case: Home and Building Automation . . . . . . . . . 13
3.7. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 13 3.7. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 13
4. Finding a Resource Directory . . . . . . . . . . . . . . . . 14 4. RD discovery and other interface-independent components . . . 14
4.1. Resource Directory Address Option (RDAO) . . . . . . . . 16 4.1. Finding a Resource Directory . . . . . . . . . . . . . . 15
5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 17 4.1.1. Resource Directory Address Option (RDAO) . . . . . . 17
5.1. Payload Content Formats . . . . . . . . . . . . . . . . . 18 4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 18
5.2. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 18 4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19
5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 21 5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 21
5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 25 5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26
5.3.2. Third-party registration . . . . . . . . . . . . . . 28 5.2. Third-party registration . . . . . . . . . . . . . . . . 28
5.4. Operations on the Registration Resource . . . . . . . . . 28 5.3. Operations on the Registration Resource . . . . . . . . . 28
5.4.1. Registration Update . . . . . . . . . . . . . . . . . 29 5.3.1. Registration Update . . . . . . . . . . . . . . . . . 29
5.4.2. Registration Removal . . . . . . . . . . . . . . . . 32 5.3.2. Registration Removal . . . . . . . . . . . . . . . . 32
5.4.3. Further operations . . . . . . . . . . . . . . . . . 33 5.3.3. Further operations . . . . . . . . . . . . . . . . . 32
6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 34 6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 33
6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 34 6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 34
6.3. Resource lookup examples . . . . . . . . . . . . . . . . 36 6.3. Resource lookup examples . . . . . . . . . . . . . . . . 36
6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 39 6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 38
7. Security policies . . . . . . . . . . . . . . . . . . . . . . 40 7. Security policies . . . . . . . . . . . . . . . . . . . . . . 39
7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 41 7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 40
7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 41 7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 40
7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 42 7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 41
8. Security Considerations . . . . . . . . . . . . . . . . . . . 42 8. Security Considerations . . . . . . . . . . . . . . . . . . . 41
8.1. Endpoint Identification and Authentication . . . . . . . 42 8.1. Endpoint Identification and Authentication . . . . . . . 41
8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 43 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 42
8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 43 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 42
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42
9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 44 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 43
9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 44 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 43
9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 44 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 43
9.3.1. Full description of the "Endpoint Type" Registration 9.3.1. Full description of the "Endpoint Type" Registration
Parameter . . . . . . . . . . . . . . . . . . . . . . 46 Parameter . . . . . . . . . . . . . . . . . . . . . . 45
9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 46 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 45
9.5. Multicast Address Registration . . . . . . . . . . . . . 47 9.5. Multicast Address Registration . . . . . . . . . . . . . 46
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 46
10.1. Lighting Installation . . . . . . . . . . . . . . . . . 47 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 46
10.1.1. Installation Characteristics . . . . . . . . . . . . 48 10.1.1. Installation Characteristics . . . . . . . . . . . . 47
10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 49 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 48
10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 51 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 50
10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 52 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 51
10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 53 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 52
10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 55 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 54
10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 55 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 54
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54
12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 55 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 54
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 64 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 63
13.1. Normative References . . . . . . . . . . . . . . . . . . 64 13.1. Normative References . . . . . . . . . . . . . . . . . . 63
13.2. Informative References . . . . . . . . . . . . . . . . . 64 13.2. Informative References . . . . . . . . . . . . . . . . . 64
Appendix A. Groups Registration and Lookup . . . . . . . . . . . 66 Appendix A. Groups Registration and Lookup . . . . . . . . . . . 66
Appendix B. Web links and the Resource Directory . . . . . . . . 67 Appendix B. Web links and the Resource Directory . . . . . . . . 67
B.1. A simple example . . . . . . . . . . . . . . . . . . . . 68 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 67
B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 68 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 68
B.1.2. Interpreting attributes and relations . . . . . . . . 68 B.1.2. Interpreting attributes and relations . . . . . . . . 68
B.2. A slightly more complex example . . . . . . . . . . . . . 69 B.2. A slightly more complex example . . . . . . . . . . . . . 69
B.3. Enter the Resource Directory . . . . . . . . . . . . . . 69 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 69
B.4. A note on differences between link-format and Link B.4. A note on differences between link-format and Link
headers . . . . . . . . . . . . . . . . . . . . . . . . . 71 headers . . . . . . . . . . . . . . . . . . . . . . . . . 71
Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 72 Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 72
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72
1. Introduction 1. Introduction
The work on Constrained RESTful Environments (CoRE) aims at realizing In the work on Constrained RESTful Environments (CoRE), a REST
the REST architecture in a suitable form for the most constrained architecture suitable for constrained nodes (e.g. with limited RAM
nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and and ROM [RFC7228]) and networks (e.g. 6LoWPAN [RFC4944]) has been
networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) established and is used in Internet-of-Things (IoT) or machine-to-
applications such as smart energy and building automation. machine (M2M) 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
important in machine-to-machine applications where there are no important in machine-to-machine applications where there are no
humans in the loop and static interfaces result in fragility. The humans in the loop and static interfaces result in fragility. The
discovery of resources provided by an HTTP Web Server is typically discovery of resources provided by an HTTP Web Server is typically
called Web Linking [RFC8288]. The use of Web Linking for the called Web Linking [RFC8288]. The use of Web Linking for the
description and discovery of resources hosted by constrained web description and discovery of resources hosted by constrained web
servers is specified by the CoRE Link Format [RFC6690]. However, servers is specified by the CoRE Link Format [RFC6690]. However,
[RFC6690] only describes how to discover resources from the web [RFC6690] only describes how to discover resources from the web
server that hosts them by querying "/.well-known/core". In many M2M server that hosts them by querying "/.well-known/core". In many
scenarios, direct discovery of resources is not practical due to constrained scenarios, direct discovery of resources is not practical
sleeping nodes, disperse networks, or networks where multicast due to sleeping nodes, disperse networks, or networks where multicast
traffic is inefficient. These problems can be solved by employing an traffic is inefficient. These problems can be solved by employing an
entity called a Resource Directory (RD), which contains information entity called a Resource Directory (RD), which contains information
about resources held on other servers, allowing lookups to be about resources held on other servers, allowing lookups to be
performed for those resources. performed for those resources.
This document specifies the web interfaces that a Resource Directory This document specifies the web interfaces that a Resource Directory
supports for web servers to discover the RD and to register, supports for web servers to discover the RD and to register,
maintain, lookup and remove information on resources. Furthermore, maintain, lookup and remove information on resources. Furthermore,
new target attributes useful in conjunction with a Resource Directory new target attributes useful in conjunction with a Resource Directory
are defined. Although the examples in this document show the use of are defined. Although the examples in this document show the use of
skipping to change at page 6, line 21 skipping to change at page 6, line 21
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.
Registrant-ep Registrant-ep
Registrant-ep is the endpoint that is registered into the RD. The Registrant-ep is the endpoint that is registered into the RD. The
registrant-ep can register itself, or a CT registers the registrant-ep can register itself, or a CT registers the
registrant-ep. registrant-ep.
RDAO RDAO
Resource Directory Address Option. Resource Directory Address Option. A new IPv6 Neigbhbor Discovery
option defined for announcing a Resource Directory's address.
For several operations, interface templates are given in list form;
those describe the operation participants, request codes, URIs,
content formats and outcomes. Sections of those templates contain
normative content about Interaction, Method, URI Template and URI
Template Variables as well as the details of the Success condition.
The additional sections on options like Content-Format and on Failure
codes give typical cases that an implementation of the RD should deal
with. Those serve to illustrate the typical responses to readers who
are not yet familiar with all the details of CoAP based interfaces;
they do not limit what a server may respond under atypical
circumstances.
3. Architecture and Use Cases 3. Architecture and Use Cases
3.1. Principles 3.1. Principles
The Resource Directory is primarily a tool to make discovery The Resource Directory is primarily a tool to make discovery
operations more efficient than querying /.well-known/core on all operations more efficient than querying /.well-known/core on all
connected devices, or across boundaries that would be limiting those connected devices, or across boundaries that would be limiting those
operations. operations.
It provides information about resources hosted by other devices that It provides information about resources hosted by other devices that
could otherwise only be obtained by directly querying the /.well- could otherwise only be obtained by directly querying the /.well-
known/core resource on these other devices, either by a unicast known/core resource on these other devices, either by a unicast
request or a multicast request. request or a multicast request.
Only information SHOULD be stored in the resource directory that can Information SHOULD only be stored in the resource directory if it can
be obtained by querying the described device's /.well-known/core be obtained by querying the described device's /.well-known/core
resource directly. resource directly.
Data in the resource directory can only be provided by the device Data in the resource directory can only be provided by the device
which hosts those data or a dedicated Commissioning Tool (CT). These which hosts those data or a dedicated Commissioning Tool (CT). These
CTs are thought to act on behalf of endpoints too constrained, or CTs are thought to act on behalf of endpoints too constrained, or
generally unable, to present that information themselves. No other generally unable, to present that information themselves. No other
client can modify data in the resource directory. Changes to the client can modify data in the resource directory. Changes to the
information in the Resource Directory do not propagate automatically information in the Resource Directory do not propagate automatically
back to the web servers from where the information originated. back to the web servers from where the information originated.
skipping to change at page 8, line 16 skipping to change at page 7, line 46
Interface Interface Interface Interface
+----+ | | +----+ | |
| EP |---- | | | EP |---- | |
+----+ ---- | | +----+ ---- | |
--|- +------+ | --|- +------+ |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
| EP | ---------|-----| RD |----|-----| Client | | EP | ---------|-----| RD |----|-----| Client |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
--|- +------+ | --|- +------+ |
+----+ ---- | | +----+ ---- | |
| EP |---- | | | CT |---- | |
+----+ +----+
Figure 1: The resource directory architecture. Figure 1: The resource directory architecture.
A Registrant-EP MAY keep concurrent registrations to more than one RD A Registrant-EP MAY keep concurrent registrations to more than one RD
at the same time if explicitly configured to do so, but that is not at the same time if explicitly configured to do so, but that is not
expected to be supported by typical EP implementations. Any such expected to be supported by typical EP implementations. Any such
registrations are independent of each other. The usual expectation registrations are independent of each other. The usual expectation
when multiple discovery mechanisms or addresses are configured is when multiple discovery mechanisms or addresses are configured is
that they constitute a fall-back path for a single registration. that they constitute a fall-back path for a single registration.
skipping to change at page 10, line 22 skipping to change at page 10, line 22
attribute. It defaults to that document's URI. attribute. It defaults to that document's URI.
o A link target URI: It defines the destination of the relation o A link target URI: It defines the destination of the relation
(e.g. _what_ is hosted), and is the topic of all target (e.g. _what_ is hosted), and is the topic of all target
attributes. attributes.
In link-format serialization, it is expressed between angular In link-format serialization, it is expressed between angular
brackets, and sometimes called the "href". brackets, and sometimes called the "href".
o Other target attributes (e.g. resource type (rt), interface (if), o Other target attributes (e.g. resource type (rt), interface (if),
or content-type (ct)). These provide additional information about or content format (ct)). These provide additional information
the target URI. about the target URI.
+----------------------+ +----------------------+
| resource-directory | | resource-directory |
+----------------------+ +----------------------+
| 1 | 1
| |
| |
| |
| |
//////\\\\ //////\\\\
skipping to change at page 12, line 8 skipping to change at page 12, line 8
Figure 3: E-R Model of the content of the Resource Directory Figure 3: E-R Model of the content of the Resource Directory
The model shown in Figure 3 models the contents of the resource The model shown in Figure 3 models the contents of the resource
directory which contains in addition to /.well-known/core: directory which contains in addition to /.well-known/core:
o 0 to n Registrations of endpoints, o 0 to n Registrations of endpoints,
A registration is associated with one endpoint. A registration A registration is associated with one endpoint. A registration
defines a set of links as defined for /.well-known/core. A defines a set of links as defined for /.well-known/core. A
Registration has six types of attributes: Registration has six types of attributes:
o a unique endpoint name ("ep") within a sector o an endpoint name ("ep", a Unicode string) unique within a sector
o a Registration Base URI ("base", a URI typically describing the o a Registration Base URI ("base", a URI typically describing the
scheme://authority part) scheme://authority part)
o a lifetime ("lt"), o a lifetime ("lt"),
o a registration resource location inside the RD ("href"), o a registration resource location inside the RD ("href"),
o optionally a sector ("d") o optionally a sector ("d", a Unicode string)
o optional additional endpoint attributes (from Section 9.3) o optional additional endpoint attributes (from Section 9.3)
The cardinality of "base" is currently 1; future documents are The cardinality of "base" is currently 1; future documents are
invited to extend the RD specification to support multiple values invited to extend the RD specification to support multiple values
(e.g. [I-D.silverajan-core-coap-protocol-negotiation]). Its value (e.g. [I-D.silverajan-core-coap-protocol-negotiation]). Its value
is used as a Base URI when resolving URIs in the links contained in is used as a Base URI when resolving URIs in the links contained in
the endpoint. the endpoint.
Links are modelled as they are in Figure 2. Links are modelled as they are in Figure 2.
skipping to change at page 14, line 32 skipping to change at page 14, line 32
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 sectors to be The additional features of Resource Directory allow sectors to be
defined to enable access to a particular set of resources from defined to enable access to a particular set of resources from
particular applications. This provides isolation and protection of particular applications. This provides isolation and protection of
sensitive data when needed. Application groups with multicast sensitive data when needed. Application groups with multicast
addresses may be defined to support efficient data transport. addresses may be defined to support efficient data transport.
4. Finding a Resource Directory 4. RD discovery and other interface-independent components
This and the following sections define the required set of REST
interfaces between a Resource Directory (RD), endpoints and lookup
clients. Although the examples throughout these sections assume the
use of CoAP [RFC7252], these REST interfaces can also be realized
using HTTP [RFC7230]. Only multicast discovery operations are not
possible on HTTP, and Simple Registration can not be executed as base
attribute (which is mandatory for HTTP) can not be used there. In
all definitions in these sections, both CoAP response codes (with dot
notation) and HTTP response codes (without dot notation) are shown.
An RD implementing this specification MUST support the discovery,
registration, update, lookup, and removal interfaces.
All operations on the contents of the Resource Directory MUST be
atomic and idempotent.
For several operations, interface templates are given in list form;
those describe the operation participants, request codes, URIs,
content formats and outcomes. Sections of those templates contain
normative content about Interaction, Method, URI Template and URI
Template Variables as well as the details of the Success condition.
The additional sections on options like Content-Format and on Failure
codes give typical cases that an implementation of the RD should deal
with. Those serve to illustrate the typical responses to readers who
are not yet familiar with all the details of CoAP based interfaces;
they do not limit what a server may respond under atypical
circumstances.
REST clients (registrant-EPs / CTs, lookup clients, RD servers during
simple registrations) MUST be prepared to receive any unsuccessful
code and act upon it according to its definition, options and/or
payload to the best of their capabilities, falling back to failing
the operation if recovery is not possible. In particular, they
should retry the request upon 5.03 (Service Unavailable; 503 in HTTP)
according to the Max-Age (Retry-After in HTTP) option, and fall back
to link-format when receiving 4.15 (Unsupported Content Format; 415
in HTTP).
A resource directory MAY make the information submitted to it
available to further directories, if it can ensure that a loop does
not form. The protocol used between directories to ensure loop-free
operation is outside the scope of this document.
4.1. Finding a Resource Directory
A (re-)starting device may want to find one or more resource A (re-)starting device may want to find one or more resource
directories for discovery purposes. directories for discovery purposes.
The device may be pre-configured to exercise specific mechanisms for The device may be pre-configured to exercise specific mechanisms for
finding the resource directory: finding the resource directory:
1. It may be configured with a specific IP address for the RD. That 1. It may be configured with a specific IP address for the RD. That
IP address may also be an anycast address, allowing the network IP address may also be an anycast address, allowing the network
to forward RD requests to an RD that is topologically close; each to forward RD requests to an RD that is topologically close; each
skipping to change at page 15, line 17 skipping to change at page 16, line 12
3. It may be configured to use a service discovery mechanism such as 3. It may be configured to use a service discovery mechanism such as
DNS-SD [RFC6763]. The present specification suggests configuring DNS-SD [RFC6763]. The present specification suggests configuring
the service with name rd._sub._coap._udp, preferably within the the service with name rd._sub._coap._udp, preferably within the
domain of the querying nodes. domain of the querying nodes.
For cases where the device is not specifically configured with a way For cases where the device is not specifically configured with a way
to find a resource directory, the network may want to provide a to find a resource directory, the network may want to provide a
suitable default. suitable default.
1. If the address configuration of the network is performed via 1. If the address configuration of the network is performed via
SLAAC, this is provided by the RDAO option Section 4.1. SLAAC, this is provided by the RDAO option Section 4.1.1.
2. If the address configuration of the network is performed via 2. If the address configuration of the network is performed via
DHCP, this could be provided via a DHCP option (no such option is DHCP, this could be provided via a DHCP option (no such option is
defined at the time of writing). defined at the time of writing).
Finally, if neither the device nor the network offers any specific Finally, if neither the device nor the network offers any specific
configuration, the device may want to employ heuristics to find a configuration, the device may want to employ heuristics to find a
suitable resource directory. suitable resource directory.
The present specification does not fully define these heuristics, but The present specification does not fully define these heuristics, but
skipping to change at page 16, line 12 skipping to change at page 17, line 9
Unreachable message (and, in particular, the port unreachable code Unreachable message (and, in particular, the port unreachable code
for this message) may indicate the lack of a CoAP server on the for this message) may indicate the lack of a CoAP server on the
candidate host, or a CoAP error response code such as 4.05 "Method candidate host, or a CoAP error response code such as 4.05 "Method
Not Allowed" may indicate unwillingness of a CoAP server to act as a Not Allowed" may indicate unwillingness of a CoAP server to act as a
directory server. directory server.
If multiple candidate addresses are discovered, the device may pick If multiple candidate addresses are discovered, the device may pick
any of them initially, unless the discovery method indicates a more any of them initially, unless the discovery method indicates a more
precise selection scheme. precise selection scheme.
4.1. Resource Directory Address Option (RDAO) 4.1.1. Resource Directory Address Option (RDAO)
The Resource Directory Address Option (RDAO) using IPv6 Neighbor The Resource Directory Address Option (RDAO) using IPv6 Neighbor
Discovery (ND) carries information about the address of the Resource Discovery (ND) carries information about the address of the Resource
Directory (RD). This information is needed when endpoints cannot Directory (RD). This information is needed when endpoints cannot
discover the Resource Directory with a link-local or realm-local discover the Resource Directory with a link-local or realm-local
scope multicast address, for instance because the endpoint and the RD scope multicast address, for instance because the endpoint and the RD
are separated by a Border Router (6LBR). In many circumstances the are separated by a Border Router (6LBR). In many circumstances the
availability of DHCP cannot be guaranteed either during commissioning availability of DHCP cannot be guaranteed either during commissioning
of the network. The presence and the use of the RD is essential of the network. The presence and the use of the RD is essential
during commissioning. during commissioning.
skipping to change at page 17, line 45 skipping to change at page 18, line 45
is not valid anymore. is not valid anymore.
Reserved: This field is unused. It MUST be Reserved: This field is unused. It MUST be
initialized to zero by the sender and initialized to zero by the sender and
MUST be ignored by the receiver. MUST be ignored by the receiver.
RD Address: IPv6 address of the RD. RD Address: IPv6 address of the RD.
Figure 4: Resource Directory Address Option Figure 4: Resource Directory Address Option
5. Resource Directory 4.2. Payload Content Formats
This section defines the required set of REST interfaces between a
Resource Directory (RD) and endpoints. Although the examples
throughout this section assume the use of CoAP [RFC7252], these REST
interfaces can also be realized using HTTP [RFC7230]. In all
definitions in this section, both CoAP response codes (with dot
notation) and HTTP response codes (without dot notation) are shown.
An RD implementing this specification MUST support the discovery,
registration, update, lookup, and removal interfaces defined in this
section.
All operations on the contents of the Resource Directory MUST be
atomic and idempotent.
A resource directory MAY make the information submitted to it
available to further directories, if it can ensure that a loop does
not form. The protocol used between directories to ensure loop-free
operation is outside the scope of this document.
5.1. Payload Content Formats
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 SHOULD be able to express all the implementing this specification SHOULD be able to express all the
information expressible in link-format. It MAY be able to express information expressible in link-format. It MAY be able to express
information that is inexpressible in link-format, but those information that is inexpressible in link-format, but those
expressions SHOULD be avoided where possible. expressions SHOULD be avoided where possible.
5.2. URI Discovery 4.3. 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 URI path information for its REST APIs. address and port, and the URI path information for its REST APIs.
This section defines discovery of the RD and its URIs using the well- This section defines discovery of the RD and its URIs using the well-
known interface of the CoRE Link Format [RFC6690]. A complete set of known interface of the CoRE Link Format [RFC6690]. A complete set of
RD discovery methods is described in Section 4. RD discovery methods is described in Section 4.1.
Discovery of the RD registration URI path is performed by sending Discovery of the RD registration URI path is performed by sending
either a multicast or unicast GET request to "/.well-known/core" and either a multicast or unicast GET request to "/.well-known/core" and
including a Resource Type (rt) parameter [RFC6690] with the value including a Resource Type (rt) parameter [RFC6690] with the value
"core.rd" in the query string. Likewise, a Resource Type parameter "core.rd" in the query string. Likewise, a Resource Type parameter
value of "core.rd-lookup*" is used to discover the URIs for RD Lookup value of "core.rd-lookup*" is used to discover the URIs for RD Lookup
operations, core.rd* is used to discover all URI paths for RD operations, core.rd* is used to discover all URI paths for RD
operations. Upon success, the response will contain a payload with a operations. Upon success, the response will contain a payload with a
link format entry for each RD function discovered, indicating the URI link format entry for each RD function discovered, indicating the URI
of the RD function returned and the corresponding Resource Type. of the RD function returned and the corresponding Resource Type.
skipping to change at page 19, line 47 skipping to change at page 20, line 28
URI Template Variables: URI Template Variables:
rt := Resource Type. SHOULD contain one of the values "core.rd", rt := Resource Type. SHOULD contain one of the values "core.rd",
"core.rd-lookup*", "core.rd-lookup-res", "core.rd-lookup-ep", "core.rd-lookup*", "core.rd-lookup-res", "core.rd-lookup-ep",
or "core.rd*" or "core.rd*"
Accept: absent, application/link-format or any other media type Accept: absent, application/link-format or any other media type
representing web links representing web links
The following response codes are defined for this interface: The following response is expected on this interface:
Success: 2.05 "Content" or 200 "OK" with an application/link-format Success: 2.05 "Content" or 200 "OK" with an application/link-format
or other web link payload containing one or more matching entries or other web link payload containing one or more matching entries
for the RD resource. for the RD resource.
Failure: 4.00 "Bad Request" or 400 "Bad Request" is returned in case
of a malformed request for a unicast request.
Failure: No error response to a multicast request.
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 directory resource location, in interface, thus learning that the directory resource location, in
this example, is /rd, and that the content-format delivered by the this example, is /rd, and that the content-format delivered by the
server hosting the resource is application/link-format (ct=40). Note server hosting the resource is application/link-format (ct=40). Note
that it is up to the RD to choose its RD locations. that it is up to the RD to choose its RD locations.
Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* Req: GET coap://[MCD1]/.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,
skipping to change at page 21, line 23 skipping to change at page 21, line 45
Res: 2.05 Content Res: 2.05 Content
<http://software.example.com/shiny-resource-directory/1.0beta1>; <http://software.example.com/shiny-resource-directory/1.0beta1>;
rel="impl-info" rel="impl-info"
Note that depending on the particular server's architecture, such a Note that depending on the particular server's architecture, such a
link could be anchored at the RD server's root, at the discovery site link could be anchored at the RD server's root, at the discovery site
(as in this example) or at individual RD components. The latter is (as in this example) or at individual RD components. The latter is
to be expected when different applications are run on the same to be expected when different applications are run on the same
server. server.
5.3. Registration 5. Registration
After discovering the location of an RD, a registrant-ep or CT MAY After discovering the location of an RD, a registrant-ep or CT MAY
register the resources of the registrant-ep using the registration register the resources of the registrant-ep using the registration
interface. This interface accepts a POST from an endpoint containing interface. This interface accepts a POST from an endpoint containing
the list of resources to be added to the directory as the message the list of resources to be added to the directory as the message
payload in the CoRE Link Format [RFC6690] or other representations of payload in the CoRE Link Format [RFC6690] or other representations of
web links, along with query parameters indicating the name of the web links, along with query parameters indicating the name of the
endpoint, and optionally the sector, lifetime and base URI of the endpoint, and optionally the sector, lifetime and base URI of the
registration. It is expected that other specifications will define registration. It is expected that other specifications will define
further parameters (see Section 9.3). The RD then creates a new further parameters (see Section 9.3). The RD then creates a new
skipping to change at page 22, line 31 skipping to change at page 23, line 4
in Limited Link Format as described there. Its behavior with in Limited Link Format as described there. Its behavior with
representations outside that subset is implementation defined. representations outside that subset is implementation defined.
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,lt,base,extra-attrs*} URI Template: {+rd}{?ep,d,lt,base,extra-attrs*}
URI Template Variables: URI Template Variables:
rd := RD registration URI (mandatory). This is the location of rd := RD registration URI (mandatory). This is the location of
the RD, as obtained from discovery. the RD, as obtained from discovery.
ep := Endpoint name (mostly mandatory). The endpoint name is an ep := Endpoint name (mostly mandatory). The endpoint name is an
identifier that MUST be unique within a sector. The maximum identifier that MUST be unique within a sector. As the
length of this parameter is 63 bytes. If the RD is configured endpoint name is a Unicode string, it is encoded in UTF-8 (and
to recognize the endpoint (e.g. based on its security context), possibly pct-encoding) during variable expansion (see [RFC6570]
the RD assigns an endpoint name based on a set of configuration Section 3.2.1). The endpoint name MUST NOT contain any
parameter values. character in the inclusive ranges 0-31 or 127-159. The maximum
length of this parameter is 63 UTF-8 encoded bytes. If the RD
is configured to recognize the endpoint (e.g. based on its
security context), the RD assigns an endpoint name based on a
set of configuration parameter values.
d := Sector (optional). The sector to which this endpoint d := Sector (optional). The sector to which this endpoint
belongs. The maximum length of this parameter is 63 bytes. belongs. When this parameter is not present, the RD MAY
When this parameter is not present, the RD MAY associate the associate the endpoint with a configured default sector or
endpoint with a configured default sector or leave it empty. leave it empty. The sector is encoded like the ep parameter,
The endpoint name and sector name are not set when one or both and is limited to 63 UTF-8 encoded bytes as well. The endpoint
are set in an accompanying authorization token. name and sector name are not set when one or both are set in an
accompanying authorization token.
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 90000 (25 in the initial registration, a default value of 90000 (25
hours) SHOULD be assumed. hours) SHOULD be assumed.
base := Base URI (optional). This parameter sets the base URI of base := Base URI (optional). This parameter sets the base URI of
the registration, under which the relative links in the payload the registration, under which the relative links in the payload
are to be interpreted. The specified URI typically does not are to be interpreted. The specified URI typically does not
have a path component of its own, and MUST be suitable as a have a path component of its own, and MUST be suitable as a
skipping to change at page 23, line 33 skipping to change at page 24, line 12
":" followed by its port (if it was not the protocol's default ":" followed by its port (if it was not the protocol's default
one) in analogy to [RFC7252] Section 6.5. one) in analogy to [RFC7252] Section 6.5.
This parameter is mandatory when the directory is filled by a This parameter is mandatory when the directory is filled by a
third party such as an commissioning tool. third party such as an commissioning tool.
If the registrant-ep uses an ephemeral port to register with, If the registrant-ep uses an ephemeral port to register with,
it MUST include the base parameter in the registration to it MUST include the base parameter in the registration to
provide a valid network path. provide a valid network path.
If the registrant-ep, located behind a NAT gateway, is A registrant that can not be reached by potential lookup
registering with a Resource Directory which is on the network clients at the address it registers from (e.g. because it is
service side of the NAT gateway, the endpoint MUST use a behind some form of Network Address Translation (NAT)) MUST
persistent port for the outgoing registration in order to provide a reachable base address with its registration.
provide the NAT gateway with a valid network address for
replies and incoming requests.
If the Base URI contains a link-local IP literal, it MUST NOT If the Base URI contains a link-local IP literal, it MUST NOT
contain a Zone Identifier, and MUST be local to the link on contain a Zone Identifier, and MUST be local to the link on
which the registration request is received. which the registration request is received.
Endpoints that register with a base that contains a path Endpoints that register with a base that contains a path
component can not meaningfully use [RFC6690] Link Format due to component can not meaningfully use [RFC6690] Link Format due to
its prevalence of the Origin concept in relative reference its prevalence of the Origin concept in relative reference
resolution. Those applications should use different resolution. Those applications should use different
representations of links to which Appendix C is not applicable representations of links to which Appendix C is not applicable
skipping to change at page 24, line 15 skipping to change at page 24, line 38
extra-attrs := Additional registration attributes (optional). extra-attrs := Additional registration attributes (optional).
The endpoint can pass any parameter registered at Section 9.3 The endpoint can pass any parameter registered at Section 9.3
to the directory. If the RD is aware of the parameter's to the directory. If the RD is aware of the parameter's
specified semantics, it processes it accordingly. Otherwise, specified semantics, it processes it accordingly. Otherwise,
it MUST store the unknown key and its value(s) as an endpoint it MUST store the unknown key and its value(s) as an endpoint
attribute for further lookup. attribute for further lookup.
Content-Format: application/link-format or any other indicated media Content-Format: application/link-format or any other indicated media
type representing web links type representing web links
The following response codes are defined for this interface: The following response is expected on this interface:
Success: 2.01 "Created" or 201 "Created". The Location-Path option Success: 2.01 "Created" or 201 "Created". The Location-Path option
or Location header MUST be included in the response. This or Location header MUST be included in the response. This
location MUST be a stable identifier generated by the RD as it is location MUST be a stable identifier generated by the RD as it is
used for all subsequent operations on this registration resource. used for all subsequent operations on this registration resource.
The registration resource location thus returned is for the The registration resource location thus returned is for the
purpose of updating the lifetime of the registration and for purpose of updating the lifetime of the registration and for
maintaining the content of the registered links, including maintaining the content of the registered links, including
updating and deleting links. updating and deleting links.
A registration with an already registered ep and d value pair A registration with an already registered ep and d value pair
responds with the same success code and location as the original responds with the same success code and location as the original
registration; the set of links registered with the endpoint is registration; the set of links registered with the endpoint is
replaced with the links from the payload. replaced with the links from the payload.
The location MUST NOT have a query or fragment component, as that The location MUST NOT have a query or fragment component, as that
could conflict with query parameters during the Registration could conflict with query parameters during the Registration
Update operation. Therefore, the Location-Query option MUST NOT Update operation. Therefore, the Location-Query option MUST NOT
be present in a successful response. be present in a successful response.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed If the registration fails, including request timeouts, or if delays
request. from Service Unavailable responses with Max-Age or Retry-After
accumulate to exceed the registrant's configured timeouts, it SHOULD
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". pick another registration URI from the "URI Discovery" step and if
Service could not perform the operation. there is only one or the list is exhausted, pick other choices from
the "Finding a Resource Directory" step. Care has to be taken to
HTTP support: YES
If the registration fails with a Service Unavailable response and a
Max-Age option or Retry-After header, the registering endpoint SHOULD
retry the operation after the time indicated. If the registration
fails in another way, including request timeouts, or if the Service
Unavailable error persists after several retries, or indicates a
longer time than the endpoint is willing to wait, it SHOULD pick
another registration URI from the "URI Discovery" step and if there
is only one or the list is exhausted, pick other choices from the
"Finding a Resource Directory" step. Care has to be taken to
consider the freshness of results obtained earlier, e.g. of the consider the freshness of results obtained earlier, e.g. of the
result of a "/.well-known/core" response, the lifetime of an RDAO result of a "/.well-known/core" response, the lifetime of an RDAO
option and of DNS responses. Any rate limits and persistent errors option and of DNS responses. Any rate limits and persistent errors
from the "Finding a Resource Directory" step must be considered for from the "Finding a Resource Directory" step must be considered for
the whole registration time, not only for a single operation. the whole registration time, not only for a single operation.
The following example shows a registrant-ep with the name "node1" The following example shows a registrant-ep 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 RD location discovered in a request location "/rd" is an example RD location discovered in a request
similar to Figure 5. similar to Figure 5.
skipping to change at page 25, line 42 skipping to change at page 26, line 5
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";
anchor="coap://spurious.example.com:5683", anchor="coap://spurious.example.com:5683",
</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.1. Simple Registration
Not all endpoints hosting resources are expected to know how to Not all endpoints hosting resources are expected to know how to
upload links to an RD as described in Section 5.3. Instead, simple upload links to an RD as described in Section 5. Instead, simple
endpoints can implement the Simple Registration approach described in endpoints can implement the Simple Registration approach described in
this section. An RD implementing this specification MUST implement this section. An RD implementing this specification MUST implement
Simple Registration. However, there may be security reasons why this Simple Registration. However, there may be security reasons why this
form of directory discovery would be disabled. form of directory discovery would be disabled.
This approach requires that the registrant-ep makes available the This approach requires that the registrant-ep makes available the
hosted resources that it wants to be discovered, as links on its hosted resources that it wants to be discovered, as links on its
"/.well-known/core" interface as specified in [RFC6690]. The links "/.well-known/core" interface as specified in [RFC6690]. The links
in that document are subject to the same limitations as the payload in that document are subject to the same limitations as the payload
of a registration (with respect to Appendix C). of a registration (with respect to Appendix C).
The registrant-ep finds one or more addresses of the directory server o The registrant-ep finds one or more addresses of the directory
as described in Section 4. server as described in Section 4.1.
The registrant-ep asks the selected directory server to probe its o The registrant-ep sends (and regularly refreshes with) a POST
/.well-known/core and publish the links as follows: request to the "/.well-known/core" URI of the directory server of
choice. The body of the POST request is empty, and triggers the
resource directory server to perform GET requests at the
requesting registrant-ep's /.well-known/core to obtain the link-
format payload to register.
The registrant-ep sends (and regularly refreshes with) a POST request The registrant-ep includes the same registration parameters in the
to the "/.well-known/core" URI of the directory server of choice. POST request as it would per Section 5. The registration base URI
The body of the POST request is empty, and triggers the resource of the registration is taken from the registrant-ep's network
directory server to perform GET requests at the requesting address (as is default with regular registrations).
registrant-ep's /.well-known/core to obtain the link-format payload
to register.
The registrant-ep includes the same registration parameters in the Example request from registrant-EP to RD (unanswered until the
POST request as it would per Section 5.3. The registration base URI next step):
of the registration is taken from the registrant-ep's network address
(as is default with regular registrations).
The Resource Directory needs to query the registrant-ep's discovery Req: POST /.well-known/core?lt=6000&ep=node1
resource to determine the success of the operation. It SHOULD keep a (No payload)
cache of the discovery resource and not query it again as long as it
is fresh.
(This is to accomodate constrained registrant devices that can not o The Resource Directory queries the registrant-ep's discovery
process an incoming and outgoing request at the same time. resource to determine the success of the operation. It SHOULD
keep a cache of the discovery resource and not query it again as
long as it is fresh.
Example request from the RD to the registrant-EP:
Req: GET /.well-known/core
Accept: 40
Res: 2.05 Content
Content-Format: 40
Payload:
</sen/temp>
With this response, the RD would answer the previous step's request:
Res: 2.04 Changed
The sequence of fetching the registration content before sending a
successful response was chosen to make responses reliable, and the
caching item was chosen to still allow very constrained registrants.
Registrants MUST be able to serve a GET request to "/.well-known/ Registrants MUST be able to serve a GET request to "/.well-known/
core" after having requested registration. Constrained devices MAY core" after having requested registration. Constrained devices MAY
regard the initial request as temporarily failed when they need RAM regard the initial request as temporarily failed when they need RAM
occupied by their own request to serve the RD's GET, and retry later occupied by their own request to serve the RD's GET, and retry later
when the RD already has a cached representation of their discovery when the RD already has a cached representation of their discovery
resources. Then, the RD can reply immediately and the registrant can resources. Then, the RD can reply immediately and the registrant can
receive the response.) receive the response.
The simple registration request interface is specified as follows: The simple registration request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /.well-known/core{?ep,d,lt,extra-attrs*} URI Template: /.well-known/core{?ep,d,lt,extra-attrs*}
URI Template Variables are as they are for registration in
Section 5.3. The base attribute is not accepted to keep the
registration interface simple; that rules out registration over CoAP-
over-TCP or HTTP that would need to specify one.
The following response codes are defined for this interface:
Success: 2.04 "Changed".
Failure: 4.00 "Bad Request". Malformed request. URI Template Variables are as they are for registration in Section 5.
The base attribute is not accepted to keep the registration interface
simple; that rules out registration over CoAP-over-TCP or HTTP that
would need to specify one.
Failure: 5.03 "Service Unavailable". Service could not perform the The following response is expected on this interface:
operation.
HTTP support: NO Success: 2.04 "Changed".
For the second interaction triggered by the above, the registrant-ep For the second interaction triggered by the above, the registrant-ep
takes the role of server and the RD the role of client. (Note that takes the role of server and the RD the role of client. (Note that
this is exactly the Well-Known Interface of [RFC6690] Section 4): this is exactly the Well-Known Interface of [RFC6690] Section 4):
Interaction: RD -> EP Interaction: RD -> EP
Method: GET Method: GET
URI Template: /.well-known/core URI Template: /.well-known/core
The following response codes are defined for this interface: The following response is expected on this interface:
Success: 2.05 "Content". Success: 2.05 "Content".
Failure: 4.00 "Bad Request". Malformed request. The RD MUST delete registrations created by simple registration after
the expiration of their lifetime. Additional operations on the
Failure: 4.04 "Not Found". /.well-known/core does not exist. registration resource cannot be executed because no registration
location is returned.
Failure: 5.03 "Service Unavailable". Service could not perform the
operation.
HTTP support: NO
The registration resources MUST be deleted after the expiration of
their lifetime. Additional operations on the registration resource
cannot be executed because no registration location is returned.
The following example shows a registrant-ep using Simple
Registration, by simply sending an empty POST to a resource
directory.
Req: (to RD server from [2001:db8:2::1])
POST /.well-known/core?lt=6000&ep=node1
No payload
Req: (from RD server to [2001:db8:2::1])
GET /.well-known/core
Accept: 40
Res: (to the RD from [2001:db8:2::1] ) 2.05 Content
Content-Format: 40
Payload:
</sen/temp>
Res: (from the RD to [2001:db8:2::1]) 2.04 Changed
5.3.2. Third-party registration 5.2. Third-party registration
For some applications, even Simple Registration may be too taxing for For some applications, even Simple Registration may be too taxing for
some very constrained devices, in particular if the security some very constrained devices, in particular if the 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 party device, called a Directory can be filled by a third party device, called a
Commissioning Tool (CT). The commissioning tool can fill the Commissioning Tool (CT). The commissioning tool can fill the
Resource Directory from a database or other means. For that purpose Resource Directory from a database or other means. For that purpose
scheme, IP address and port of the URI of the registered device is scheme, IP address and port of the URI of the registered device is
the value of the "base" parameter of the registration described in the value of the "base" parameter of the registration described in
Section 5.3. Section 5.
It should be noted that the value of the "base" parameter applies to It should be noted that the value of the "base" parameter applies to
all the links of the registration and has consequences for the anchor all the links of the registration and has consequences for the anchor
value of the individual links as exemplified in Appendix B. An value of the individual links as exemplified in Appendix B. An
eventual (currently non-existing) "base" attribute of the link is not eventual (currently non-existing) "base" attribute of the link is not
affected by the value of "base" parameter in the registration. affected by the value of "base" parameter in the registration.
5.4. Operations on the Registration Resource 5.3. Operations on the Registration Resource
This section describes how the registering endpoint can maintain the This section describes how the registering endpoint can maintain the
registrations that it created. The registering endpoint can be the registrations that it created. The registering endpoint can be the
registrant-ep or the CT. An endpoint SHOULD NOT use this interface registrant-ep or the CT. An endpoint SHOULD NOT use this interface
for registrations that it did not create. The registrations are for registrations that it did not create. The registrations are
resources of the RD. resources of the RD.
After the initial registration, the registering endpoint retains the After the initial registration, the registering endpoint retains 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
skipping to change at page 29, line 18 skipping to change at page 29, line 14
registration resource for the purpose of garbage collection. If the registration resource for the purpose of garbage collection. If the
Registration Resource is removed, the corresponding endpoint will Registration Resource is removed, the corresponding endpoint will
need to be re-registered. need to be re-registered.
The Registration Resource may also be used cancel the registration The Registration Resource may also be used cancel the registration
using DELETE, and to perform further operations beyond the scope of using DELETE, and to perform further operations beyond the scope of
this specification. this specification.
These operations are described below. These operations are described below.
5.4.1. Registration Update 5.3.1. Registration Update
The update interface is used by the registering endpoint to refresh The update interface is used by the registering endpoint to refresh
or update its registration with an RD. To use the interface, the or update its registration with an RD. To use the interface, the
registering endpoint sends a POST request to the registration registering endpoint sends a POST request to the registration
resource returned by the initial registration operation. resource returned by the initial registration operation.
An update MAY update the lifetime or the base URI registration An update MAY update the lifetime or the base URI registration
parameters "lt", "base" as in Section 5.3. Parameters that are not parameters "lt", "base" as in Section 5. Parameters that are not
being changed SHOULD NOT be included in an update. Adding parameters being changed SHOULD NOT be included in an update. Adding parameters
that have not changed increases the size of the message but does not that have not changed increases the size of the message but does not
have any other implications. Parameters MUST be included as query have any other implications. Parameters MUST be included as query
parameters in an update operation as in Section 5.3. parameters in an update operation as in Section 5.
A registration update resets the timeout of the registration to the A registration update resets the timeout of the registration to the
(possibly updated) lifetime of the registration, independent of (possibly updated) lifetime of the registration, independent of
whether a "lt" parameter was given. whether a "lt" parameter was given.
If the base URI of the registration is changed in an update, relative If the base URI of the registration is changed in an update, relative
references submitted in the original registration or later updates references submitted in the original registration or later updates
are resolved anew against the new base. are resolved anew against the new base.
The registration update operation only describes the use of POST with The registration update operation only describes the use of POST with
an empty payload. Future standards might describe the semantics of an empty payload. Future standards might describe the semantics of
using content formats and payloads with the POST method to update the using content formats and payloads with the POST method to update the
links of a registration (see Section 5.4.3). links of a registration (see Section 5.3.3).
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,base,extra-attrs*} URI Template: {+location}{?lt,base,extra-attrs*}
URI Template Variables: URI Template Variables:
location := This is the Location returned by the RD as a result location := This is the Location returned by the RD as a 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 90000) SHOULD be used. original registration (falling back to 90000) SHOULD be used.
skipping to change at page 30, line 34 skipping to change at page 30, line 33
URI. URI.
extra-attrs := Additional registration attributes (optional). As extra-attrs := Additional registration attributes (optional). As
with the registration, the RD processes them if it knows their with the registration, the RD processes them if it knows their
semantics. Otherwise, unknown attributes are stored as semantics. Otherwise, unknown attributes are stored as
endpoint attributes, overriding any previously stored endpoint endpoint attributes, overriding any previously stored endpoint
attributes of the same key. attributes of the same key.
Content-Format: none (no payload) Content-Format: none (no payload)
The following response codes are defined for this interface: The following responses are expected on this interface:
Success: 2.04 "Changed" or 204 "No Content" if the update was Success: 2.04 "Changed" or 204 "No Content" if the update was
successfully processed. successfully processed.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
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 been removed). exist (e.g. may have been removed).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". If the registration fails in any way, including "Not Found" and
Service could not perform the operation. request timeouts, or if the time indicated in a Service Unabailable
Max-Age/Retry-After exceeds the remaining lifetime, the registering
HTTP support: YES
If the registration update fails with a "Service Unavailable"
response and a Max-Age option or Retry-After header, the registering
endpoint SHOULD retry the operation after the time indicated. If the
registration fails in another way, including request timeouts, or if
the time indicated exceeds the remaining lifetime, the registering
endpoint SHOULD attempt registration again. endpoint SHOULD attempt registration again.
The following example shows how the registering endpoint updates its The following example shows how the registering endpoint updates its
registration resource at an RD using this interface with the example registration resource at an RD using this interface with the example
location value: /rd/4521. location value: /rd/4521.
Req: POST /rd/4521 Req: POST /rd/4521
Res: 2.04 Changed Res: 2.04 Changed
The following example shows the registering endpoint updating its The following example shows the registering endpoint updating its
registration resource at an RD using this interface with the example registration resource at an RD using this interface with the example
location value: /rd/4521. The initial registration by the location value: /rd/4521. The initial registration by the
registering endpoint set the following values: registering endpoint set the following values:
o endpoint name (ep)=endpoint1 o endpoint name (ep)=endpoint1
o lifetime (lt)=500 o lifetime (lt)=500
o Base URI (base)=coap://local-proxy-old.example.com:5683 o Base URI (base)=coap://local-proxy-old.example.com:5683
skipping to change at page 32, line 14 skipping to change at page 32, line 5
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content Res: 2.01 Content
Payload: Payload:
<coaps://new.example.com:5684/sensors/temp>;ct=41;rt="temperature"; <coaps://new.example.com:5684/sensors/temp>;ct=41;rt="temperature";
anchor="coap://spurious.example.com:5683", anchor="coap://spurious.example.com:5683",
<coaps://new.example.com:5684/sensors/light>;ct=41;rt="light-lux"; <coaps://new.example.com:5684/sensors/light>;ct=41;rt="light-lux";
if="sensor"; anchor="coaps://new.example.com:5684", if="sensor"; anchor="coaps://new.example.com:5684",
5.4.2. Registration Removal 5.3.2. Registration Removal
Although RD registrations have soft state and will eventually timeout Although RD registrations have soft state and will eventually timeout
after their lifetime, the registering endpoint SHOULD explicitly after their lifetime, the registering endpoint SHOULD explicitly
remove an entry from the RD if it knows it will no longer be remove an entry from the RD if it knows it will no longer be
available (for example on shut-down). This is accomplished using a available (for example on shut-down). This is accomplished using a
removal interface on the RD by performing a DELETE on the endpoint removal interface on the RD by performing a DELETE on the endpoint
resource. resource.
The removal request interface is specified as follows: The removal request interface is specified as follows:
skipping to change at page 32, line 36 skipping to change at page 32, line 27
Method: DELETE Method: DELETE
URI Template: {+location} URI Template: {+location}
URI Template Variables: URI Template Variables:
location := This is the Location returned by the RD as a result location := This is the Location returned by the RD as a result
of a successful earlier registration. of a successful earlier registration.
The following response codes are defined for this interface: The following responses are expected on 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
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 already have been removed). exist (e.g. may already have been removed).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation.
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 with example location value /rd/4521. the RD with example location value /rd/4521.
Req: DELETE /rd/4521 Req: DELETE /rd/4521
Res: 2.02 Deleted Res: 2.02 Deleted
5.4.3. Further operations 5.3.3. Further operations
Additional operations on the registration can be specified in future Additional operations on the registration can be specified in future
documents, for example: documents, for example:
o Send iPATCH (or PATCH) updates ([RFC8132]) to add, remove or o Send iPATCH (or PATCH) updates ([RFC8132]) to add, remove or
change the links of a registration. change the links of a registration.
o Use GET to read the currently stored set of links in a o Use GET to read the currently stored set of links in a
registration resource. registration resource.
skipping to change at page 35, line 43 skipping to change at page 35, line 28
Interaction: Client -> RD Interaction: Client -> RD
Method: GET Method: GET
URI Template: {+type-lookup-location}{?page,count,search*} URI Template: {+type-lookup-location}{?page,count,search*}
URI Template Variables: URI Template Variables:
type-lookup-location := RD Lookup URI for a given lookup type type-lookup-location := RD Lookup URI for a given lookup type
(mandatory). The address is discovered as described in (mandatory). The address is discovered as described in
Section 5.2. Section 4.3.
search := Search criteria for limiting the number of results search := Search criteria for limiting the number of results
(optional). (optional).
page := Page (optional). Parameter cannot be used without the page := Page (optional). Parameter cannot be used without the
count parameter. Results are returned from result set in pages count parameter. Results are returned from result set in pages
that contain 'count' links starting from index (page * count). that contain 'count' links starting from index (page * count).
Page numbering starts with zero. Page numbering starts with zero.
count := Count (optional). Number of results is limited to this count := Count (optional). Number of results is limited to this
skipping to change at page 36, line 24 skipping to change at page 36, line 11
media type representing web links media type representing web links
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" with an "application/link- Success: 2.05 "Content" or 200 "OK" with an "application/link-
format" or other web link payload containing matching entries for format" or other web link payload containing matching entries for
the lookup. The payload can contain zero links (which is an empty the lookup. The payload can contain zero links (which is an empty
payload in [RFC6690] link format, but could also be "[]" in JSON payload in [RFC6690] link format, but could also be "[]" in JSON
based formats), indicating that no entities matched the request. based formats), indicating that no entities matched the request.
Failure: No error response to a multicast request.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation.
HTTP support: YES
6.3. Resource lookup examples 6.3. Resource lookup examples
The examples in this section assume the existence of CoAP hosts with The examples in this section assume the existence of CoAP hosts with
a default CoAP port 61616. HTTP hosts are possible and do not change a default CoAP port 61616. HTTP hosts are possible and do not change
the nature of the examples. 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 resource look-up locations discovered in Figure 5: with the example resource look-up locations discovered in Figure 5:
Req: GET /rd-lookup/res?rt=temperature Req: GET /rd-lookup/res?rt=temperature
skipping to change at page 39, line 46 skipping to change at page 38, line 46
well as a constant resource type (rt="core.rd-ep"); the lifetime (lt) well as a constant resource type (rt="core.rd-ep"); the lifetime (lt)
is not reported. Additional endpoint attributes are added as target is not reported. Additional endpoint attributes are added as target
attributes to their endpoint link unless their specification says attributes to their endpoint link unless their specification says
otherwise. otherwise.
Links to endpoints SHOULD be presented in path-absolute form or, if Links to endpoints SHOULD be presented in path-absolute form or, if
required, as absolute references. (This avoids the RFC6690 required, as absolute references. (This avoids the RFC6690
ambiguities.) ambiguities.)
Base addresses that contain link-local addresses MUST NOT include Base addresses that contain link-local addresses MUST NOT include
zone identifiers, and such registrations MUST NOT be show unless the zone identifiers, and such registrations MUST NOT be shown unless the
lookup was made from the same link from which the registration was lookup was made from the same link from which the registration was
made. made.
While Endpoint Lookup does expose the registration resources, the RD While Endpoint Lookup does expose the registration resources, the RD
does not need to make them accessible to clients. Clients SHOULD NOT does not need to make them accessible to clients. Clients SHOULD NOT
attempt to dereference or manipulate them. attempt to dereference or manipulate them.
A Resource Directory can report endpoints in lookup that are not A Resource Directory can report endpoints in lookup that are not
hosted at the same address. Lookup clients MUST be prepared to see hosted at the same address. Lookup clients MUST be prepared to see
arbitrary URIs as registration resources in the results and treat arbitrary URIs as registration resources in the results and treat
skipping to change at page 40, line 35 skipping to change at page 39, line 35
The Resource Directory (RD) provides assistance to applications The Resource Directory (RD) provides assistance to applications
situated on a selection of nodes to discover endpoints on connected situated on a selection of nodes to discover endpoints on connected
nodes. This section discusses different security aspects of nodes. This section discusses different security aspects of
accessing the RD. accessing the RD.
The contents of the RD are inserted in two ways: The contents of the RD are inserted in two ways:
1. The node hosting the discoverable endpoint fills the RD with the 1. The node hosting the discoverable endpoint fills the RD with the
contents of /.well-known/core by: contents of /.well-known/core by:
* Storing the contents directly into RD (see Section 5.3) * Storing the contents directly into RD (see Section 5)
* Requesting the RD to load the contents from /.well-known/core * Requesting the RD to load the contents from /.well-known/core
(see Section 5.3.1) (see Section 5.1)
2. A Commissioning Tool (CT) fills the RD with endpoint information 2. A Commissioning Tool (CT) fills the RD with endpoint information
for a set of discoverable nodes. (see Section 5.3 with for a set of discoverable nodes. (see Section 5 with
base=authority parameter value) base=authority parameter value)
In both cases, the nodes filling the RD should be authenticated and In both cases, the nodes filling the RD should be authenticated and
authorized to change the contents of the RD. An Authorization Server authorized to change the contents of the RD. An Authorization Server
(AS) is responsible to assign a token to the registering node to (AS) is responsible to assign a token to the registering node to
authorize the node to discover or register endpoints in a given RD authorize the node to discover or register endpoints in a given RD
[I-D.ietf-ace-oauth-authz]. [I-D.ietf-ace-oauth-authz].
It can be imagined that an installation is divided in a set of It can be imagined that an installation is divided in a set of
security regions, each one with its own RD(s) to discover the security regions, each one with its own RD(s) to discover the
skipping to change at page 41, line 38 skipping to change at page 40, line 38
A separate document needs to specify these aspects to ensure A separate document needs to specify these aspects to ensure
interoperability between registering nodes and RD. The subsections interoperability between registering nodes and RD. The subsections
below give some hints how to handle a subset of the different below give some hints how to handle a subset of the different
aspects. aspects.
7.1. Secure RD discovery 7.1. Secure RD discovery
The Resource Server (RS) discussed in [I-D.ietf-ace-oauth-authz] is The Resource Server (RS) discussed in [I-D.ietf-ace-oauth-authz] is
equated to the RD. The client (C) needs to discover the RD as equated to the RD. The client (C) needs to discover the RD as
discussed in Section 4. C can discover the related AS by sending a discussed in Section 4.1. C can discover the related AS by sending a
request to the RD. The RD denies the request by sending the address request to the RD. The RD denies the request by sending the address
of the related AS, as discussed in section 5.1 of of the related AS, as discussed in section 5.1 of
[I-D.ietf-ace-oauth-authz]. The client MUST send an authorization [I-D.ietf-ace-oauth-authz]. The client MUST send an authorization
request to the AS. When appropriate, the AS returns a token that request to the AS. When appropriate, the AS returns a token that
specifies the authorization permission which needs to be specified in specifies the authorization permission which needs to be specified in
a separate document. a separate document.
7.2. Secure RD filtering 7.2. Secure RD filtering
The authorized parameter values for the queries by a given endpoint The authorized parameter values for the queries by a given endpoint
skipping to change at page 44, line 14 skipping to change at page 43, line 14
9.1. Resource Types 9.1. Resource Types
IANA is asked to enter the following values into the Resource Type IANA is asked to enter the following values into the Resource Type
(rt=) Link Target Attribute Values sub-registry of the Constrained (rt=) Link Target Attribute Values sub-registry of the Constrained
Restful Environments (CoRE) Parameters registry defined in [RFC6690]: Restful Environments (CoRE) Parameters registry defined in [RFC6690]:
+--------------------+--------------------------+-------------------+ +--------------------+--------------------------+-------------------+
| Value | Description | Reference | | Value | Description | Reference |
+--------------------+--------------------------+-------------------+ +--------------------+--------------------------+-------------------+
| core.rd | Directory resource of an | RFCTHIS Section | | core.rd | Directory resource of an | RFCTHIS Section |
| | RD | 5.2 | | | RD | 4.3 |
| core.rd-lookup-res | Resource lookup of an RD | RFCTHIS Section | | core.rd-lookup-res | Resource lookup of an RD | RFCTHIS Section |
| | | 5.2 | | | | 4.3 |
| core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS Section | | core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS Section |
| | | 5.2 | | | | 4.3 |
| core.rd-ep | Endpoint resource of an | RFCTHIS Section 6 | | core.rd-ep | Endpoint resource of an | RFCTHIS Section 6 |
| | RD | | | | RD | |
+--------------------+--------------------------+-------------------+ +--------------------+--------------------------+-------------------+
9.2. IPv6 ND Resource Directory Address Option 9.2. IPv6 ND Resource Directory Address Option
This document registers one new ND option type under the sub-registry This document registers one new ND option type under the sub-registry
"IPv6 Neighbor Discovery Option Formats": "IPv6 Neighbor Discovery Option Formats":
o Resource Directory address Option (38) o Resource Directory Address Option (38)
9.3. RD Parameter Registry 9.3. RD Parameter Registry
This specification defines a new sub-registry for registration and This specification defines a new sub-registry for registration and
lookup parameters called "RD Parameters" under "CoRE Parameters". lookup parameters called "RD Parameters" under "CoRE Parameters".
Although this specification defines a basic set of parameters, it is Although this specification defines a basic set of parameters, it is
expected that other standards that make use of this interface will expected that other standards that make use of this interface will
define new ones. define new ones.
Each entry in the registry must include Each entry in the registry must include
skipping to change at page 49, line 43 skipping to change at page 48, line 43
| 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 the RD's address, and has performed It is assumed that the CT knows the RD's address, and has performed
URI discovery on it that returned a response like the one in the URI discovery on it that returned a response like the one in the
Section 5.2 example. Section 4.3 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 registration base URI parameter (base) to specify the RD using the registration base URI parameter (base) to specify the
interface address: interface address:
Req: POST coap://[2001:db8:4::ff]/rd Req: POST coap://[2001:db8:4::ff]/rd
?ep=lm_R2-4-015_wndw&base=coap://[2001:db8:4::1]&d=R2-4-015 ?ep=lm_R2-4-015_wndw&base=coap://[2001:db8:4::1]&d=R2-4-015
Payload: Payload:
</light/left>;rt="light", </light/left>;rt="light",
</light/middle>;rt="light", </light/middle>;rt="light",
skipping to change at page 55, line 13 skipping to change at page 54, line 13
</1>,</1/0>,</3/0>,</5> </1>,</1/0>,</3/0>,</5>
This link format payload indicates that object ID 1 (LWM2M Server This link format payload indicates that object ID 1 (LWM2M Server
Object) is supported, with a single instance 0 existing, object ID 3 Object) is supported, with a single instance 0 existing, object ID 3
(LWM2M Device object) is supported, with a single instance 0 (LWM2M Device object) is supported, with a single instance 0
existing, and object 5 (LWM2M Firmware Object) is supported, with no existing, and object 5 (LWM2M Firmware Object) is supported, with no
existing instances. existing instances.
10.2.3. LWM2M Update Endpoint Registration 10.2.3. LWM2M Update Endpoint Registration
The LwM2M update is really very similar to the registration update as The LwM2M update is really very similar to the registration update as
described in Section 5.4.1, with the only difference that there are described in Section 5.3.1, with the only difference that there are
more parameters defined and available. All the parameters listed in more parameters defined and available. All the parameters listed in
that section are also available with the initial registration but are that section are also available with the initial registration but are
all optional: all optional:
lt - Registration Lifetime lt - Registration Lifetime
b - Protocol Binding b - Protocol Binding
sms - MSISDN sms - MSISDN
link payload - new or modified links link payload - new or modified links
A Registration update is also specified to be used to update the A Registration update is also specified to be used to update the
LWM2M server whenever the endpoint's UDP port or IP address are LWM2M server whenever the endpoint's UDP port or IP address are
changed. changed.
10.2.4. LWM2M De-Register Endpoint 10.2.4. LWM2M De-Register Endpoint
LWM2M allows for de-registration using the delete method on the LWM2M allows for de-registration using the delete method on the
returned location from the initial registration operation. LWM2M de- returned location from the initial registration operation. LWM2M de-
registration proceeds as described in Section 5.4.2. registration proceeds as described in Section 5.3.2.
11. Acknowledgments 11. Acknowledgments
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, Jim Schaad, Mohit Sethi, Hauke Petersen, Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen,
Hannes Tschofenig, Sampo Ukkola, Linyi Tian, and Jan Newmarch have Hannes Tschofenig, Sampo Ukkola, Linyi Tian, Jan Newmarch, Matthias
provided helpful comments, discussions and ideas to improve and shape Kovatsch and Jaime Jimenez have provided helpful comments,
this document. Zach would also like to thank his colleagues from the discussions and ideas to improve and shape this document. Zach would
EU FP7 SENSEI project, where many of the resource directory concepts also like to thank his colleagues from the EU FP7 SENSEI project,
were originally developed. where many of the resource directory concepts were originally
developed.
12. Changelog 12. Changelog
changes from -19 to -20
(Processing comments from the WG chair review)
o Define the permissible characters in endpoint and sector names
o Express requirements on NAT situations in more abstract terms
o Shifted heading levels to have the interfaces on the same level
o Group instructions for error handling into general section
o Simple Registration: process reflowed into items list
o Updated introduction to reflect state of CoRE in general,
reference RFC7228 (defining "constrained") and use "IoT" term in
addition to "M2M"
o Update acknowledgements
o Assorted editorial changes
* Unify examples style
* Terminology: RDAO defined and not only expanded
* Add CT to Figure 1
* Consistency in the use of the term "Content Format"
changes from -18 to -19 changes from -18 to -19
o link-local addresses: allow but prescribe split-horizon fashion o link-local addresses: allow but prescribe split-horizon fashion
when used, disallow zone identifiers when used, disallow zone identifiers
o Remove informative references to documents not mentioned any more o Remove informative references to documents not mentioned any more
changes from -17 to -18 changes from -17 to -18
o Rather than re-specifying link format (Modernized Link Format), o Rather than re-specifying link format (Modernized Link Format),
describe a Limited Link Format that's the uncontested subset of describe a Limited Link Format that's the uncontested subset of
Link Format Link Format
o Acknowledging the -17 version as part of the draft o Acknowledging the -17 version as part of the draft
o Move "Read endpoint links" operation to future specification like o Move "Read endpoint links" operation to future specification like
PATCH PATCH
skipping to change at page 64, line 51 skipping to change at page 64, line 32
Systems Vol. 1, pp. 9-36, DOI 10.1145/320434.320440, March Systems Vol. 1, pp. 9-36, DOI 10.1145/320434.320440, March
1976. 1976.
[I-D.bormann-t2trg-rel-impl] [I-D.bormann-t2trg-rel-impl]
Bormann, C., "impl-info: A link relation type for Bormann, C., "impl-info: A link relation type for
disclosing implementation information", draft-bormann- disclosing implementation information", draft-bormann-
t2trg-rel-impl-00 (work in progress), January 2018. t2trg-rel-impl-00 (work in progress), January 2018.
[I-D.hartke-t2trg-coral] [I-D.hartke-t2trg-coral]
Hartke, K., "The Constrained RESTful Application Language Hartke, K., "The Constrained RESTful Application Language
(CoRAL)", draft-hartke-t2trg-coral-06 (work in progress), (CoRAL)", draft-hartke-t2trg-coral-07 (work in progress),
October 2018. February 2019.
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE) using the OAuth 2.0 Constrained Environments (ACE) using the OAuth 2.0
Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-17 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-22
(work in progress), November 2018. (work in progress), March 2019.
[I-D.ietf-core-links-json] [I-D.ietf-core-links-json]
Li, K., Rahman, A., and C. Bormann, "Representing Li, K., Rahman, A., and C. Bormann, "Representing
Constrained RESTful Environments (CoRE) Link Format in Constrained RESTful Environments (CoRE) Link Format in
JSON and CBOR", draft-ietf-core-links-json-10 (work in JSON and CBOR", draft-ietf-core-links-json-10 (work in
progress), February 2018. progress), February 2018.
[I-D.silverajan-core-coap-protocol-negotiation] [I-D.silverajan-core-coap-protocol-negotiation]
Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation", Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation",
draft-silverajan-core-coap-protocol-negotiation-09 (work draft-silverajan-core-coap-protocol-negotiation-09 (work
in progress), July 2018. in progress), July 2018.
[RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
"Transmission of IPv6 Packets over IEEE 802.15.4
Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007,
<https://www.rfc-editor.org/info/rfc4944>.
[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,
<https://www.rfc-editor.org/info/rfc6775>. <https://www.rfc-editor.org/info/rfc6775>.
[RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing
IPv6 Zone Identifiers in Address Literals and Uniform IPv6 Zone Identifiers in Address Literals and Uniform
Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874,
February 2013, <https://www.rfc-editor.org/info/rfc6874>. February 2013, <https://www.rfc-editor.org/info/rfc6874>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014,
<https://www.rfc-editor.org/info/rfc7228>.
[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,
<https://www.rfc-editor.org/info/rfc7230>. <https://www.rfc-editor.org/info/rfc7230>.
[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,
<https://www.rfc-editor.org/info/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
skipping to change at page 68, line 47 skipping to change at page 68, line 38
Because ""/temp"" starts with a single slash, the record's target is Because ""/temp"" starts with a single slash, the record's target is
resolved by replacing the path ""/.well-known/core"" from the Base resolved by replacing the path ""/.well-known/core"" from the Base
URI (section 5.2 [RFC3986]) with the relative target URI ""/temp"" URI (section 5.2 [RFC3986]) with the relative target URI ""/temp""
into ""coap://[2001:db8:f0::1]/temp"". into ""coap://[2001:db8:f0::1]/temp"".
B.1.2. Interpreting attributes and relations B.1.2. Interpreting attributes and relations
Some more information but the record's target can be obtained from Some more information but the record's target can be obtained from
the payload: the resource type of the target is "temperature", and the payload: the resource type of the target is "temperature", and
its content type is text/plain (ct=0). its content format is text/plain (ct=0).
A relation in a web link is a three-part statement that specifies a A relation in a web link is a three-part statement that specifies a
named relation between the so-called "context resource" and the named relation between the so-called "context resource" and the
target resource, like "_This page_ has _its table of contents_ at _/ target resource, like "_This page_ has _its table of contents_ at _/
toc.html_". In link format documents, there is an implicit "host toc.html_". In link format documents, there is an implicit "host
relation" specified with default parameter: rel="hosts". relation" specified with default parameter: rel="hosts".
In our example, the context resource of the link is the URI specified In our example, the context resource of the link is the URI specified
in the GET request "coap:://[2001:db8:f0::1]/.well-known/core". A in the GET request "coap:://[2001:db8:f0::1]/.well-known/core". A
full English expression of the "host relation" is: full English expression of the "host relation" is:
 End of changes. 90 change blocks. 
281 lines changed or deleted 275 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/