< draft-ietf-core-resource-directory-23.txt   draft-ietf-core-resource-directory-24.txt >
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft ARM Internet-Draft ARM
Intended status: Standards Track M. Koster Intended status: Standards Track M. Koster
Expires: January 9, 2020 SmartThings Expires: 10 September 2020 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. Amsüss, Ed.
July 08, 2019 9 March 2020
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-23 draft-ietf-core-resource-directory-24
Abstract Abstract
In many IoT 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
in conjunction with an RD are defined. in conjunction with an RD are defined.
Note to Readers
Discussion of this document takes place on the CORE Working Group
mailing list (core@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/core/
(https://mailarchive.ietf.org/arch/browse/core/).
Source for this draft and an issue tracker can be found at
https://github.com/core-wg/resource-directory (https://github.com/
core-wg/resource-directory).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at 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 January 9, 2020. This Internet-Draft will expire on 10 September 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 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/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
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 . . . . . . . . . . . . . . . . 14 3.7. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 14
4. RD discovery and other interface-independent components . . . 14 4. RD discovery and other interface-independent components . . . 14
4.1. Finding a Resource Directory . . . . . . . . . . . . . . 15 4.1. Finding a Resource Directory . . . . . . . . . . . . . . 15
4.1.1. Resource Directory Address Option (RDAO) . . . . . . 17 4.1.1. Resource Directory Address Option (RDAO) . . . . . . 17
4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 18 4.1.2. Using DNS-SD to discover a resource directory . . . . 19
4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 19
4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19 4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19
5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 21 5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 22
5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26 5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26
5.2. Third-party registration . . . . . . . . . . . . . . . . 28 5.2. Third-party registration . . . . . . . . . . . . . . . . 28
5.3. Operations on the Registration Resource . . . . . . . . . 29 5.3. Operations on the Registration Resource . . . . . . . . . 29
5.3.1. Registration Update . . . . . . . . . . . . . . . . . 29 5.3.1. Registration Update . . . . . . . . . . . . . . . . . 29
5.3.2. Registration Removal . . . . . . . . . . . . . . . . 32 5.3.2. Registration Removal . . . . . . . . . . . . . . . . 33
5.3.3. Further operations . . . . . . . . . . . . . . . . . 33 5.3.3. Further operations . . . . . . . . . . . . . . . . . 33
6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 34 6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 34
6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 34 6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 35
6.3. Resource lookup examples . . . . . . . . . . . . . . . . 36 6.3. Resource lookup examples . . . . . . . . . . . . . . . . 37
6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 39 6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 39
7. Security policies . . . . . . . . . . . . . . . . . . . . . . 40 7. Security policies . . . . . . . . . . . . . . . . . . . . . . 40
7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 41 7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 41
7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 42 7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 42
7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 42 7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 42
8. Security Considerations . . . . . . . . . . . . . . . . . . . 42 8. Security Considerations . . . . . . . . . . . . . . . . . . . 42
8.1. Endpoint Identification and Authentication . . . . . . . 42 8.1. Endpoint Identification and Authentication . . . . . . . 42
8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 43 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 43
8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 43 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 43
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 44 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 44
9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 44 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 44
9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 44 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 44
9.3.1. Full description of the "Endpoint Type" Registration 9.3.1. Full description of the "Endpoint Type" Registration
Parameter . . . . . . . . . . . . . . . . . . . . . . 46 Parameter . . . . . . . . . . . . . . . . . . . . . . 47
9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 46 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 47
9.5. Multicast Address Registration . . . . . . . . . . . . . 47 9.5. Multicast Address Registration . . . . . . . . . . . . . 48
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47 9.6. Well-Kown URIs . . . . . . . . . . . . . . . . . . . . . 48
10.1. Lighting Installation . . . . . . . . . . . . . . . . . 48 9.7. Service Names and Transport Protocol Port Number
10.1.1. Installation Characteristics . . . . . . . . . . . . 48 Registry . . . . . . . . . . . . . . . . . . . . . . . . 48
10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 49 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 49
10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 52 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 49
10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 52 10.1.1. Installation Characteristics . . . . . . . . . . . . 49
10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 54 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 50
10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 55 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 54
10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 56 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 54
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 56 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 56
12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 56 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 57
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 58
13.1. Normative References . . . . . . . . . . . . . . . . . . 66 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58
13.2. Informative References . . . . . . . . . . . . . . . . . 66 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Appendix A. Groups Registration and Lookup . . . . . . . . . . . 68 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 68
Appendix B. Web links and the Resource Directory . . . . . . . . 70 13.1. Normative References . . . . . . . . . . . . . . . . . . 68
B.1. A simple example . . . . . . . . . . . . . . . . . . . . 70 13.2. Informative References . . . . . . . . . . . . . . . . . 69
B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 71 Appendix A. Groups Registration and Lookup . . . . . . . . . . . 71
B.1.2. Interpreting attributes and relations . . . . . . . . 71 Appendix B. Web links and the Resource Directory . . . . . . . . 73
B.2. A slightly more complex example . . . . . . . . . . . . . 71 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 73
B.3. Enter the Resource Directory . . . . . . . . . . . . . . 72 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 74
B.4. A note on differences between link-format and Link B.1.2. Interpreting attributes and relations . . . . . . . . 74
headers . . . . . . . . . . . . . . . . . . . . . . . . . 74 B.2. A slightly more complex example . . . . . . . . . . . . . 74
Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 75 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 75
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75 B.4. A note on differences between link-format and Link header
fields . . . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 78
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78
1. Introduction 1. Introduction
In the work on Constrained RESTful Environments (CoRE), a REST In the work on Constrained RESTful Environments (CoRE), a REST
architecture suitable for constrained nodes (e.g. with limited RAM architecture suitable for constrained nodes (e.g. with limited RAM
and ROM [RFC7228]) and networks (e.g. 6LoWPAN [RFC4944]) has been and ROM [RFC7228]) and networks (e.g. 6LoWPAN [RFC4944]) has been
established and is used in Internet-of-Things (IoT) or machine-to- established and is used in Internet-of-Things (IoT) or machine-to-
machine (M2M) applications such as smart energy and building machine (M2M) applications such as smart energy and building
automation. automation.
skipping to change at page 7, line 49 skipping to change at page 8, line 19
+----+ ---- | | +----+ ---- | |
--|- +------+ | --|- +------+ |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
| EP | ---------|-----| RD |----|-----| Client | | EP | ---------|-----| RD |----|-----| Client |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
--|- +------+ | --|- +------+ |
+----+ ---- | | +----+ ---- | |
| CT |---- | | | 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.
3.3. RD Content Model 3.3. RD Content Model
skipping to change at page 9, line 37 skipping to change at page 9, line 37
| |
| 1 ooooooooo | 1 ooooooooo
+-----o context o +-----o context o
ooooooooo ooooooooo
Figure 2: E-R Model of the content of /.well-known/core Figure 2: E-R Model of the content of /.well-known/core
The model shown in Figure 2 models the contents of /.well-known/core The model shown in Figure 2 models the contents of /.well-known/core
which contains: which contains:
o a set of links belonging to the hosting web server * a set of links belonging to the hosting web server
The web server is free to choose links it deems appropriate to be The web server is free to choose links it deems appropriate to be
exposed in its ".well-known/core". Typically, the links describe exposed in its ".well-known/core". Typically, the links describe
resources that are served by the host, but the set can also contain resources that are served by the host, but the set can also contain
links to resources on other servers (see examples in [RFC6690] page links to resources on other servers (see examples in [RFC6690] page
14). The set does not necessarily contain links to all resources 14). The set does not necessarily contain links to all resources
served by the host. served by the host.
A link has the following attributes (see [RFC8288]): A link has the following attributes (see [RFC8288]):
o Zero or more link relations: They describe relations between the * Zero or more link relations: They describe relations between the
link context and the link target. link context and the link target.
In link-format serialization, they are expressed as space- In link-format serialization, they are expressed as space-
separated values in the "rel" attribute, and default to "hosts". separated values in the "rel" attribute, and default to "hosts".
o A link context URI: It defines the source of the relation, e.g. * A link context URI: It defines the source of the relation, e.g.
_who_ "hosts" something. _who_ "hosts" something.
In link-format serialization, it is expressed in the "anchor" In link-format serialization, it is expressed in the "anchor"
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 * 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), * Other target attributes (e.g. resource type (rt), interface (if),
or content format (ct)). These provide additional information or content format (ct)). These provide additional information
about the target URI. about the target URI.
+----------------------+ +----------------------+
| resource-directory | | resource-directory |
+----------------------+ +----------------------+
| 1 | 1
| |
| |
| |
skipping to change at page 11, line 46 skipping to change at page 11, line 46
o lt o----+ ooooooooooo 0+ | o lt o----+ ooooooooooo 0+ |
oooooooo | o target o-----+ oooooooo | o target o-----+
| o attribute o | 0+ oooooo | o attribute o | 0+ oooooo
ooooooooooo 0+ | ooooooooooo +-----o rel o ooooooooooo 0+ | ooooooooooo +-----o rel o
o endpoint o----+ | oooooo o endpoint o----+ | oooooo
o attribute o | o attribute o |
ooooooooooo | 1 ooooooooo ooooooooooo | 1 ooooooooo
+----o context o +----o context o
ooooooooo ooooooooo
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, * 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 an endpoint name ("ep", a Unicode string) unique within a sector * an endpoint name ("ep", a Unicode string) unique within a sector
o a Registration Base URI ("base", a URI typically describing the * a Registration Base URI ("base", a URI typically describing the
scheme://authority part) scheme://authority part)
o a lifetime ("lt"), * a lifetime ("lt"),
o a registration resource location inside the RD ("href"), * a registration resource location inside the RD ("href"),
o optionally a sector ("d", a Unicode string) * optionally a sector ("d", a Unicode string)
o optional additional endpoint attributes (from Section 9.3) * 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.
3.4. Link-local addresses and zone identifiers 3.4. Link-local addresses and zone identifiers
skipping to change at page 14, line 30 skipping to change at page 14, line 30
The Resource Directory service need not be coupled with the data The Resource Directory service need not be coupled with the data
intermediary service. Mapping of Resource Directories to data intermediary service. Mapping of Resource Directories to data
intermediaries may be many-to-many. intermediaries may be many-to-many.
Metadata in web link formats like [RFC6690] which may be internally Metadata in web link formats like [RFC6690] which may be internally
stored as triples, or relation/attribute pairs providing metadata stored as triples, or relation/attribute pairs providing metadata
about resource links, need to be supported by Resource Directories . about resource links, need to be supported by Resource Directories .
External catalogues that are represented in other formats may be External catalogues that are represented in other formats may be
converted to common web linking formats for storage and access by converted to common web linking formats for storage and access by
Resource Directories. Since it is common practice for these to be Resource Directories. Since it is common practice for these to be
URN encoded, simple and lossless structural transforms should encoded in URNs [RFC8141], simple and lossless structural transforms
generally be sufficient to store external metadata in Resource should 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. RD discovery and other interface-independent components 4. RD discovery and other interface-independent components
skipping to change at page 15, line 27 skipping to change at page 15, line 27
they do not limit what a server may respond under atypical they do not limit what a server may respond under atypical
circumstances. circumstances.
REST clients (registrant-EPs / CTs, lookup clients, RD servers during REST clients (registrant-EPs / CTs, lookup clients, RD servers during
simple registrations) MUST be prepared to receive any unsuccessful simple registrations) MUST be prepared to receive any unsuccessful
code and act upon it according to its definition, options and/or code and act upon it according to its definition, options and/or
payload to the best of their capabilities, falling back to failing payload to the best of their capabilities, falling back to failing
the operation if recovery is not possible. In particular, they the operation if recovery is not possible. In particular, they
should retry the request upon 5.03 (Service Unavailable; 503 in HTTP) 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 according to the Max-Age (Retry-After in HTTP) option, and fall back
to link-format when receiving 4.15 (Unsupported Content Format; 415 to link-format when receiving 4.15 (Unsupported Content-Format; 415
in HTTP). in HTTP).
A resource directory MAY make the information submitted to it A resource directory MAY make the information submitted to it
available to further directories, if it can ensure that a loop does available to further directories, if it can ensure that a loop does
not form. The protocol used between directories to ensure loop-free not form. The protocol used between directories to ensure loop-free
operation is outside the scope of this document. operation is outside the scope of this document.
4.1. Finding a Resource Directory 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. Dependent on the operational directories for discovery purposes. Dependent on the operational
conditions, one or more of the techniques below apply. The use of conditions, one or more of the techniques below apply.
DNS-SD [RFC6763] is described in [I-D.ietf-core-rd-dns-sd].
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
target network environment in which some of these preconfigured target network environment in which some of these preconfigured
nodes are to be brought up is then configured with a route for nodes are to be brought up is then configured with a route for
this anycast address that leads to an appropriate RD. (Instead this anycast address that leads to an appropriate RD. (Instead
of using an anycast address, a multicast address can also be of using an anycast address, a multicast address can also be
preconfigured. The RD servers then need to configure one of preconfigured. The RD servers then need to configure one of
their interfaces with this multicast address.) their interfaces with this multicast address.)
2. It may be configured with a DNS name for the RD and use DNS to 2. It may be configured with a DNS name for the RD and use DNS to
return the IP address of the RD; it can find a DNS server to return the IP address of the RD; it can find a DNS server to
perform the lookup using the usual mechanisms for finding DNS perform the lookup using the usual mechanisms for finding DNS
servers. servers.
3. It may be configured to use a service discovery mechanism such as
DNS-SD, as outlined in Section 4.1.2.
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.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).
skipping to change at page 17, line 10 skipping to change at page 17, line 10
error messages to very strictly rate-limit requests to candidate IP error messages to very strictly rate-limit requests to candidate IP
addresses that don't work out. For example, an ICMP Destination addresses that don't work out. For example, an ICMP Destination
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.
The following RD discovery mechanisms are recommended: The following RD discovery mechanisms are recommended:
o In managed networks with border routers that need stand-alone * In managed networks with border routers that need stand-alone
operation, the RDAO option is recommended (e.g. operational phase operation, the RDAO option is recommended (e.g. operational phase
described in Section 3.6). described in Section 3.6).
o In managed networks without border router (no Internet services * In managed networks without border router (no Internet services
available), the use of a preconfigured anycast address is available), the use of a preconfigured anycast address is
recommended (e.g. installation phase described in Section 3.6). recommended (e.g. installation phase described in Section 3.6).
o The use of DNS facilities is described in * In networks managed using DNS-SD, the use of DNS-SD for discovery
[I-D.ietf-core-rd-dns-sd]. as described in Section 4.1.2 is recommended.
The use of multicast discovery in mesh networks is NOT recommended. The use of multicast discovery in mesh networks is NOT recommended.
4.1.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
skipping to change at page 18, line 23 skipping to change at page 18, line 23
+ + + +
| | | |
+ RD Address + + RD Address +
| | | |
+ + + +
| | | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Fields: Fields:
Type: 38 Type: TBD38
Length: 8-bit unsigned integer. The length of Length: 8-bit unsigned integer. The length of
the option in units of 8 bytes. the option in units of 8 bytes.
Always 3. Always 3.
Valid Lifetime: 16-bit unsigned integer. The length of Valid Lifetime: 16-bit unsigned integer. The length of
time in units of 60 seconds (relative to time in units of 60 seconds (relative to
the time the packet is received) that the time the packet is received) that
this Resource Directory address is valid. this Resource Directory address is valid.
A value of all zero bits (0x0) indicates A value of all zero bits (0x0) indicates
skipping to change at page 18, line 45 skipping to change at page 19, line 5
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
4.1.2. Using DNS-SD to discover a resource directory
A resource directory can advertise its presence in DNS-SD [RFC6763]
using the service name "_core-rd._udp" (for CoAP), "_core-rd-
dtls._udp" (for CoAP over DTLS), "_core-rd._tcp" (for CoAP over TCP)
or "_core-rd-tls._tcp" (for CoAP over TLS) defined in this document.
(For the WebSocket transports of CoAP, no service is defined as DNS-
SD is typically unavailable in environments where CoAP over
WebSockets is used).
The selection of the service indicates the protocol used, and the SRV
record points the client to a host name and port to use as a starting
point for the URI discovery steps of Section 4.3.
This section is a simplified concrete application of the more generic
mechanism specified in [I-D.ietf-core-rd-dns-sd].
4.2. Payload Content Formats 4.2. 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.
4.3. 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] after having
RD discovery methods is described in Section 4.1. discovered a host as 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 28 skipping to change at page 20, line 4
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.
When performing multicast discovery, the multicast IP address used When performing multicast discovery, the multicast IP address used
will depend on the scope required and the multicast capabilities of will depend on the scope required and the multicast capabilities of
the network (see Section 9.5). the network (see Section 9.5).
A Resource Directory MAY provide hints about the content-formats it A Resource Directory MAY provide hints about the content-formats it
supports in the links it exposes or registers, using the "ct" target supports in the links it exposes or registers, using the "ct" target
attribute, as shown in the example below. Clients MAY use these attribute, as shown in the example below. Clients MAY use these
hints to select alternate content-formats for interaction with the hints to select alternate content-formats for interaction with the
Resource Directory. Resource Directory.
HTTP does not support multicast and consequently only unicast HTTP does not support multicast and consequently only unicast
discovery can be supported using HTTP. The well-known entry points discovery can be supported at the using the HTTP "/.well-known/core"
SHOULD be provided to enable unicast discovery. resource.
An implementation of this resource directory specification MUST An implementation of this resource directory specification MUST
support query filtering for the rt parameter as defined in [RFC6690]. support query filtering for the rt parameter as defined in [RFC6690].
While the link targets in this discovery step are often expressed in While the link targets in this discovery step are often expressed in
path-absolute form, this is not a requirement. Clients of the RD path-absolute form, this is not a requirement. Clients of the RD
SHOULD therefore accept URIs of all schemes they support, both as SHOULD therefore accept URIs of all schemes they support, both as
URIs and relative references, and not limit the set of discovered URIs and relative references, and not limit the set of discovered
URIs to those hosted at the address used for URI discovery. URIs to those hosted at the address used for URI discovery.
skipping to change at page 20, line 19 skipping to change at page 20, line 42
The discovery request interface is specified as follows (this is The discovery request interface is specified as follows (this is
exactly the Well-Known Interface of [RFC6690] Section 4, with the exactly the Well-Known Interface of [RFC6690] Section 4, with the
additional requirement that the server MUST support query filtering): additional requirement that the server MUST support query filtering):
Interaction: EP and Client -> RD Interaction: EP and Client -> RD
Method: GET Method: GET
URI Template: /.well-known/core{?rt} URI Template: /.well-known/core{?rt}
URI Template Variables: URI Template Variables: rt := Resource Type. SHOULD contain one of
the values "core.rd", "core.rd-lookup*", "core.rd-lookup-res",
rt := Resource Type. SHOULD contain one of the values "core.rd", "core.rd-lookup-ep", or "core.rd*"
"core.rd-lookup*", "core.rd-lookup-res", "core.rd-lookup-ep",
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 is expected on 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.
skipping to change at page 20, line 47 skipping to change at page 21, line 20
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,
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct=40, </rd-lookup/ep>;rt="core.rd-lookup-ep";ct=40,
</rd-lookup/res>;rt="core.rd-lookup-res";ct=40, </rd-lookup/res>;rt="core.rd-lookup-res";ct=40,
Figure 5: Example discovery exchange Figure 5: Example discovery exchange
The following example shows the way of indicating that a client may The following example shows the way of indicating that a client may
request alternate content-formats. The Content-Format code attribute request alternate content-formats. The Content-Format code attribute
"ct" MAY include a space-separated sequence of Content-Format codes "ct" MAY include a space-separated sequence of Content-Format codes
as specified in Section 7.2.1 of [RFC7252], indicating that multiple as specified in Section 7.2.1 of [RFC7252], indicating that multiple
content-formats are available. The example below shows the required content-formats are available. The example below shows the required
Content-Format 40 (application/link-format) indicated as well as a Content-Format 40 (application/link-format) indicated as well as a
CBOR and JSON representation from [I-D.ietf-core-links-json] (which CBOR and JSON representation from [I-D.ietf-core-links-json] (which
have no numeric values assigned yet, so they are shown as TBD64 and have no numeric values assigned yet, so they are shown as TBD64 and
TBD504 as in that draft). The RD resource locations /rd, and /rd- TBD504 as in that draft). The RD resource locations /rd, and /rd-
lookup are example values. The server in this example also indicates lookup are example values. The server in this example also indicates
that it is capable of providing observation on resource lookups. that it is capable of providing observation on resource lookups.
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 65225", </rd>;rt="core.rd";ct="40 65225",
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs, </rd-lookup/res>;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs,
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504", </rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504",
Figure 6: Example discovery exchange indicating additional content- Figure 6: Example discovery exchange indicating additional
formats content-formats
From a management and maintenance perspective, it is necessary to From a management and maintenance perspective, it is necessary to
identify the components that constitute the RD server. The identify the components that constitute the RD server. The
identification refers to information about for example client-server identification refers to information about for example client-server
incompatibilities, supported features, required updates and other incompatibilities, supported features, required updates and other
aspects. The URI discovery address, a described in section 4 of aspects. The URI discovery address, a described in section 4 of
[RFC6690] can be used to find the identification. [RFC6690] can be used to find the identification.
It would typically be stored in an implementation information link It would typically be stored in an implementation information link
(as described in [I-D.bormann-t2trg-rel-impl]): (as described in [I-D.bormann-t2trg-rel-impl]):
Req: GET /.well-known/core?rel=impl-info Req: GET /.well-known/core?rel=impl-info
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"
Figure 7: Example exchange of obtaining implementation information Figure 7: Example exchange of obtaining implementation information
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. 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
skipping to change at page 22, line 23 skipping to change at page 22, line 47
The creating endpoint is responsible for refreshing the registration The creating endpoint is responsible for refreshing the registration
resource within this period using either the registration or update resource within this period using either the registration or update
interface. The registration interface MUST be implemented to be interface. The registration interface MUST be implemented to be
idempotent, so that registering twice with the same endpoint idempotent, so that registering twice with the same endpoint
parameters ep and d (sector) does not create multiple registration parameters ep and d (sector) does not create multiple registration
resources. resources.
The following rules apply for a registration request targeting a The following rules apply for a registration request targeting a
given (ep, d) value pair: given (ep, d) value pair:
o When the (ep, d) value pair of the registration-request is * When the (ep, d) value pair of the registration-request is
different from any existing registration, a new registration is different from any existing registration, a new registration is
generated. generated.
o When the (ep, d) value pair of the registration-request is equal * When the (ep, d) value pair of the registration-request is equal
to an existing registration, the content and parameters of the to an existing registration, the content and parameters of the
existing registration are replaced with the content of the existing registration are replaced with the content of the
registration request. registration request.
The posted link-format document can (and typically does) contain The posted link-format document can (and typically does) contain
relative references both in its link targets and in its anchors, or relative references both in its link targets and in its anchors, or
contain empty anchors. The RD server needs to resolve these contain empty anchors. The RD server needs to resolve these
references in order to faithfully represent them in lookups. They references in order to faithfully represent them in lookups. They
are resolved against the base URI of the registration, which is are resolved against the base URI of the registration, which is
provided either explicitly in the "base" parameter or constructed provided either explicitly in the "base" parameter or constructed
skipping to change at page 23, line 4 skipping to change at page 23, line 26
For media types to which Appendix C applies (i.e. documents in For media types to which Appendix C applies (i.e. documents in
application/link-format), the RD only needs to accept representations application/link-format), the RD only needs to accept representations
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 Variables: URI Template: {+rd}{?ep,d,lt,base,extra-attrs*}
rd := RD registration URI (mandatory). This is the location of URI Template Variables: rd := RD registration URI (mandatory).
the RD, as obtained from discovery. This is the location of the RD, as obtained from discovery.
ep := Endpoint name (mostly mandatory). The endpoint name is an ep := Endpoint name (mostly mandatory).
identifier that MUST be unique within a sector. As the The endpoint name is an identifier that MUST be unique within a
endpoint name is a Unicode string, it is encoded in UTF-8 (and sector. As the endpoint name is a Unicode string, it is
possibly pct-encoding) during variable expansion (see [RFC6570] encoded in UTF-8 (and possibly pct-encoded) during variable
Section 3.2.1). The endpoint name MUST NOT contain any expansion (see [RFC6570] Section 3.2.1). The endpoint name
character in the inclusive ranges 0-31 or 127-159. The maximum MUST NOT contain any character in the inclusive ranges 0-31 or
length of this parameter is 63 UTF-8 encoded bytes. If the RD 127-159. The maximum length of this parameter is 63 UTF-8
is configured to recognize the endpoint (e.g. based on its encoded bytes. If the RD is configured to recognize the
security context), the RD assigns an endpoint name based on a endpoint (e.g. based on its security context), the RD assigns
set of configuration parameter values. 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
belongs. When this parameter is not present, the RD MAY which this endpoint belongs. When this parameter is not
associate the endpoint with a configured default sector or present, the RD MAY associate the endpoint with a configured
leave it empty. The sector is encoded like the ep parameter, default sector or leave it empty. The sector is encoded like
and is limited to 63 UTF-8 encoded bytes as well. The endpoint the ep parameter, and is limited to 63 UTF-8 encoded bytes as
name and sector name are not set when one or both are set in an well. The endpoint name and sector name are not set when one
accompanying authorization token. or both are set in an accompanying authorization token.
lt := Lifetime (optional). Lifetime of the registration in lt := Lifetime (optional). Lifetime of the
seconds. Range of 60-4294967295. If no lifetime is included registration in seconds. Range of 1-4294967295. If no
in the initial registration, a default value of 90000 (25 lifetime is included in the initial registration, a default
hours) SHOULD be assumed. value of 90000 (25 hours) SHOULD be assumed.
base := Base URI (optional). This parameter sets the base URI of base := Base URI (optional). This
the registration, under which the relative links in the payload parameter sets the base URI of the registration, under which
are to be interpreted. The specified URI typically does not the relative links in the payload are to be interpreted. The
have a path component of its own, and MUST be suitable as a specified URI typically does not have a path component of its
base URI to resolve any relative references given in the own, and MUST be suitable as a base URI to resolve any relative
registration. The parameter is therefore usually of the shape references given in the registration. The parameter is
"scheme://authority" for HTTP and CoAP URIs. The URI SHOULD therefore usually of the shape "scheme://authority" for HTTP
NOT have a query or fragment component as any non-empty and CoAP URIs. The URI SHOULD NOT have a query or fragment
relative part in a reference would remove those parts from the component as any non-empty relative part in a reference would
resulting URI. remove those parts from the resulting URI.
In the absence of this parameter the scheme of the protocol, In the absence of this parameter the scheme of the protocol,
source address and source port of the registration request are source address and source port of the registration request are
assumed. The Base URI is consecutively constructed by assumed. The Base URI is consecutively constructed by
concatenating the used protocol's scheme with the characters concatenating the used protocol's scheme with the characters
"://", the requester's source address as an address literal and "://", the requester's source address as an address literal and
":" 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
skipping to change at page 24, line 30 skipping to change at page 24, line 52
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
(e.g. [I-D.hartke-t2trg-coral]). (e.g. [I-D.hartke-t2trg-coral]).
extra-attrs := Additional registration attributes (optional). extra-attrs := Additional registration
The endpoint can pass any parameter registered at Section 9.3
to the directory. If the RD is aware of the parameter's attributes (optional). The endpoint can pass any parameter
specified semantics, it processes it accordingly. Otherwise, registered at Section 9.3 to the directory. If the RD is aware
it MUST store the unknown key and its value(s) as an endpoint of the parameter's specified semantics, it processes it
attribute for further lookup. accordingly. Otherwise, it MUST store the unknown key and its
value(s) as an endpoint 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 is expected on 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 field 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
skipping to change at page 25, line 42 skipping to change at page 26, line 15
Req: POST coap://rd.example.com/rd?ep=node1 Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
<http://www.example.com/sensors/temp>; <http://www.example.com/sensors/temp>;
anchor="/sensors/temp";rel="describedby" anchor="/sensors/temp";rel="describedby"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/4521 Location-Path: /rd/4521
Figure 8: Example registration payload Figure 8: Example registration payload
A Resource Directory may optionally support HTTP. Here is an example A Resource Directory may optionally support HTTP. Here is an example
of almost the same registration operation above, when done using of almost the same registration operation above, when done using
HTTP. HTTP.
Req: POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1 Req:
POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/link-format Content-Type: application/link-format
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
<http://www.example.com/sensors/temp>; <http://www.example.com/sensors/temp>;
anchor="/sensors/temp";rel="describedby" anchor="/sensors/temp";rel="describedby"
Res: 201 Created Res:
HTTP/1.1 201 Created
Location: /rd/4521 Location: /rd/4521
Figure 9: Example registration payload as expressed using HTTP Figure 9: Example registration payload as expressed using HTTP
5.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. 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).
o The registrant-ep finds one or more addresses of the directory * The registrant-ep finds one or more addresses of the directory
server as described in Section 4.1. server as described in Section 4.1.
o The registrant-ep sends (and regularly refreshes with) a POST * The registrant-ep sends (and regularly refreshes with) a POST
request to the "/.well-known/core" URI of the directory server of request to the "/.well-known/core" URI of the directory server of
choice. The body of the POST request is empty, and triggers the choice. The body of the POST request is empty, and triggers the
resource directory server to perform GET requests at the resource directory server to perform GET requests at the
requesting registrant-ep's /.well-known/core to obtain the link- requesting registrant-ep's /.well-known/core to obtain the link-
format payload to register. format payload to register.
The registrant-ep includes the same registration parameters in the The registrant-ep includes the same registration parameters in the
POST request as it would per Section 5. The registration base URI POST request as it would per Section 5. The registration base URI
of the registration is taken from the registrant-ep's network of the registration is taken from the registrant-ep's network
address (as is default with regular registrations). address (as is default with regular registrations).
Example request from registrant-EP to RD (unanswered until the Example request from registrant-EP to RD (unanswered until the
next step): next step):
Req: POST /.well-known/core?lt=6000&ep=node1 Req: POST /.well-known/core?lt=6000&ep=node1
(No payload) (No payload)
Figure 10: First half example exchange of a simple registration Figure 10: First half example exchange of a simple registration
o The Resource Directory queries the registrant-ep's discovery * The Resource Directory queries the registrant-ep's discovery
resource to determine the success of the operation. It SHOULD resource to determine the success of the operation. It SHOULD
keep a cache of the discovery resource and not query it again as keep a cache of the discovery resource and not query it again as
long as it is fresh. long as it is fresh.
Example request from the RD to the registrant-EP: Example request from the RD to the registrant-EP:
Req: GET /.well-known/core Req: GET /.well-known/core
Accept: 40 Accept: 40
Res: 2.05 Content Res: 2.05 Content
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sen/temp> </sen/temp>
Figure 11: Example exchange of the RD querying the simple endpoint Figure 11: Example exchange of the RD querying the simple endpoint
With this response, the RD would answer the previous step's request: With this response, the RD would answer the previous step's request:
Res: 2.04 Changed Res: 2.04 Changed
Figure 12: Second half example exchange of a simple registration Figure 12: Second half example exchange of a simple registration
The sequence of fetching the registration content before sending a The sequence of fetching the registration content before sending a
successful response was chosen to make responses reliable, and the successful response was chosen to make responses reliable, and the
caching item was chosen to still allow very constrained registrants. 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
skipping to change at page 30, line 18 skipping to change at page 30, line 33
links of a registration (see Section 5.3.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 of a successful earlier registration.
location := This is the Location returned by the RD as a result
of a successful earlier registration.
lt := Lifetime (optional). Lifetime of the registration in lt := Lifetime (optional). Lifetime of the
seconds. Range of 60-4294967295. If no lifetime is included, registration in seconds. Range of 1-4294967295. If no
the previous last lifetime set on a previous update or the lifetime is included, the previous last lifetime set on a
original registration (falling back to 90000) SHOULD be used. previous update or the original registration (falling back to
90000) SHOULD be used.
base := Base URI (optional). This parameter updates the Base URI base := Base URI (optional). This
established in the original registration to a new value. If parameter updates the Base URI established in the original
the parameter is set in an update, it is stored by the RD as registration to a new value. If the parameter is set in an
the new Base URI under which to interpret the relative links update, it is stored by the RD as the new Base URI under which
present in the payload of the original registration, following to interpret the relative links present in the payload of the
the same restrictions as in the registration. If the parameter original registration, following the same restrictions as in
is not set in the request but was set before, the previous Base the registration. If the parameter is not set in the request
URI value is kept unmodified. If the parameter is not set in but was set before, the previous Base URI value is kept
the request and was not set before either, the source address unmodified. If the parameter is not set in the request and was
and source port of the update request are stored as the Base not set before either, the source address and source port of
URI. the update request are stored as the Base URI.
extra-attrs := Additional registration attributes (optional). As extra-attrs := Additional registration
with the registration, the RD processes them if it knows their attributes (optional). As with the registration, the RD
semantics. Otherwise, unknown attributes are stored as processes them if it knows their semantics. Otherwise, unknown
endpoint attributes, overriding any previously stored endpoint attributes are stored as endpoint attributes, overriding any
attributes of the same key. previously stored endpoint attributes of the same key.
Note that this default behavior does not allow removing an Note that this default behavior does not allow removing an
endpoint attribute in an update. For attributes whose endpoint attribute in an update. For attributes whose
functionality depends on the endpoints' ability to remove them functionality depends on the endpoints' ability to remove them
in an update, it can make sense to define a value whose in an update, it can make sense to define a value whose
presence is equivalent to the absence of a value. As an presence is equivalent to the absence of a value. As an
alternative, an extension can define different updating rules alternative, an extension can define different updating rules
for their attributes. That necessitates either discovery of for their attributes. That necessitates either discovery of
whether the RD is aware of that extension, or tolerating the whether the RD is aware of that extension, or tolerating the
default behavior. default behavior.
skipping to change at page 31, line 18 skipping to change at page 31, line 32
The following responses are expected on 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.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).
If the registration fails in any way, including "Not Found" and If the registration fails in any way, including "Not Found" and
request timeouts, or if the time indicated in a Service Unabailable request timeouts, or if the time indicated in a Service Unavailable
Max-Age/Retry-After exceeds the remaining lifetime, the registering Max-Age/Retry-After 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
Figure 13: Example update of a registration Figure 13: Example update of a registration
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 * endpoint name (ep)=endpoint1
* lifetime (lt)=500
o lifetime (lt)=500
o Base URI (base)=coap://local-proxy-old.example.com:5683 * Base URI (base)=coap://local-proxy-old.example.com:5683
o payload of Figure 8 * payload of Figure 8
The initial state of the Resource Directory is reflected in the The initial state of the Resource Directory is reflected in the
following request: following request:
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content Res: 2.05 Content
Payload: Payload:
<coap://local-proxy-old.example.com:5683/sensors/temp>;ct=41; <coap://local-proxy-old.example.com:5683/sensors/temp>;ct=41;
rt="temperature-c";if="sensor"; rt="temperature-c";if="sensor";
anchor="coap://local-proxy-old.example.com:5683/", anchor="coap://local-proxy-old.example.com:5683/",
<http://www.example.com/sensors/temp>; <http://www.example.com/sensors/temp>;
anchor="coap://local-proxy-old.example.com:5683/sensors/temp";rel="describedby" anchor="coap://local-proxy-old.example.com:5683/sensors/temp";rel="describedby"
Figure 14: Example lookup before a change to the base address Figure 14: Example lookup before a change to the base address
The following example shows the registering endpoint changing the The following example shows the registering endpoint changing the
Base URI to "coaps://new.example.com:5684": Base URI to "coaps://new.example.com:5684":
Req: POST /rd/4521?base=coaps://new.example.com:5684 Req: POST /rd/4521?base=coaps://new.example.com:5684
Res: 2.04 Changed Res: 2.04 Changed
Figure 15: Example registration update that changes the base address Figure 15: Example registration update that changes the base address
The consecutive query returns: The consecutive query returns:
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content Res: 2.05 Content
Payload: Payload:
<coap://new.example.com:5684/sensors/temp>;ct=41; <coap://new.example.com:5684/sensors/temp>;ct=41;
rt="temperature-c";if="sensor"; rt="temperature-c";if="sensor";
anchor="coap://new.example.com:5684/", anchor="coap://new.example.com:5684/",
<http://www.example.com/sensors/temp>; <http://www.example.com/sensors/temp>;
anchor="coap://new.example.com:5684/sensors/temp";rel="describedby" anchor="coap://new.example.com:5684/sensors/temp";rel="describedby"
Figure 16: Example lookup after a change to the base address Figure 16: Example lookup after a change to the base address
5.3.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.
skipping to change at page 33, line 4 skipping to change at page 33, line 17
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:
Interaction: EP -> RD Interaction: EP -> RD
Method: DELETE Method: DELETE
URI Template: {+location} URI Template: {+location}
URI Template Variables: URI Template Variables: location := This is the Location returned
by the RD as a result of a successful earlier registration.
location := This is the Location returned by the RD as a result
of a successful earlier registration.
The following responses are expected on 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.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).
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
Figure 17: Example of a registration removal Figure 17: Example of a registration removal
5.3.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 * 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 * Use GET to read the currently stored set of links in a
registration resource. registration resource.
Those operations are out of scope of this document, and will require Those operations are out of scope of this document, and will require
media types suitable for modifying sets of links. media types suitable for modifying sets of links.
6. RD Lookup 6. RD Lookup
To discover the resources registered with the RD, a lookup interface To discover the resources registered with the RD, a lookup interface
must be provided. This lookup interface is defined as a default, and must be provided. This lookup interface is defined as a default, and
it is assumed that RDs may also support lookups to return resource it is assumed that RDs may also support lookups to return resource
skipping to change at page 34, line 17 skipping to change at page 34, line 30
result of a lookup request is the list of links (if any) result of a lookup request is the list of links (if any)
corresponding to the type of lookup. Thus, an endpoint lookup MUST corresponding to the type of lookup. Thus, an endpoint lookup MUST
return a list of endpoints and a resource lookup MUST return a list return a list of endpoints and a resource lookup MUST return a list
of links to resources. of links to resources.
The lookup type is selected by a URI endpoint, which is indicated by The lookup type is selected by a URI endpoint, which is indicated by
a Resource Type as per Table 1 below: a Resource Type as per Table 1 below:
+-------------+--------------------+-----------+ +-------------+--------------------+-----------+
| Lookup Type | Resource Type | Mandatory | | Lookup Type | Resource Type | Mandatory |
+-------------+--------------------+-----------+ +=============+====================+===========+
| Resource | core.rd-lookup-res | Mandatory | | Resource | core.rd-lookup-res | Mandatory |
+-------------+--------------------+-----------+
| Endpoint | core.rd-lookup-ep | Mandatory | | Endpoint | core.rd-lookup-ep | Mandatory |
+-------------+--------------------+-----------+ +-------------+--------------------+-----------+
Table 1: Lookup Types Table 1: Lookup Types
6.1. Resource lookup 6.1. Resource lookup
Resource lookup results in links that are semantically equivalent to Resource lookup results in links that are semantically equivalent to
the links submitted to the RD. The links and link parameters the links submitted to the RD. The links and link parameters
returned by the lookup are equal to the submitted ones, except that returned by the lookup are equal to the submitted ones, except that
the target and anchor references are fully resolved. the target and anchor references are fully resolved.
Links that did not have an anchor attribute are therefore returned Links that did not have an anchor attribute are therefore returned
with the base URI of the registration as the anchor. Links of which with the base URI of the registration as the anchor. Links of which
skipping to change at page 35, line 35 skipping to change at page 35, line 48
matches a search criterion if any of its resource links matches it. matches a search criterion if any of its resource links matches it.
Note that "href" is a valid search criterion and matches target Note that "href" is a valid search criterion and matches target
references. Like all search criteria, on a resource lookup it can references. Like all search criteria, on a resource lookup it can
match the target reference of the resource link itself, but also the match the target reference of the resource link itself, but also the
registration resource of the endpoint that registered it. Queries registration resource of the endpoint that registered it. Queries
for resource link targets MUST be in URI form (i.e. not relative for resource link targets MUST be in URI form (i.e. not relative
references) and are matched against a resolved link target. Queries references) and are matched against a resolved link target. Queries
for endpoints SHOULD be expressed in path-absolute form if possible for endpoints SHOULD be expressed in path-absolute form if possible
and MUST be expressed in URI form otherwise; the RD SHOULD recognize and MUST be expressed in URI form otherwise; the RD SHOULD recognize
either. either. The "anchor" attribute is usable for resource lookups, and,
if queried, MUST be for in URI form as well.
Endpoints that are interested in a lookup result repeatedly or Endpoints that are interested in a lookup result repeatedly or
continuously can use mechanisms like ETag caching, resource continuously can use mechanisms like ETag caching, resource
observation ([RFC7641]), or any future mechanism that might allow observation ([RFC7641]), or any future mechanism that might allow
more efficient observations of collections. These are advertised, more efficient observations of collections. These are advertised,
detected and used according to their own specifications and can be detected and used according to their own specifications and can be
used with the lookup interface as with any other resource. used with the lookup interface as with any other resource.
When resource observation is used, every time the set of matching When resource observation is used, every time the set of matching
links changes, or the content of a matching link changes, the RD links changes, or the content of a matching link changes, the RD
skipping to change at page 36, line 11 skipping to change at page 36, line 27
"Success" item below). "Success" item below).
The lookup interface is specified as follows: The lookup interface is specified as follows:
Interaction: Client -> RD Interaction: Client -> RD
Method: GET Method: GET
URI Template: {+type-lookup-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 (mandatory). The address is discovered as
type-lookup-location := RD Lookup URI for a given lookup type described in Section 4.3.
(mandatory). The address is discovered as described in
Section 4.3.
search := Search criteria for limiting the number of results search := Search criteria for limiting the
(optional). number of results (optional).
page := Page (optional). Parameter cannot be used without the page := Page (optional). Parameter cannot
count parameter. Results are returned from result set in pages be used without the count parameter. Results are returned from
that contain 'count' links starting from index (page * count). result set in pages that contain 'count' links starting from
Page numbering starts with zero. index (page * count). Page numbering starts with zero.
count := Count (optional). Number of results is limited to this count := Count (optional). Number of
parameter value. If the page parameter is also present, the results is limited to this parameter value. If the page
response MUST only include 'count' links starting with the parameter is also present, the response MUST only include
(page * count) link in the result set from the query. If the 'count' links starting with the (page * count) link in the
count parameter is not present, then the response MUST return result set from the query. If the count parameter is not
all matching links in the result set. Link numbering starts present, then the response MUST return all matching links in
with zero. the result set. Link numbering starts with zero.
Accept: absent, application/link-format or any other indicated Accept: absent, application/link-format or any other indicated media
media type representing web links 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.
6.3. Resource lookup examples 6.3. Resource lookup examples
skipping to change at page 37, line 11 skipping to change at page 37, line 26
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
Res: 2.05 Content Res: 2.05 Content
<coap://[2001:db8:3::123]:61616/temp>;rt="temperature"; <coap://[2001:db8:3::123]:61616/temp>;rt="temperature";
anchor="coap://[2001:db8:3::123]:61616" anchor="coap://[2001:db8:3::123]:61616"
Figure 18: Example a resource lookup Figure 18: Example a resource lookup
A client that wants to be notified of new resources as they show up A client that wants to be notified of new resources as they show up
can use observation: can use observation:
Req: GET /rd-lookup/res?rt=light Req: GET /rd-lookup/res?rt=light
Observe: 0 Observe: 0
Res: 2.05 Content Res: 2.05 Content
Observe: 23 Observe: 23
Payload: empty Payload: empty
skipping to change at page 38, line 32 skipping to change at page 38, line 36
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/6>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/6>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/7>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/7>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/8>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/8>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/9>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/9>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616" anchor="coap://[2001:db8:3::123]:61616"
Figure 20: Examples of paginated resource lookup Figure 20: Examples of paginated resource lookup
The following example shows a client performing a lookup of all The following example shows a client performing a lookup of all
resources of all endpoints of a given endpoint type. It assumes that resources of all endpoints of a given endpoint type. It assumes that
two endpoints (with endpoint names "sensor1" and "sensor2") have two endpoints (with endpoint names "sensor1" and "sensor2") have
previously registered with their respective addresses previously registered with their respective addresses
"coap://sensor1.example.com" and "coap://sensor2.example.com", and "coap://sensor1.example.com" and "coap://sensor2.example.com", and
posted the very payload of the 6th request of section 5 of [RFC6690]. posted the very payload of the 6th request of section 5 of [RFC6690].
It demonstrates how absolute link targets stay unmodified, while It demonstrates how absolute link targets stay unmodified, while
relative ones are resolved: relative ones are resolved:
skipping to change at page 39, line 44 skipping to change at page 39, line 44
Endpoint registration resources are annotated with their endpoint Endpoint registration resources are annotated with their endpoint
names (ep), sectors (d, if present) and registration base URI (base; names (ep), sectors (d, if present) and registration base URI (base;
reports the registrant-ep's address if no explicit base was given) as reports the registrant-ep's address if no explicit base was given) as
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 (full) URIs. (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 shown 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.
skipping to change at page 40, line 27 skipping to change at page 40, line 25
rt value): rt value):
Req: GET /rd-lookup/ep?et=oic.d.sensor Req: GET /rd-lookup/ep?et=oic.d.sensor
Res: 2.05 Content Res: 2.05 Content
</rd/1234>;base="coap://[2001:db8:3::127]:61616";ep="node5"; </rd/1234>;base="coap://[2001:db8:3::127]:61616";ep="node5";
et="oic.d.sensor";ct="40";rt="core.rd-ep", et="oic.d.sensor";ct="40";rt="core.rd-ep",
</rd/4521>;base="coap://[2001:db8:3::129]:61616";ep="node7"; </rd/4521>;base="coap://[2001:db8:3::129]:61616";ep="node7";
et="oic.d.sensor";ct="40";d="floor-3";rt="core.rd-ep" et="oic.d.sensor";ct="40";d="floor-3";rt="core.rd-ep"
Figure 22: Examples of endpoint lookup Figure 22: Examples of endpoint lookup
7. Security policies 7. Security policies
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:
skipping to change at page 41, line 23 skipping to change at page 41, line 23
on the values of the endpoint registration parameters. Authorization on the values of the endpoint registration parameters. Authorization
to discover endpoints with a given set of filter values is to discover endpoints with a given set of filter values is
recommended for those cases. recommended for those cases.
When a node registers its endpoints, criteria are needed to authorize When a node registers its endpoints, criteria are needed to authorize
the node to enter them. An important aspect is the uniqueness of the the node to enter them. An important aspect is the uniqueness of the
(endpoint name, and optional sector) pair within the RD. Consider (endpoint name, and optional sector) pair within the RD. Consider
the two cases separately: (1) CT registers endpoints, and (2) the the two cases separately: (1) CT registers endpoints, and (2) the
registering node registers its own endpoint(s). registering node registers its own endpoint(s).
o A CT needs authorization to register a set of endpoints. This * A CT needs authorization to register a set of endpoints. This
authorization can be based on the region, i.e. a given CT is authorization can be based on the region, i.e. a given CT is
authorized to register any endpoint (endpoint name, sector) into a authorized to register any endpoint (endpoint name, sector) into a
given RD, or to register an endpoint with (endpoint name, sector) given RD, or to register an endpoint with (endpoint name, sector)
value pairs assigned by the AS, or can be more fine-grained, value pairs assigned by the AS, or can be more fine-grained,
including a subset of registration parameter values. including a subset of registration parameter values.
o A given endpoint that registers itself, needs to proof its * A given endpoint that registers itself, needs to proof its
possession of its unique (endpoint name, sector) value pair. possession of its unique (endpoint name, sector) value pair.
Alternatively, the AS can authorize the endpoint to register with Alternatively, the AS can authorize the endpoint to register with
an (endpoint name, sector) value pair assigned by the AS. an (endpoint name, sector) value pair assigned by the AS.
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
skipping to change at page 42, line 25 skipping to change at page 42, line 25
This section only considers the assignment of a name to the endpoint This section only considers the assignment of a name to the endpoint
based on an automatic mechanism without use of AS. More elaborate based on an automatic mechanism without use of AS. More elaborate
protocols are out of scope. The registering endpoint is authorized protocols are out of scope. The registering endpoint is authorized
by the AS to discover the RD and add registrations. A token is by the AS to discover the RD and add registrations. A token is
provided by the AS and communicated from registering endpoint to RD. provided by the AS and communicated from registering endpoint to RD.
It is assumed that DTLS is used to secure the channel between It is assumed that DTLS is used to secure the channel between
registering endpoint and RD, where the registering endpoint is the registering endpoint and RD, where the registering endpoint is the
DTLS client. Assuming that the client is provided by a certificate DTLS client. Assuming that the client is provided by a certificate
at manufacturing time, the certificate is uniquely identified by the at manufacturing time, the certificate is uniquely identified by the
CN field and the serial number. The RD can assign a unique endpoint CN field and the serial number (see [RFC5280] Section 4.1.2.2). The
name by using the certificate identifier as endpoint name. Proof of RD can assign a unique endpoint name by using the certificate
possession of the endpoint name by the registering endpoint is identifier as endpoint name. Proof of possession of the endpoint
checked by encrypting the certificate identifier with the private key name by the registering endpoint is checked by encrypting the
of the registering endpoint, which the RD can decrypt with the public certificate identifier with the private key of the registering
key stored in the certificate. Even simpler, the authorized endpoint, which the RD can decrypt with the public key stored in the
registering endpoint can generate a random number (or string) that certificate. Even simpler, the authorized registering endpoint can
identifies the endpoint. The RD can check for the improbable generate a random number (or string) that identifies the endpoint.
replication of the random value. The RD MUST check that registering The RD can check for the improbable replication of the random value.
endpoint uses only one random value for each authorized endpoint. The RD MUST check that registering endpoint uses only one random
value for each authorized endpoint.
8. Security Considerations 8. Security Considerations
The security considerations as described in Section 5 of [RFC8288] The security considerations as described in Section 5 of [RFC8288]
and Section 6 of [RFC6690] apply. The "/.well-known/core" resource and Section 6 of [RFC6690] apply. The "/.well-known/core" resource
may be protected e.g. using DTLS when hosted on a CoAP server as may be protected e.g. using DTLS when hosted on a CoAP server as
described in [RFC7252]. DTLS or TLS based security SHOULD be used on described in [RFC7252]. DTLS or TLS based security SHOULD be used on
all resource directory interfaces defined in this document. all resource directory interfaces defined in this document.
8.1. Endpoint Identification and Authentication 8.1. Endpoint Identification and Authentication
skipping to change at page 44, line 15 skipping to change at page 44, line 15
attack. attack.
9. IANA Considerations 9. IANA Considerations
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 RD | RFCTHIS |
| | RD | 4.3 | | | | Section 4.3 |
| core.rd-lookup-res | Resource lookup of an RD | RFCTHIS Section | +--------------------+-----------------------------+-------------+
| | | 4.3 | | core.rd-lookup-res | Resource lookup of an RD | RFCTHIS |
| core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS Section | | | | Section 4.3 |
| | | 4.3 | +--------------------+-----------------------------+-------------+
| core.rd-ep | Endpoint resource of an | RFCTHIS Section 6 | | core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS |
| | RD | | | | | Section 4.3 |
+--------------------+--------------------------+-------------------+ +--------------------+-----------------------------+-------------+
| core.rd-ep | Endpoint resource of an RD | RFCTHIS |
| | | Section 6 |
+--------------------+-----------------------------+-------------+
Table 2
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) * Resource Directory Address Option (TBD38)
[ The RFC editor is asked to replace TBD38 with the assigned number
in the document; the value 38 is suggested. ]
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
* the human readable name of the parameter,
o the human readable name of the parameter, * the short name as used in query parameters or target attributes,
o the short name as used in query parameters or target attributes,
o indication of whether it can be passed as a query parameter at * indication of whether it can be passed as a query parameter at
registration of endpoints, as a query parameter in lookups, or be registration of endpoints, as a query parameter in lookups, or be
expressed as a target attribute, expressed as a target attribute,
o validity requirements if any, and * validity requirements if any,
o a description. * a description,
* and a link to reference documentation.
The query parameter MUST be both a valid URI query key [RFC3986] and The query parameter MUST be both a valid URI query key [RFC3986] and
a token as used in [RFC8288]. a token as used in [RFC8288].
The description must give details on whether the parameter can be The description must give details on whether the parameter can be
updated, and how it is to be processed in lookups. updated, and how it is to be processed in lookups.
The mechanisms around new RD parameters should be designed in such a The mechanisms around new RD parameters should be designed in such a
way that they tolerate RD implementations that are unaware of the way that they tolerate RD implementations that are unaware of the
parameter and expose any parameter passed at registration or updates parameter and expose any parameter passed at registration or updates
on in endpoint lookups. (For example, if a parameter used at on in endpoint lookups. (For example, if a parameter used at
registration were to be confidential, the registering endpoint should registration were to be confidential, the registering endpoint should
be instructed to only set that parameter if the RD advertises support be instructed to only set that parameter if the RD advertises support
for keeping it confidential at the discovery step.) for keeping it confidential at the discovery step.)
Initial entries in this sub-registry are as follows: Initial entries in this sub-registry are as follows:
+--------------+-------+---------------+-----+----------------------+ +--------------+-------+--------------+-----+---------------------+
| Full name | Short | Validity | Use | Description | | Full name | Short | Validity | Use | Description |
+--------------+-------+---------------+-----+----------------------+ +==============+=======+==============+=====+=====================+
| Endpoint | ep | Unicode* | RLA | Name of the endpoint | | Endpoint | ep | Unicode* | RLA | Name of the |
| Name | | | | | | Name | | | | endpoint |
| Lifetime | lt | 60-4294967295 | R | Lifetime of the | +--------------+-------+--------------+-----+---------------------+
| | | | | registration in | | Lifetime | lt | 1-4294967295 | R | Lifetime of the |
| | | | | seconds | | | | | | registration in |
| Sector | d | Unicode* | RLA | Sector to which this | | | | | | seconds |
| | | | | endpoint belongs | +--------------+-------+--------------+-----+---------------------+
| Registration | base | URI | RLA | The scheme, address | | Sector | d | Unicode* | RLA | Sector to which |
| Base URI | | | | and port and path at | | | | | | this endpoint |
| | | | | which this server is | | | | | | belongs |
| | | | | available | +--------------+-------+--------------+-----+---------------------+
| Page | page | Integer | L | Used for pagination | | Registration | base | URI | RLA | The scheme, address |
| Count | count | Integer | L | Used for pagination | | Base URI | | | | and port and path |
| Endpoint | et | Section 9.3.1 | RLA | Semantic type of the | | | | | | at which this |
| Type | | | | endpoint (see | | | | | | server is available |
| | | | | Section 9.4) | +--------------+-------+--------------+-----+---------------------+
+--------------+-------+---------------+-----+----------------------+ | Page | page | Integer | L | Used for pagination |
+--------------+-------+--------------+-----+---------------------+
| Count | count | Integer | L | Used for pagination |
+--------------+-------+--------------+-----+---------------------+
| Endpoint | et | Section | RLA | Semantic type of |
| Type | | 9.3.1 | | the endpoint (see |
| | | | | Section 9.4) |
+--------------+-------+--------------+-----+---------------------+
Table 2: RD Parameters Table 3: RD Parameters
(Short: Short name used in query parameters or target attributes. (Short: Short name used in query parameters or target attributes.
Validity: Unicode* = 63 Bytes of UTF-8 encoded Unicode, with no Validity: Unicode* = 63 Bytes of UTF-8 encoded Unicode, with no
control characters as per Section 5. Use: R = used at registration, control characters as per Section 5. Use: R = used at registration,
L = used at lookup, A = expressed in target attribute L = used at lookup, A = expressed in target attribute
The descriptions for the options defined in this document are only The descriptions for the options defined in this document are only
summarized here. To which registrations they apply and when they are summarized here. To which registrations they apply and when they are
to be shown is described in the respective sections of this document. to be shown is described in the respective sections of this document.
All their reference documentation entries point to this document.
The IANA policy for future additions to the sub-registry is "Expert The IANA policy for future additions to the sub-registry is "Expert
Review" as described in [RFC8126]. The evaluation should consider Review" as described in [RFC8126]. The evaluation should consider
formal criteria, duplication of functionality (Is the new entry formal criteria, duplication of functionality (Is the new entry
redundant with an existing one?), topical suitability (E.g. is the redundant with an existing one?), topical suitability (E.g. is the
described property actually a property of the endpoint and not a described property actually a property of the endpoint and not a
property of a particular resource, in which case it should go into property of a particular resource, in which case it should go into
the payload of the registration and need not be registered?), and the the payload of the registration and need not be registered?), and the
potential for conflict with commonly used target attributes (For potential for conflict with commonly used target attributes (For
example, "if" could be used as a parameter for conditional example, "if" could be used as a parameter for conditional
skipping to change at page 47, line 10 skipping to change at page 47, line 44
Parameters" called '"Endpoint Type" (et=) RD Parameter values'. The Parameters" called '"Endpoint Type" (et=) RD Parameter values'. The
registry properties (required policy, requirements, template) are registry properties (required policy, requirements, template) are
identical to those of the Resource Type parameters in [RFC6690], in identical to those of the Resource Type parameters in [RFC6690], in
short: short:
The review policy is IETF Review for values starting with "core", and The review policy is IETF Review for values starting with "core", and
Specification Required for others. Specification Required for others.
The requirements to be enforced are: The requirements to be enforced are:
o The values MUST be related to the purpose described in * The values MUST be related to the purpose described in
Section 9.3.1. Section 9.3.1.
o The registered values MUST conform to the ABNF reg-rel-type * The registered values MUST conform to the ABNF reg-rel-type
definition of [RFC6690] and MUST NOT be a URI. definition of [RFC6690] and MUST NOT be a URI.
o It is recommended to use the period "." character for * It is recommended to use the period "." character for
segmentation. segmentation.
The registry initially contains one value: The registry initially contains one value:
o "core.rd-group": An application group as described in Appendix A. * "core.rd-group": An application group as described in Appendix A.
9.5. Multicast Address Registration 9.5. Multicast Address Registration
IANA is asked to assign the following multicast addresses for use by IANA is asked to assign the following multicast addresses for use by
CoAP nodes: CoAP nodes:
IPv4 - "all CoRE resource directories" address MCD2 (suggestion: IPv4 - "all CoRE resource directories" address MCD2 (suggestion:
224.0.1.189), from the "IPv4 Multicast Address Space Registry". As 224.0.1.189), from the "IPv4 Multicast Address Space Registry". As
the address is used for discovery that may span beyond a single the address is used for discovery that may span beyond a single
network, it has come from the Internetwork Control Block (224.0.1.x, network, it has come from the Internetwork Control Block (224.0.1.x,
skipping to change at page 47, line 44 skipping to change at page 48, line 30
IPv6 - "all CoRE resource directories" address MCD1 (suggestions IPv6 - "all CoRE resource directories" address MCD1 (suggestions
FF0X::FE), from the "IPv6 Multicast Address Space Registry", in the FF0X::FE), from the "IPv6 Multicast Address Space Registry", in the
"Variable Scope Multicast Addresses" space (RFC 3307). Note that "Variable Scope Multicast Addresses" space (RFC 3307). Note that
there is a distinct multicast address for each scope that interested there is a distinct multicast address for each scope that interested
CoAP nodes should listen to; CoAP needs the Link-Local and Site-Local CoAP nodes should listen to; CoAP needs the Link-Local and Site-Local
scopes only. scopes only.
[ The RFC editor is asked to replace MCD1 and MCD2 with the assigned [ The RFC editor is asked to replace MCD1 and MCD2 with the assigned
addresses throughout the document. ] addresses throughout the document. ]
9.6. Well-Kown URIs
IANA is asked to extend the reference for the "core" URI suffix in
the "Well-Known URIs" registry to reference this document next to
[RFC6690], as this defines the resource's behavior for POST requests.
9.7. Service Names and Transport Protocol Port Number Registry
IANA is asked to enter four new items into the Service Names and
Transport Protocol Port Number Registry:
* Service name: "core-rd", Protocol: "udp", Description: "Resource
Directory accessed using CoAP"
* Service name "core-rd-dtls", Protocol: "udp", Description:
"Resource Directory accedded using CoAP over DTLS"
* Service name: "core-rd", Protocol: "tcp", Description: "Resource
Directory accessed using CoAP over TCP"
* Service name "core-rd-tls", Protocol: "tcp", Description:
"Resource Directory accedded using CoAP over TLS"
All in common have this document as their reference.
10. Examples 10. Examples
Two examples are presented: a Lighting Installation example in Two examples are presented: a Lighting Installation example in
Section 10.1 and a LWM2M example in Section 10.2. Section 10.1 and a LWM2M example in Section 10.2.
10.1. Lighting Installation 10.1. Lighting Installation
This example shows a simplified lighting installation which makes use This example shows a simplified lighting installation which makes use
of the Resource Directory (RD) with a CoAP interface to facilitate of the Resource Directory (RD) with a CoAP interface to facilitate
the installation and start-up of the application code in the lights the installation and start-up of the application code in the lights
skipping to change at page 48, line 51 skipping to change at page 50, line 10
group of lamps consists of: middle and left lamps of luminary1 and group of lamps consists of: middle and left lamps of luminary1 and
right lamp of luminary2. right lamp of luminary2.
Before commissioning by the lighting manager, the network is Before commissioning by the lighting manager, the network is
installed and access to the interfaces is proven to work by the installed and access to the interfaces is proven to work by the
network manager. network manager.
At the moment of installation, the network under installation is not At the moment of installation, the network under installation is not
necessarily connected to the DNS infra structure. Therefore, SLAAC necessarily connected to the DNS infra structure. Therefore, SLAAC
IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in
Table 3 below: Table 4 below:
+--------------------+----------------+ +--------------------+----------------+
| Name | IPv6 address | | Name | IPv6 address |
+--------------------+----------------+ +====================+================+
| luminary1 | 2001:db8:4::1 | | luminary1 | 2001:db8:4::1 |
+--------------------+----------------+
| luminary2 | 2001:db8:4::2 | | luminary2 | 2001:db8:4::2 |
+--------------------+----------------+
| Presence sensor | 2001:db8:4::3 | | Presence sensor | 2001:db8:4::3 |
+--------------------+----------------+
| Resource directory | 2001:db8:4::ff | | Resource directory | 2001:db8:4::ff |
+--------------------+----------------+ +--------------------+----------------+
Table 3: interface SLAAC addresses Table 4: interface SLAAC addresses
In Section 10.1.2 the use of resource directory during installation In Section 10.1.2 the use of resource directory during installation
is presented. is presented.
10.1.2. RD entries 10.1.2. RD entries
It is assumed that access to the DNS infrastructure is not always It is assumed that access to the DNS infrastructure is not always
possible during installation. Therefore, the SLAAC addresses are possible during installation. Therefore, the SLAAC addresses are
used in this section. used in this section.
For discovery, the resource types (rt) of the devices are important. For discovery, the resource types (rt) of the devices are important.
The lamps in the luminaries have rt: light, and the presence sensor The lamps in the luminaries have rt: light, and the presence sensor
has rt: p-sensor. The endpoints have names which are relevant to the has rt: p-sensor. The endpoints have names which are relevant to the
light installation manager. In this case luminary1, luminary2, and light installation manager. In this case luminary1, luminary2, and
the presence sensor are located in room 2-4-015, where luminary1 is the presence sensor are located in room 2-4-015, where luminary1 is
located at the window and luminary2 and the presence sensor are located at the window and luminary2 and the presence sensor are
located at the door. The endpoint names reflect this physical located at the door. The endpoint names reflect this physical
location. The middle, left and right lamps are accessed via path location. The middle, left and right lamps are accessed via path
/light/middle, /light/left, and /light/right respectively. The /light/middle, /light/left, and /light/right respectively. The
identifiers relevant to the Resource Directory are shown in Table 4 identifiers relevant to the Resource Directory are shown in Table 5
below: below:
+----------------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
| Name | endpoint | resource path | resource type | | Name | endpoint | resource path | resource type |
+----------------+------------------+---------------+---------------+ +===========+==================+===============+===============+
| luminary1 | lm_R2-4-015_wndw | /light/left | light | | luminary1 | lm_R2-4-015_wndw | /light/left | light |
| luminary1 | lm_R2-4-015_wndw | /light/middle | light | +-----------+------------------+---------------+---------------+
| luminary1 | lm_R2-4-015_wndw | /light/right | light | | luminary1 | lm_R2-4-015_wndw | /light/middle | light |
| luminary2 | lm_R2-4-015_door | /light/left | light | +-----------+------------------+---------------+---------------+
| luminary2 | lm_R2-4-015_door | /light/middle | light | | luminary1 | lm_R2-4-015_wndw | /light/right | light |
| luminary2 | lm_R2-4-015_door | /light/right | light | +-----------+------------------+---------------+---------------+
| Presence | ps_R2-4-015_door | /ps | p-sensor | | luminary2 | lm_R2-4-015_door | /light/left | light |
| sensor | | | | +-----------+------------------+---------------+---------------+
+----------------+------------------+---------------+---------------+ | luminary2 | lm_R2-4-015_door | /light/middle | light |
+-----------+------------------+---------------+---------------+
| luminary2 | lm_R2-4-015_door | /light/right | light |
+-----------+------------------+---------------+---------------+
| Presence | ps_R2-4-015_door | /ps | p-sensor |
| sensor | | | |
+-----------+------------------+---------------+---------------+
Table 4: Resource Directory identifiers Table 5: 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 4.3 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
skipping to change at page 50, line 41 skipping to change at page 52, line 33
Location-Path: /rd/4522 Location-Path: /rd/4522
Req: POST coap://[2001:db8:4::ff]/rd Req: POST coap://[2001:db8:4::ff]/rd
?ep=ps_R2-4-015_door&base=coap://[2001:db8:4::3]d&d=R2-4-015 ?ep=ps_R2-4-015_door&base=coap://[2001:db8:4::3]d&d=R2-4-015
Payload: Payload:
</ps>;rt="p-sensor" </ps>;rt="p-sensor"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/4523 Location-Path: /rd/4523
Figure 23: Example of registrations a CT enters into an RD Figure 23: Example of registrations a CT enters into an RD
The sector name d=R2-4-015 has been added for an efficient lookup The sector name d=R2-4-015 has been added for an efficient lookup
because filtering on "ep" name is more awkward. The same sector name because filtering on "ep" name is more awkward. The same sector name
is communicated to the two luminaries and the presence sensor by the is communicated to the two luminaries and the presence sensor by the
CT. CT.
The group is specified in the RD. The base parameter is set to the The group is specified in the RD. The base parameter is set to the
site-local multicast address allocated to the group. In the POST in site-local multicast address allocated to the group. In the POST in
the example below, the resources supported by all group members are the example below, the resources supported by all group members are
published. published.
skipping to change at page 51, line 15 skipping to change at page 53, line 15
Req: POST coap://[2001:db8:4::ff]/rd Req: POST coap://[2001:db8:4::ff]/rd
?ep=grp_R2-4-015&et=core.rd-group&base=coap://[ff05::1] ?ep=grp_R2-4-015&et=core.rd-group&base=coap://[ff05::1]
Payload: Payload:
</light/left>;rt="light", </light/left>;rt="light",
</light/middle>;rt="light", </light/middle>;rt="light",
</light/right>;rt="light" </light/right>;rt="light"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/501 Location-Path: /rd/501
Figure 24: Example of a multicast group a CT enters into an RD Figure 24: Example of a multicast group a CT enters into an RD
After the filling of the RD by the CT, the application in the After the filling of the RD by the CT, the application in the
luminaries can learn to which groups they belong, and enable their luminaries can learn to which groups they belong, and enable their
interface for the multicast address. interface for the multicast address.
The luminary, knowing its sector and being configured to join any The luminary, knowing its sector and being configured to join any
group containing lights, searches for candidate groups and joins group containing lights, searches for candidate groups and joins
them: them:
Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep
?d=R2-4-015&et=core.rd-group&rt=light ?d=R2-4-015&et=core.rd-group&rt=light
Res: 2.05 Content Res: 2.05 Content
</rd/501>;ep="grp_R2-4-015";et="core.rd-group"; </rd/501>;ep="grp_R2-4-015";et="core.rd-group";
base="coap://[ff05::1]";rt="core.rd-ep" base="coap://[ff05::1]";rt="core.rd-ep"
Figure 25: Example of a lookup exchange to find suitable multicast Figure 25: Example of a lookup exchange to find suitable
addresses multicast addresses
From the returned base parameter value, the luminary learns the From the returned base parameter value, the luminary learns the
multicast address of the multicast group. multicast address of the multicast group.
Alternatively, the CT can communicate the multicast address directly Alternatively, the CT can communicate the multicast address directly
to the luminaries by using the "coap-group" resource specified in to the luminaries by using the "coap-group" resource specified in
[RFC7390]. [RFC7390].
Req: POST coap://[2001:db8:4::1]/coap-group Req: POST coap://[2001:db8:4::1]/coap-group
Content-Format: application/coap-group+json Content-Format: application/coap-group+json
Payload: Payload:
{ "a": "[ff05::1]", "n": "grp_R2-4-015"} { "a": "[ff05::1]", "n": "grp_R2-4-015"}
Res: 2.01 Created Res: 2.01 Created
Location-Path: /coap-group/1 Location-Path: /coap-group/1
Figure 26: Example use of direct multicast address configuration Figure 26: Example use of direct multicast address configuration
Dependent on the situation, only the address, "a", or the name, "n", Dependent on the situation, only the address, "a", or the name, "n",
is specified in the coap-group resource. is specified in the coap-group resource.
The presence sensor can learn the presence of groups that support The presence sensor can learn the presence of groups that support
resources with rt=light in its own sector by sending the same resources with rt=light in its own sector by sending the same
request, as used by the luminary. The presence sensor learns the request, as used by the luminary. The presence sensor learns the
multicast address to use for sending messages to the luminaries. multicast address to use for sending messages to the luminaries.
10.2. OMA Lightweight M2M (LWM2M) Example 10.2. OMA Lightweight M2M (LWM2M) Example
skipping to change at page 54, line 30 skipping to change at page 56, line 30
object instance using GET with a CoAP Content-Format of application/ object instance using GET with a CoAP Content-Format of application/
link-format. Resources may also be read as a structured object by link-format. Resources may also be read as a structured object by
performing a GET to the object instance with a Content-Format of performing a GET to the object instance with a Content-Format of
senml+json. senml+json.
When an LWM2M object or instance is registered, this indicates to the When an LWM2M object or instance is registered, this indicates to the
LWM2M server that the object and its resources are available for LWM2M server that the object and its resources are available for
management and service enablement (REST API) operations. management and service enablement (REST API) operations.
LWM2M endpoints may use the following RD registration parameters as LWM2M endpoints may use the following RD registration parameters as
defined in Table 2 : defined in Table 3 :
ep - Endpoint Name ep - Endpoint Name
lt - registration lifetime lt - registration lifetime
Endpoint Name, Lifetime, and LWM2M Version are mandatory parameters Endpoint Name, Lifetime, and LWM2M Version are mandatory parameters
for the register operation, all other registration parameters are for the register operation, all other registration parameters are
optional. optional.
Additional optional LWM2M registration parameters are defined: Additional optional LWM2M registration parameters are defined:
+-----------+-------+-------------------------------+---------------+ +---------+-------+-------------------------------+-------------+
| Name | Query | Validity | Description | | Name | Query | Validity | Description |
+-----------+-------+-------------------------------+---------------+ +=========+=======+===============================+=============+
| Binding | b | {"U",UQ","S","SQ","US","UQS"} | Available | | Binding | b | {"U",UQ","S","SQ","US","UQS"} | Available |
| Mode | | | Protocols | | Mode | | | Protocols |
| | | | | +---------+-------+-------------------------------+-------------+
| LWM2M | ver | 1.0 | Spec Version | +---------+-------+-------------------------------+-------------+
| Version | | | | | LWM2M | ver | 1.0 | Spec |
| | | | | | Version | | | Version |
| SMS | sms | | MSISDN | +---------+-------+-------------------------------+-------------+
| Number | | | | +---------+-------+-------------------------------+-------------+
+-----------+-------+-------------------------------+---------------+ | SMS | sms | | MSISDN |
| Number | | | |
+---------+-------+-------------------------------+-------------+
Table 5: LWM2M Additional Registration Parameters Table 6: LWM2M Additional Registration Parameters
The following RD registration parameters are not currently specified The following RD registration parameters are not currently specified
for use in LWM2M: for use in LWM2M:
et - Endpoint Type et - Endpoint Type
base - Registration Base URI base - Registration Base URI
The endpoint registration must include a payload containing links to The endpoint registration must include a payload containing links to
all supported objects and existing object instances, optionally all supported objects and existing object instances, optionally
including the appropriate link-format relations. including the appropriate link-format relations.
skipping to change at page 56, line 27 skipping to change at page 58, line 33
Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen,
Hannes Tschofenig, Sampo Ukkola, Linyi Tian, Jan Newmarch, Matthias Hannes Tschofenig, Sampo Ukkola, Linyi Tian, Jan Newmarch, Matthias
Kovatsch, Jaime Jimenez and Ted Lemon have provided helpful comments, Kovatsch, Jaime Jimenez and Ted Lemon have provided helpful comments,
discussions and ideas to improve and shape this document. Zach would discussions and ideas to improve and shape this document. Zach would
also like to thank his colleagues from the EU FP7 SENSEI project, also like to thank his colleagues from the EU FP7 SENSEI project,
where many of the resource directory concepts were originally where many of the resource directory concepts were originally
developed. developed.
12. Changelog 12. Changelog
changes from -23 to -24
* Discovery using DNS-SD added again
* Minimum lifetime (lt) reduced from 60 to 1
* References added
* IANA considerations
- added about .well-known/core resource
- added DNS-SD service names
- made RDAO option number a suggestion
- added "reference" field to endpoint type registry
* Lookup: mention that anchor is a legitimate lookup attribute
* Terminology and example fixes
* Layout fixes, esp. the use of non-ASCII characters in figures
changes from -22 to -23 changes from -22 to -23
o Explain that updates can not remove attributes * Explain that updates can not remove attributes
o Typo fixes * Typo fixes
changes from -21 to -22 changes from -21 to -22
o Request a dedicated IPv4 address from IANA (rather than sharing * Request a dedicated IPv4 address from IANA (rather than sharing
with All CoAP nodes) with All CoAP nodes)
o Fix erroneous examples * Fix erroneous examples
o Editorial changes * Editorial changes
* Add figure numbers to examples - Add figure numbers to examples
* Update RD parameters table to reflect changes of earlier - Update RD parameters table to reflect changes of earlier
versions in the text versions in the text
* Typos and minor wording - Typos and minor wording
changes from -20 to -21 changes from -20 to -21
(Processing comments during WGLC) (Processing comments during WGLC)
o Defer outdated description of using DNS-SD to find an RD to the
* Defer outdated description of using DNS-SD to find an RD to the
defining document defining document
o Describe operational conditions in automation example * Describe operational conditions in automation example
o Recommend particular discovery mechanisms for some managed network * Recommend particular discovery mechanisms for some managed network
scenarios scenarios
changes from -19 to -20 changes from -19 to -20
(Processing comments from the WG chair review) (Processing comments from the WG chair review)
o Define the permissible characters in endpoint and sector names * 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 * Express requirements on NAT situations in more abstract terms
o Group instructions for error handling into general section * Shifted heading levels to have the interfaces on the same level
* Group instructions for error handling into general section
o Simple Registration: process reflowed into items list * Simple Registration: process reflowed into items list
o Updated introduction to reflect state of CoRE in general, * Updated introduction to reflect state of CoRE in general,
reference RFC7228 (defining "constrained") and use "IoT" term in reference RFC7228 (defining "constrained") and use "IoT" term in
addition to "M2M" addition to "M2M"
o Update acknowledgements * Update acknowledgements
o Assorted editorial changes * Assorted editorial changes
* Unify examples style - Unify examples style
* Terminology: RDAO defined and not only expanded - Terminology: RDAO defined and not only expanded
* Add CT to Figure 1 - Add CT to Figure 1
* Consistency in the use of the term "Content Format" - 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 * 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 * 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),
* 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 * Acknowledging the -17 version as part of the draft
o Move "Read endpoint links" operation to future specification like * Move "Read endpoint links" operation to future specification like
PATCH PATCH
o Demote links-json to an informative reference, and removed them * Demote links-json to an informative reference, and removed them
from exchange examples from exchange examples
o Add note on unusability of link-local IP addresses, and describe * Add note on unusability of link-local IP addresses, and describe
mitigation. mitigation.
o Reshuffling of sections: Move additional operations and endpoint * Reshuffling of sections: Move additional operations and endpoint
lookup back from appendix, and groups into one lookup back from appendix, and groups into one
o Lookup interface tightened to not imply applicability for non * Lookup interface tightened to not imply applicability for non
link-format lookups (as those can have vastly different views on link-format lookups (as those can have vastly different views on
link cardinality) link cardinality)
o Simple registration: Change sequence of GET and POST-response, * Simple registration: Change sequence of GET and POST-response,
ensuring unsuccessful registrations are reported as such, and ensuring unsuccessful registrations are reported as such, and
suggest how devices that would have required the inverse behavior suggest how devices that would have required the inverse behavior
can still cope with it. can still cope with it.
o Abstract and introduction reworded to avoid the impression that * Abstract and introduction reworded to avoid the impression that
resources are stored in full in the RD resources are stored in full in the RD
o Simplify the rules governing when a registration resource can or * Simplify the rules governing when a registration resource can or
must be changed. must be changed.
o Drop a figure that has become useless due to the changes of and * Drop a figure that has become useless due to the changes of and
-13 and -17 -13 and -17
o Wording consistency fixes: Use "Registrations" and "target * Wording consistency fixes: Use "Registrations" and "target
attributes" attributes"
o Fix incorrect use of content negotiation in discovery interface * Fix incorrect use of content negotiation in discovery interface
description (Content-Format -> Accept) description (Content-Format -> Accept)
o State that the base attribute value is part of endpoint lookup * State that the base attribute value is part of endpoint lookup
even when implicit in the registration even when implicit in the registration
o Update references from RFC5988 to its update RFC8288 * Update references from RFC5988 to its update RFC8288
o Remove appendix on protocol-negotiation (which had a note to be
* Remove appendix on protocol-negotiation (which had a note to be
removed before publication) removed before publication)
changes from -16 to -17 changes from -16 to -17
(Note that -17 is published as a direct follow-up to -16, containing (Note that -17 is published as a direct follow-up to -16, containing
a single change to be discussed at IETF103) a single change to be discussed at IETF103)
o Removed groups that are enumerations of registrations and have * Removed groups that are enumerations of registrations and have
dedicated mechanism dedicated mechanism
o Add groups that are enumerations of shared resources and are a * Add groups that are enumerations of shared resources and are a
special case of endpoint registrations special case of endpoint registrations
changes from -15 to -16 changes from -15 to -16
o Recommend a common set of resources for members of a group * Recommend a common set of resources for members of a group
o Clarified use of multicast group in lighting example
o Add note on concurrent registrations from one EP being possible * Clarified use of multicast group in lighting example
* Add note on concurrent registrations from one EP being possible
but not expected but not expected
o Refresh web examples appendix to reflect current use of Modernized * Refresh web examples appendix to reflect current use of Modernized
Link Format Link Format
o Add examples of URIs where Modernized Link Format matters * Add examples of URIs where Modernized Link Format matters
o Editorial changes * Editorial changes
changes from -14 to -15 changes from -14 to -15
o Rewrite of section "Security policies" * Rewrite of section "Security policies"
o Clarify that the "base" parameter text applies both to relative * Clarify that the "base" parameter text applies both to relative
references both in anchor and href references both in anchor and href
o Renamed "Registree-EP" to Registrant-EP" * Renamed "Registree-EP" to Registrant-EP"
o Talk of "relative references" and "URIs" rather than "relative" * Talk of "relative references" and "URIs" rather than "relative"
and "absolute" URIs. (The concept of "absolute URIs" of [RFC3986] and "absolute" URIs. (The concept of "absolute URIs" of [RFC3986]
is not needed in RD). is not needed in RD).
o Fixed examples * Fixed examples
o Editorial changes * Editorial changes
changes from -13 to -14 changes from -13 to -14
o Rename "registration context" to "registration base URI" (and
* Rename "registration context" to "registration base URI" (and
"con" to "base") and "domain" to "sector" (where the abbreviation "con" to "base") and "domain" to "sector" (where the abbreviation
"d" stays for compatibility reasons) "d" stays for compatibility reasons)
o Introduced resource types core.rd-ep and core.rd-gp * Introduced resource types core.rd-ep and core.rd-gp
o Registration management moved to appendix A, including endpoint * Registration management moved to appendix A, including endpoint
and group lookup and group lookup
o Minor editorial changes * Minor editorial changes
* PATCH/iPATCH is clearly deferred to another document - PATCH/iPATCH is clearly deferred to another document
* Recommend against query / fragment identifier in con= - Recommend against query / fragment identifier in con=
* Interface description lists are described as illustrative - Interface description lists are described as illustrative
* Rewording of Simple Registration - Rewording of Simple Registration
o Simple registration carries no error information and succeeds * Simple registration carries no error information and succeeds
immediately (previously, sequence was unspecified) immediately (previously, sequence was unspecified)
o Lookup: href are matched against resolved values (previously, this * Lookup: href are matched against resolved values (previously, this
was unspecified) was unspecified)
o Lookup: lt are not exposed any more * Lookup: lt are not exposed any more
o con/base: Paths are allowed * con/base: Paths are allowed
o Registration resource locations can not have query or fragment * Registration resource locations can not have query or fragment
parts parts
o Default life time extended to 25 hours * Default life time extended to 25 hours
o clarified registration update rules * clarified registration update rules
o lt-value semantics for lookup clarified. * lt-value semantics for lookup clarified.
o added template for simple registration * added template for simple registration
changes from -12 to -13 changes from -12 to -13
o Added "all resource directory" nodes MC address * Added "all resource directory" nodes MC address
o Clarified observation behavior * Clarified observation behavior
o version identification * version identification
o example rt= and et= values
o domain from figure 2 * example rt= and et= values
o more explanatory text * domain from figure 2
o endpoints of a groups hosted by different RD * more explanatory text
o resolve RFC6690-vs-8288 resolution ambiguities: * endpoints of a groups hosted by different RD
* require registered links not to be relative when using anchor * resolve RFC6690-vs-8288 resolution ambiguities:
* return absolute URIs in resource lookup - require registered links not to be relative when using anchor
changes from -11 to -12 - return absolute URIs in resource lookup
o added Content Model section, including ER diagram changes from -11 to -12
o removed domain lookup interface; domains are now plain attributes * added Content Model section, including ER diagram
* removed domain lookup interface; domains are now plain attributes
of groups and endpoints of groups and endpoints
o updated chapter "Finding a Resource Directory"; now distinguishes * updated chapter "Finding a Resource Directory"; now distinguishes
configuration-provided, network-provided and heuristic sources configuration-provided, network-provided and heuristic sources
o improved text on: atomicity, idempotency, lookup with multiple * improved text on: atomicity, idempotency, lookup with multiple
parameters, endpoint removal, simple registration parameters, endpoint removal, simple registration
o updated LWM2M description * updated LWM2M description
o clarified where relative references are resolved, and how context * clarified where relative references are resolved, and how context
and anchor interact and anchor interact
o new appendix on the interaction with RFCs 6690, 5988 and 3986 * new appendix on the interaction with RFCs 6690, 5988 and 3986
o lookup interface: group and endpoint lookup return group and * lookup interface: group and endpoint lookup return group and
registration resources as link targets registration resources as link targets
o lookup interface: search parameters work the same across all * lookup interface: search parameters work the same across all
entities entities
o removed all methods that modify links in an existing registration * removed all methods that modify links in an existing registration
(POST with payload, PATCH and iPATCH) (POST with payload, PATCH and iPATCH)
o removed plurality definition (was only needed for link * removed plurality definition (was only needed for link
modification) modification)
o enhanced IANA registry text * enhanced IANA registry text
o state that lookup resources can be observable
o More examples and improved text * state that lookup resources can be observable
changes from -09 to -10 * More examples and improved text
o removed "ins" and "exp" link-format extensions. changes from -09 to -10
o removed all text concerning DNS-SD. * removed "ins" and "exp" link-format extensions.
o removed inconsistency in RDAO text. * removed all text concerning DNS-SD.
o suggestions taken over from various sources * removed inconsistency in RDAO text.
o replaced "Function Set" with "REST API", "base URI", "base path" * suggestions taken over from various sources
o moved simple registration to registration section * replaced "Function Set" with "REST API", "base URI", "base path"
* moved simple registration to registration section
changes from -08 to -09 changes from -08 to -09
o clarified the "example use" of the base RD resource values /rd, * clarified the "example use" of the base RD resource values /rd,
/rd-lookup, and /rd-group. /rd-lookup, and /rd-group.
o changed "ins" ABNF notation. * changed "ins" ABNF notation.
o various editorial improvements, including in examples * various editorial improvements, including in examples
o clarifications for RDAO * clarifications for RDAO
changes from -07 to -08 changes from -07 to -08
o removed link target value returned from domain and group lookup * removed link target value returned from domain and group lookup
types types
o Maximum length of domain parameter 63 bytes for consistency with * Maximum length of domain parameter 63 bytes for consistency with
group group
o removed option for simple POST of link data, don't require a * removed option for simple POST of link data, don't require a
.well-known/core resource to accept POST data and handle it in a .well-known/core resource to accept POST data and handle it in a
special way; we already have /rd for that special way; we already have /rd for that
o add IPv6 ND Option for discovery of an RD * add IPv6 ND Option for discovery of an RD
o clarify group configuration section 6.1 that endpoints must be * clarify group configuration section 6.1 that endpoints must be
registered before including them in a group registered before including them in a group
o removed all superfluous client-server diagrams * removed all superfluous client-server diagrams
o simplified lighting example
o introduced Commissioning Tool * simplified lighting example
o RD-Look-up text is extended. * introduced Commissioning Tool
* RD-Look-up text is extended.
changes from -06 to -07 changes from -06 to -07
o added text in the discovery section to allow content format hints * added text in the discovery section to allow content format hints
to be exposed in the discovery link attributes to be exposed in the discovery link attributes
o editorial updates to section 9 * editorial updates to section 9
o update author information * update author information
o minor text corrections * minor text corrections
Changes from -05 to -06 Changes from -05 to -06
* added note that the PATCH section is contingent on the progress of
o added note that the PATCH section is contingent on the progress of
the PATCH method the PATCH method
changes from -04 to -05 changes from -04 to -05
o added Update Endpoint Links using PATCH * added Update Endpoint Links using PATCH
o http access made explicit in interface specification * http access made explicit in interface specification
o Added http examples * Added http examples
Changes from -03 to -04: Changes from -03 to -04:
o Added http response codes * Added http response codes
o Clarified endpoint name usage * Clarified endpoint name usage
o Add application/link-format+cbor content-format * Add application/link-format+cbor content-format
Changes from -02 to -03: Changes from -02 to -03:
o Added an example for lighting and DNS integration * Added an example for lighting and DNS integration
o Added an example for RD use in OMA LWM2M * Added an example for RD use in OMA LWM2M
o Added Read Links operation for link inspection by endpoints * Added Read Links operation for link inspection by endpoints
o Expanded DNS-SD section * Expanded DNS-SD section
o Added draft authors Peter van der Stok and Michael Koster
* Added draft authors Peter van der Stok and Michael Koster
Changes from -01 to -02: Changes from -01 to -02:
o Added a catalogue use case. * Added a catalogue use case.
o Changed the registration update to a POST with optional link * Changed the registration update to a POST with optional link
format payload. Removed the endpoint type update from the update. format payload. Removed the endpoint type update from the update.
o Additional examples section added for more complex use cases. * Additional examples section added for more complex use cases.
o New DNS-SD mapping section. * New DNS-SD mapping section.
o Added text on endpoint identification and authentication. * Added text on endpoint identification and authentication.
o Error code 4.04 added to Registration Update and Delete requests. * Error code 4.04 added to Registration Update and Delete requests.
o Made 63 bytes a SHOULD rather than a MUST for endpoint name and * Made 63 bytes a SHOULD rather than a MUST for endpoint name and
resource type parameters. resource type parameters.
Changes from -00 to -01: Changes from -00 to -01:
o Removed the ETag validation feature. * Removed the ETag validation feature.
o Place holder for the DNS-SD mapping section. * Place holder for the DNS-SD mapping section.
o Explicitly disabled GET or POST on returned Location. * Explicitly disabled GET or POST on returned Location.
o New registry for RD parameters. * New registry for RD parameters.
o Added support for the JSON Link Format. * Added support for the JSON Link Format.
o Added reference to the Groupcomm WG draft. * Added reference to the Groupcomm WG draft.
Changes from -05 to WG Document -00: Changes from -05 to WG Document -00:
o Updated the version and date. * Updated the version and date.
Changes from -04 to -05: Changes from -04 to -05:
o Restricted Update to parameter updates. * Restricted Update to parameter updates.
o Added pagination support for the Lookup interface. * Added pagination support for the Lookup interface.
o Minor editing, bug fixes and reference updates. * Minor editing, bug fixes and reference updates.
o Added group support. * Added group support.
o Changed rt to et for the registration and update interface. * Changed rt to et for the registration and update interface.
Changes from -03 to -04: Changes from -03 to -04:
o Added the ins= parameter back for the DNS-SD mapping. * Added the ins= parameter back for the DNS-SD mapping.
o Integrated the Simple Directory Discovery from Carsten. * Integrated the Simple Directory Discovery from Carsten.
o Editorial improvements. * Editorial improvements.
o Fixed the use of ETags. * Fixed the use of ETags.
o Fixed tickets 383 and 372 * Fixed tickets 383 and 372
Changes from -02 to -03: Changes from -02 to -03:
o Changed the endpoint name back to a single registration parameter * Changed the endpoint name back to a single registration parameter
ep= and removed the h= and ins= parameters. ep= and removed the h= and ins= parameters.
o Updated REST interface descriptions to use RFC6570 URI Template * Updated REST interface descriptions to use RFC6570 URI Template
format. format.
o Introduced an improved RD Lookup design as its own function set. * Introduced an improved RD Lookup design as its own function set.
o Improved the security considerations section. * Improved the security considerations section.
o Made the POST registration interface idempotent by requiring the * Made the POST registration interface idempotent by requiring the
ep= parameter to be present. ep= parameter to be present.
Changes from -01 to -02: Changes from -01 to -02:
o Added a terminology section. * Added a terminology section.
o Changed the inclusion of an ETag in registration or update to a * Changed the inclusion of an ETag in registration or update to a
MAY. MAY.
o Added the concept of an RD Domain and a registration parameter for * Added the concept of an RD Domain and a registration parameter for
it. it.
o Recommended the Location returned from a registration to be * Recommended the Location returned from a registration to be
stable, allowing for endpoint and Domain information to be changed stable, allowing for endpoint and Domain information to be changed
during updates. during updates.
o Changed the lookup interface to accept endpoint and Domain as * Changed the lookup interface to accept endpoint and Domain as
query string parameters to control the scope of a lookup. query string parameters to control the scope of a lookup.
13. References 13. References
13.1. Normative References 13.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 66, line 40 skipping to change at page 69, line 19
<https://www.rfc-editor.org/info/rfc6763>. <https://www.rfc-editor.org/info/rfc6763>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
13.2. Informative References 13.2. Informative References
[ER] Chen, P., "The entity-relationship model---toward a [ER] Chen, P., "The entity-relationship model---toward a
unified view of data", ACM Transactions on Database unified view of data", DOI 10.1145/320434.320440, ACM
Systems Vol. 1, pp. 9-36, DOI 10.1145/320434.320440, March Transactions on Database Systems Vol. 1, pp. 9-36, March
1976. 1976, <https://doi.org/10.1145/320434.320440>.
[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", Work in Progress,
t2trg-rel-impl-00 (work in progress), January 2018. Internet-Draft, draft-bormann-t2trg-rel-impl-00, 28
January 2018, <http://www.ietf.org/internet-drafts/draft-
bormann-t2trg-rel-impl-00.txt>.
[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-08 (work in progress), (CoRAL)", Work in Progress, Internet-Draft, draft-hartke-
March 2019. t2trg-coral-09, 8 July 2019, <http://www.ietf.org/
internet-drafts/draft-hartke-t2trg-coral-09.txt>.
[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-24 Framework (ACE-OAuth)", Work in Progress, Internet-Draft,
(work in progress), March 2019. draft-ietf-ace-oauth-authz-33, 6 February 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-ace-oauth-
authz-33.txt>.
[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", Work in Progress, Internet-Draft, draft-
progress), February 2018. ietf-core-links-json-10, 26 February 2018,
<http://www.ietf.org/internet-drafts/draft-ietf-core-
links-json-10.txt>.
[I-D.ietf-core-rd-dns-sd] [I-D.ietf-core-rd-dns-sd]
Stok, P., Koster, M., and C. Amsuess, "CoRE Resource Stok, P., Koster, M., and C. Amsuess, "CoRE Resource
Directory: DNS-SD mapping", draft-ietf-core-rd-dns-sd-05 Directory: DNS-SD mapping", Work in Progress, Internet-
(work in progress), July 2019. Draft, draft-ietf-core-rd-dns-sd-05, 7 July 2019,
<http://www.ietf.org/internet-drafts/draft-ietf-core-rd-
dns-sd-05.txt>.
[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 Work in Progress, Internet-Draft, draft-silverajan-core-
in progress), July 2018. coap-protocol-negotiation-09, 2 July 2018,
<http://www.ietf.org/internet-drafts/draft-silverajan-
core-coap-protocol-negotiation-09.txt>.
[RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
"Transmission of IPv6 Packets over IEEE 802.15.4 "Transmission of IPv6 Packets over IEEE 802.15.4
Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007, Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007,
<https://www.rfc-editor.org/info/rfc4944>. <https://www.rfc-editor.org/info/rfc4944>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>.
[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>.
skipping to change at page 68, line 25 skipping to change at page 71, line 22
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<https://www.rfc-editor.org/info/rfc7641>. <https://www.rfc-editor.org/info/rfc7641>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/info/rfc8132>. <https://www.rfc-editor.org/info/rfc8132>.
[RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names
(URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
<https://www.rfc-editor.org/info/rfc8141>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
Appendix A. Groups Registration and Lookup Appendix A. Groups Registration and Lookup
The RD-Groups usage pattern allows announcing application groups The RD-Groups usage pattern allows announcing application groups
inside a Resource Directory. inside a Resource Directory.
Groups are represented by endpoint registrations. Their base address Groups are represented by endpoint registrations. Their base address
skipping to change at page 69, line 15 skipping to change at page 72, line 15
Req: POST coap://rd.example.com/rd?ep=lights&et=core.rd-group Req: POST coap://rd.example.com/rd?ep=lights&et=core.rd-group
&base=coap://[ff35:30:2001:db8::1] &base=coap://[ff35:30:2001:db8::1]
Content-Format: 40 Content-Format: 40
Payload: Payload:
</light>;rt="light";if="core.a", </light>;rt="light";if="core.a",
</color-temperature>;if="core.p";u="K" </color-temperature>;if="core.p";u="K"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/12 Location-Path: /rd/12
Figure 27: Example registration of a group Figure 27: Example registration of a group
In this example, the group manager can easily permit devices that In this example, the group manager can easily permit devices that
have no writable color-temperature to join, as they would still have no writable color-temperature to join, as they would still
respond to brightness changing commands. Had the group instead respond to brightness changing commands. Had the group instead
contained a single resource that sets brightness and color contained a single resource that sets brightness and color
temperature atomically, endpoints would need to support both temperature atomically, endpoints would need to support both
properties. properties.
The resources of a group can be looked up like any other resource, The resources of a group can be looked up like any other resource,
and the group registrations (along with any additional registration and the group registrations (along with any additional registration
parameters) can be looked up using the endpoint lookup interface. parameters) can be looked up using the endpoint lookup interface.
The following example shows a client performing and endpoint lookup The following example shows a client performing and endpoint lookup
for all groups. for all groups.
Req: GET /rd-lookup/ep?et=core.rd-group Req: GET /rd-lookup/ep?et=core.rd-group
Res: 2.01 Content Res: 2.05 Content
Payload: Payload:
</rd/501>;ep="GRP_R2-4-015";et="core.rd-group"; </rd/501>;ep="GRP_R2-4-015";et="core.rd-group";
base="coap://[ff05::1]", base="coap://[ff05::1]",
</rd/12>;ep=lights&et=core.rd-group; </rd/12>;ep=lights&et=core.rd-group;
base="coap://[ff35:30:2001:db8::1]";rt="core.rd-ep" base="coap://[ff35:30:2001:db8::1]";rt="core.rd-ep"
Figure 28: Example lookup of groups Figure 28: Example lookup of groups
The following example shows a client performing a lookup of all The following example shows a client performing a lookup of all
resources of all endpoints (groups) with et=core.rd-group. resources of all endpoints (groups) with et=core.rd-group.
Req: GET /rd-lookup/res?et=core.rd-group Req: GET /rd-lookup/res?et=core.rd-group
<coap://[ff35:30:2001:db8::1]/light>;rt="light";if="core.a"; <coap://[ff35:30:2001:db8::1]/light>;rt="light";if="core.a";
et="core.rd-group";anchor="coap://[ff35:30:2001:db8::1]", et="core.rd-group";anchor="coap://[ff35:30:2001:db8::1]",
<coap://[ff35:30:2001:db8::1]/color-temperature>;if="core.p";u="K"; <coap://[ff35:30:2001:db8::1]/color-temperature>;if="core.p";u="K";
et="core.rd-group"; et="core.rd-group";
anchor="coap://[ff35:30:2001:db8::1]" anchor="coap://[ff35:30:2001:db8::1]"
Figure 29: Example lookup of resources inside groups
Figure 29: Example lookup of resources inside groups
Appendix B. Web links and the Resource Directory Appendix B. Web links and the Resource Directory
Understanding the semantics of a link-format document and its URI Understanding the semantics of a link-format document and its URI
references is a journey through different documents ([RFC3986] references is a journey through different documents ([RFC3986]
defining URIs, [RFC6690] defining link-format documents based on defining URIs, [RFC6690] defining link-format documents based on
[RFC8288] which defines link headers, and [RFC7252] providing the [RFC8288] which defines Link header fields, and [RFC7252] providing
transport). This appendix summarizes the mechanisms and semantics at the transport). This appendix summarizes the mechanisms and
play from an entry in ".well-known/core" to a resource lookup. semantics at play from an entry in ".well-known/core" to a resource
lookup.
This text is primarily aimed at people entering the field of This text is primarily aimed at people entering the field of
Constrained Restful Environments from applications that previously Constrained Restful Environments from applications that previously
did not use web mechanisms. did not use web mechanisms.
The explanation of the steps makes some shortcuts in the more The explanation of the steps makes some shortcuts in the more
confusing details of [RFC6690], which are justified as all examples confusing details of [RFC6690], which are justified as all examples
being in Limited Link Format. being in Limited Link Format.
B.1. A simple example B.1. A simple example
skipping to change at page 71, line 15 skipping to change at page 74, line 13
retrieval from the RD without any shortcuts are: retrieval from the RD without any shortcuts are:
B.1.1. Resolving the URIs B.1.1. Resolving the URIs
The client parses the single returned record. The link's target The client parses the single returned record. The link's target
(sometimes called "href") is ""/temp"", which is a relative URI that (sometimes called "href") is ""/temp"", which is a relative URI that
needs resolving. The base URI <coap://[ff02::fd]:5683/.well-known/ needs resolving. The base URI <coap://[ff02::fd]:5683/.well-known/
core> is used to resolve the reference /temp against. core> is used to resolve the reference /temp against.
The Base URI of the requested resource can be composed from the The Base URI of the requested resource can be composed from the
header options of the CoAP GET request by following the steps of options of the CoAP GET request by following the steps of [RFC7252]
[RFC7252] section 6.5 (with an addition at the end of 8.2) into section 6.5 (with an addition at the end of 8.2) into
""coap://[2001:db8:f0::1]/.well-known/core"". ""coap://[2001:db8:f0::1]/.well-known/core"".
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
skipping to change at page 72, line 14 skipping to change at page 75, line 14
GET coap://[ff02::fd]:5683/.well-known/core GET coap://[ff02::fd]:5683/.well-known/core
RES 2.05 Content RES 2.05 Content
</temp>;rt=temperature;ct=0, </temp>;rt=temperature;ct=0,
</light>;rt=light-lux;ct=0, </light>;rt=light-lux;ct=0,
</t>;anchor="/sensors/temp";rel=alternate, </t>;anchor="/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>;anchor="/temp"; <http://www.example.com/sensors/t123>;anchor="/temp";
rel="describedby" rel="describedby"
Figure 31: Extended example of direct resource discovery Figure 31: Extended example of direct resource discovery
Parsing the third record, the client encounters the "anchor" Parsing the third record, the client encounters the "anchor"
parameter. It is a URI relative to the Base URI of the request and parameter. It is a URI relative to the Base URI of the request and
is thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That is thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That
is the context resource of the link, so the "rel" statement is not is the context resource of the link, so the "rel" statement is not
about the target and the Base URI any more, but about the target and about the target and the Base URI any more, but about the target and
the resolved URI. Thus, the third record could be read as the resolved URI. Thus, the third record could be read as
""coap://[2001:db8:f0::1]/sensors/temp" has an alternate ""coap://[2001:db8:f0::1]/sensors/temp" has an alternate
representation at "coap://[2001:db8:f0::1]/t"". representation at "coap://[2001:db8:f0::1]/t"".
skipping to change at page 73, line 47 skipping to change at page 76, line 47
<coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0; <coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0;
anchor="coap://[2001:db8:f0::1]", anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0; <coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0;
anchor="coap://[2001:db8:f0::1]", anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/t>; <coap://[2001:db8:f0::1]/t>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>; <http://www.example.com/sensors/t123>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby" anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby"
Figure 34: Extended example payload of a response to a resource Figure 34: Extended example payload of a response to a resource
lookup lookup
All the target and anchor references are already in absolute form All the target and anchor references are already in absolute form
there, which don't need to be resolved any further. there, which don't need to be resolved any further.
Had the simple host done an equivalent full registration with a base= Had the simple host done an equivalent full registration with a base=
parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple- parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple-
host1.example.com"), that context would have been used to resolve the host1.example.com"), that context would have been used to resolve the
relative anchor values instead, giving relative anchor values instead, giving
<coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0; <coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0;
anchor="coap+tcp://simple-host1.example.com" anchor="coap+tcp://simple-host1.example.com"
Figure 35: Example payload of a response to a resource lookup with a Figure 35: Example payload of a response to a resource lookup
dedicated base URI with a dedicated base URI
and analogous records. and analogous records.
B.4. A note on differences between link-format and Link headers B.4. A note on differences between link-format and Link header fields
While link-format and Link headers look very similar and are based on While link-format and Link header fields look very similar and are
the same model of typed links, there are some differences between based on the same model of typed links, there are some differences
[RFC6690] and [RFC8288], which are dealt with differently: between [RFC6690] and [RFC8288], which are dealt with differently:
o "Resolving the target against the anchor": [RFC6690] Section 2.1 * "Resolving the target against the anchor": [RFC6690] Section 2.1
states that the anchor of a link is used as the Base URI against states that the anchor of a link is used as the Base URI against
which the term inside the angle brackets (the target) is resolved, which the term inside the angle brackets (the target) is resolved,
falling back to the resource's URI with paths stripped off (its falling back to the resource's URI with paths stripped off (its
"Origin"). In contrast to that, [RFC8288] Section B.2 describes "Origin"). In contrast to that, [RFC8288] Section B.2 describes
that the anchor is immaterial to the resolution of the target that the anchor is immaterial to the resolution of the target
reference. reference.
RFC6690, in the same section, also states that absent anchors set RFC6690, in the same section, also states that absent anchors set
the context of the link to the target's URI with its path stripped the context of the link to the target's URI with its path stripped
off, while according to [RFC8288] Section 3.2, the context is the off, while according to [RFC8288] Section 3.2, the context is the
resource's base URI. resource's base URI.
The rules introduced in Appendix C ensure that an RD does not need The rules introduced in Appendix C ensure that an RD does not need
to deal with those differences when processing input data. Lookup to deal with those differences when processing input data. Lookup
results are required to be absolute references for the same results are required to be absolute references for the same
reason. reason.
o There is no percent encoding in link-format documents. * There is no percent encoding in link-format documents.
A link-format document is a UTF-8 encoded string of Unicode A link-format document is a UTF-8 encoded string of Unicode
characters and does not have percent encoding, while Link headers characters and does not have percent encoding, while Link header
are practically ASCII strings that use percent encoding for non- fields are practically ASCII strings that use percent encoding for
ASCII characters, stating the encoding explicitly when required. non-ASCII characters, stating the encoding explicitly when
required.
For example, while a Link header in a page about a Swedish city For example, while a Link header field in a page about a Swedish
might read city might read
Link: </temperature/Malm%C3%B6>;rel="live-environment-data"
"Link: </temperature/Malm%C3%B6>;rel="live-environment-data""
a link-format document from the same source might describe the a link-format document from the same source might describe the
link as link as
"</temperature/Malmoe>;rel="live-environment-data"" </temperature/Malmö>;rel="live-environment-data"
Parsers and producers of link-format and header data need to be Parsers and producers of link-format and header fields need to be
aware of this difference. aware of this difference.
Appendix C. Limited Link Format Appendix C. Limited Link Format
The CoRE Link Format as described in [RFC6690] has been interpreted The CoRE Link Format as described in [RFC6690] has been interpreted
differently by implementers, and a strict implementation rules out differently by implementers, and a strict implementation rules out
some use cases of a Resource Directory (e.g. base values with path some use cases of a Resource Directory (e.g. base values with path
components). components).
This appendix describes a subset of link format documents called This appendix describes a subset of link format documents called
skipping to change at page 75, line 32 skipping to change at page 78, line 34
are aware of already stick to them - but ease the implementation of are aware of already stick to them - but ease the implementation of
resource directory servers. resource directory servers.
It is applicable to representations in the application/link-format It is applicable to representations in the application/link-format
media type, and any other media types that inherit [RFC6690] media type, and any other media types that inherit [RFC6690]
Section 2.1. Section 2.1.
A link format representation is in Limited Link format if, for each A link format representation is in Limited Link format if, for each
link in it, the following applies: link in it, the following applies:
o All URI references either follow the URI or the path-absolute ABNF * All URI references either follow the URI or the path-absolute ABNF
rule of RFC3986 (i.e. target and anchor each either start with a rule of RFC3986 (i.e. target and anchor each either start with a
scheme or with a single slash), scheme or with a single slash),
o if the anchor reference starts with a scheme, the target reference * if the anchor reference starts with a scheme, the target reference
starts with a scheme as well (i.e. relative references in target starts with a scheme as well (i.e. relative references in target
cannot be used when the anchor is a full URI), and cannot be used when the anchor is a full URI), and
o the application does not care whether links without an explicitly * the application does not care whether links without an explicitly
given anchor have the origin's "/" or "/.well-known/core" resource given anchor have the origin's "/" or "/.well-known/core" resource
as their link context. as their link context.
Authors' Addresses Authors' Addresses
Zach Shelby Zach Shelby
ARM ARM
150 Rose Orchard 150 Rose Orchard
San Jose 95134 San Jose, 95134
USA United States of America
Phone: +1-408-203-9434 Phone: +1-408-203-9434
Email: zach.shelby@arm.com Email: zach.shelby@arm.com
Michael Koster Michael Koster
SmartThings SmartThings
665 Clyde Avenue 665 Clyde Avenue
Mountain View 94043 Mountain View, 94043
USA United States of America
Phone: +1-707-502-5136 Phone: +1-707-502-5136
Email: Michael.Koster@smartthings.com Email: Michael.Koster@smartthings.com
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 D-28359 Bremen
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org Email: cabo@tzi.org
Peter van der Stok Peter van der Stok
consultant consultant
Phone: +31-492474673 (Netherlands), +33-966015248 (France) Phone: +31-492474673 (Netherlands), +33-966015248 (France)
Email: consultancy@vanderstok.org Email: consultancy@vanderstok.org
URI: www.vanderstok.org URI: www.vanderstok.org
Christian Amsuess (editor) Christian Amsüss (editor)
Hollandstr. 12/4 Hollandstr. 12/4
1020 1020
Austria Austria
Phone: +43-664-9790639 Phone: +43-664-9790639
Email: christian@amsuess.com Email: christian@amsuess.com
 End of changes. 330 change blocks. 
538 lines changed or deleted 673 lines changed or added

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