draft-ietf-core-resource-directory-24.txt   draft-ietf-core-resource-directory-25.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: 10 September 2020 SmartThings Expires: 14 January 2021 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
C. Amsüss, Ed. C. Amsüss, Ed.
9 March 2020 13 July 2020
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-24 draft-ietf-core-resource-directory-25
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 an RD supports for web servers to discover the RD and
discover the RD and to register, maintain, lookup and remove to register, maintain, lookup and remove information on resources.
information on resources. Furthermore, new target attributes useful Furthermore, new target attributes useful in conjunction with an RD
in conjunction with an RD are defined. are defined.
Note to Readers Note to Readers
Discussion of this document takes place on the CORE Working Group Discussion of this document takes place on the CORE Working Group
mailing list (core@ietf.org), which is archived at mailing list (core@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/core/ https://mailarchive.ietf.org/arch/browse/core/
(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 Source for this draft and an issue tracker can be found at
https://github.com/core-wg/resource-directory (https://github.com/ https://github.com/core-wg/resource-directory (https://github.com/
skipping to change at page 2, line 12 skipping to change at page 2, line 15
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 10 September 2020. This Internet-Draft will expire on 14 January 2021.
Copyright Notice Copyright Notice
Copyright (c) 2020 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . . . . . . 7
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.1.2. Using DNS-SD to discover a resource directory . . . . 19 4.1.2. Using DNS-SD to discover a Resource Directory . . . . 19
4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 19 4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 19
4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19 4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19
5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 22 5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 22
5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26 5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26
5.2. Third-party registration . . . . . . . . . . . . . . . . 28 5.2. Third-party registration . . . . . . . . . . . . . . . . 29
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 . . . . . . . . . . . . . . . . . 30
5.3.2. Registration Removal . . . . . . . . . . . . . . . . 33 5.3.2. Registration Removal . . . . . . . . . . . . . . . . 33
5.3.3. Further operations . . . . . . . . . . . . . . . . . 33 5.3.3. Further operations . . . . . . . . . . . . . . . . . 34
6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 34 6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 35
6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 35 6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 35
6.3. Resource lookup examples . . . . . . . . . . . . . . . . 37 6.3. Resource lookup examples . . . . . . . . . . . . . . . . 37
6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 39 6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 40
7. Security policies . . . . . . . . . . . . . . . . . . . . . . 40 7. Security policies . . . . . . . . . . . . . . . . . . . . . . 41
7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 41 7.1. Endpoint name . . . . . . . . . . . . . . . . . . . . . . 42
7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 42 7.1.1. Random endpoint names . . . . . . . . . . . . . . . . 42
7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 42 7.2. Entered resources . . . . . . . . . . . . . . . . . . . . 42
8. Security Considerations . . . . . . . . . . . . . . . . . . . 42 7.3. Link confidentiality . . . . . . . . . . . . . . . . . . 43
8.1. Endpoint Identification and Authentication . . . . . . . 42 7.4. Segmentation . . . . . . . . . . . . . . . . . . . . . . 43
8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 43 8. Security Considerations . . . . . . . . . . . . . . . . . . . 44
8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 43 8.1. Endpoint Identification and Authentication . . . . . . . 44
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 45
9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 44 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 45
9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 44 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46
9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 44 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 46
9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 46
9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 46
9.3.1. Full description of the "Endpoint Type" Registration 9.3.1. Full description of the "Endpoint Type" Registration
Parameter . . . . . . . . . . . . . . . . . . . . . . 47 Parameter . . . . . . . . . . . . . . . . . . . . . . 49
9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 47 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 49
9.5. Multicast Address Registration . . . . . . . . . . . . . 48 9.5. Multicast Address Registration . . . . . . . . . . . . . 50
9.6. Well-Kown URIs . . . . . . . . . . . . . . . . . . . . . 48 9.6. Well-Known URIs . . . . . . . . . . . . . . . . . . . . . 50
9.7. Service Names and Transport Protocol Port Number 9.7. Service Names and Transport Protocol Port Number
Registry . . . . . . . . . . . . . . . . . . . . . . . . 48 Registry . . . . . . . . . . . . . . . . . . . . . . . . 50
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 49 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 51
10.1. Lighting Installation . . . . . . . . . . . . . . . . . 49 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 51
10.1.1. Installation Characteristics . . . . . . . . . . . . 49 10.1.1. Installation Characteristics . . . . . . . . . . . . 51
10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 50 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 52
10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 54 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 56
10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 54 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 56
10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 56 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 58
10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 57 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 59
10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 58 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 60
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 60
12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 58 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 60
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 71
13.1. Normative References . . . . . . . . . . . . . . . . . . 68 13.1. Normative References . . . . . . . . . . . . . . . . . . 71
13.2. Informative References . . . . . . . . . . . . . . . . . 69 13.2. Informative References . . . . . . . . . . . . . . . . . 72
Appendix A. Groups Registration and Lookup . . . . . . . . . . . 71 Appendix A. Groups Registration and Lookup . . . . . . . . . . . 75
Appendix B. Web links and the Resource Directory . . . . . . . . 73 Appendix B. Web links and the Resource Directory . . . . . . . . 76
B.1. A simple example . . . . . . . . . . . . . . . . . . . . 73 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 77
B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 74 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 77
B.1.2. Interpreting attributes and relations . . . . . . . . 74 B.1.2. Interpreting attributes and relations . . . . . . . . 78
B.2. A slightly more complex example . . . . . . . . . . . . . 74
B.3. Enter the Resource Directory . . . . . . . . . . . . . . 75
B.4. A note on differences between link-format and Link header
fields . . . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 78 B.2. A slightly more complex example . . . . . . . . . . . . . 78
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 79
B.4. A note on differences between link-format and Link header
fields . . . . . . . . . . . . . . . . . . . . . . . . . 80
Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 81
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82
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 4, line 33 skipping to change at page 4, line 37
servers is specified by the CoRE Link Format [RFC6690]. However, servers is specified by the CoRE Link Format [RFC6690]. However,
[RFC6690] only describes how to discover resources from the web [RFC6690] only describes how to discover resources from the web
server that hosts them by querying "/.well-known/core". In many server that hosts them by querying "/.well-known/core". In many
constrained scenarios, direct discovery of resources is not practical constrained scenarios, direct discovery of resources is not practical
due to sleeping nodes, disperse networks, or networks where multicast due to sleeping nodes, disperse networks, or networks where multicast
traffic is inefficient. These problems can be solved by employing an traffic is inefficient. These problems can be solved by employing an
entity called a Resource Directory (RD), which contains information entity called a Resource Directory (RD), which contains information
about resources held on other servers, allowing lookups to be about resources held on other servers, allowing lookups to be
performed for those resources. performed for those resources.
This document specifies the web interfaces that a Resource Directory This document specifies the web interfaces that an RD supports for
supports for web servers to discover the RD and to register, web servers to discover the RD and to register, maintain, lookup and
maintain, lookup and remove information on resources. Furthermore, remove information on resources. Furthermore, new target attributes
new target attributes useful in conjunction with a Resource Directory useful in conjunction with an RD are defined. Although the examples
are defined. Although the examples in this document show the use of in this document show the use of these interfaces with CoAP
these interfaces with CoAP [RFC7252], they can be applied in an [RFC7252], they can be applied in an equivalent manner to HTTP
equivalent manner to HTTP [RFC7230]. [RFC7230].
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in BCP
[RFC2119]. The term "byte" is used in its now customary sense as a 14 [RFC2119] [RFC8174] when, and only when, they appear in all
synonym for "octet". capitals, as shown here.
The term "byte" is used in its now customary sense as a synonym for
"octet".
This specification requires readers to be familiar with all the terms This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC3986], [RFC8288] and and concepts that are discussed in [RFC3986], [RFC8288] and
[RFC6690]. Readers should also be familiar with the terms and [RFC6690]. Readers should also be familiar with the terms and
concepts discussed in [RFC7252]. To describe the REST interfaces concepts discussed in [RFC7252]. To describe the REST interfaces
defined in this specification, the URI Template format is used defined in this specification, the URI Template format is used
[RFC6570]. [RFC6570].
This specification makes use of the following additional terminology: This specification makes use of the following additional terminology:
resolve against resolve against
The expression "a URI-reference is _resolved against_ a base URI" The expression "a URI-reference is _resolved against_ a base URI"
is used to describe the process of [RFC3986] Section 5.2. is used to describe the process of [RFC3986] Section 5.2.
Noteworthy corner cases are that if the URI-reference is a (full) Noteworthy corner cases are that if the URI-reference is a (full)
URI and resolved against any base URI, that gives the original URI and resolved against any base URI, that gives the original
full URI, and that resolving an empty URI reference gives the base full URI, and that resolving an empty URI reference gives the base
URI without any fragment identifier. URI without any fragment identifier.
Resource Directory Resource Directory (RD)
A web entity that stores information about web resources and A web entity that stores information about web resources and
implements the REST interfaces defined in this specification for implements the REST interfaces defined in this specification for
registration and lookup of those resources. discovery, for the creation, the maintenance and the removal of
registrations, and for lookup of the registered resources.
Sector Sector
In the context of a Resource Directory, a sector is a logical In the context of an RD, a sector is a logical grouping of
grouping of endpoints. endpoints.
The abbreviation "d=" is used for the sector in query parameters The abbreviation "d=" is used for the sector in query parameters
for compatibility with deployed implementations. for compatibility with deployed implementations.
Endpoint Endpoint
Endpoint (EP) is a term used to describe a web server or client in Endpoint (EP) is a term used to describe a web server or client in
[RFC7252]. In the context of this specification an endpoint is [RFC7252]. In the context of this specification an endpoint is
used to describe a web server that registers resources to the used to describe a web server that registers resources to the RD.
Resource Directory. An endpoint is identified by its endpoint An endpoint is identified by its endpoint name, which is included
name, which is included during registration, and has a unique name during registration, and has a unique name within the associated
within the associated sector of the registration. sector of the registration.
Registration Base URI Registration Base URI
The Base URI of a Registration is a URI that typically gives The Base URI of a Registration is a URI that typically gives
scheme and authority information about an Endpoint. The scheme and authority information about an Endpoint. The
Registration Base URI is provided at registration time, and is Registration Base URI is provided at registration time, and is
used by the Resource Directory to resolve relative references of used by the RD to resolve relative references of the registration
the registration into URIs. into URIs.
Target Target
The target of a link is the destination address (URI) of the link. The target of a link is the destination address (URI) of the link.
It is sometimes identified with "href=", or displayed as It is sometimes identified with "href=", or displayed as
"<target>". Relative targets need resolving with respect to the "<target>". Relative targets need resolving with respect to the
Base URI (section 5.2 of [RFC3986]). Base URI (section 5.2 of [RFC3986]).
This use of the term Target is consistent with [RFC8288]'s use of This use of the term Target is consistent with [RFC8288]'s use of
the term. the term.
Context Context
The context of a link is the source address (URI) of the link, and The context of a link is the source address (URI) of the link, and
describes which resource is linked to the target. A link's describes which resource is linked to the target. A link's
context is made explicit in serialized links as the "anchor=" context is made explicit in serialized links as the "anchor="
attribute. attribute.
This use of the term Context is consistent with [RFC8288]'s use of This use of the term Context is consistent with [RFC8288]'s use of
the term. the term.
Directory Resource Directory Resource
A resource in the Resource Directory (RD) containing registration A resource in the RD containing registration resources.
resources.
Registration Resource Registration Resource
A resource in the RD that contains information about an Endpoint A resource in the RD that contains information about an Endpoint
and its links. and its links.
Commissioning Tool Commissioning Tool
Commissioning Tool (CT) is a device that assists during the Commissioning Tool (CT) is a device that assists during the
installation of the network by assigning values to parameters, installation of the network by assigning values to parameters,
naming endpoints and groups, or adapting the installation to the naming endpoints and groups, or adapting the installation to the
needs of the applications. needs of the applications.
Registrant-ep Registrant-ep
Registrant-ep is the endpoint that is registered into the RD. The Registrant-ep is the endpoint that is registered into the RD. The
registrant-ep can register itself, or a CT registers the registrant-ep can register itself, or a CT registers the
registrant-ep. registrant-ep.
RDAO RDAO
Resource Directory Address Option. A new IPv6 Neighbor Discovery Resource Directory Address Option. A new IPv6 Neighbor Discovery
option defined for announcing a Resource Directory's address. option defined for announcing an RD's address.
3. Architecture and Use Cases 3. Architecture and Use Cases
3.1. Principles 3.1. Principles
The Resource Directory is primarily a tool to make discovery The RD is primarily a tool to make discovery operations more
operations more efficient than querying /.well-known/core on all efficient than querying /.well-known/core on all connected devices,
connected devices, or across boundaries that would be limiting those or across boundaries that would be limiting those operations.
operations.
It provides information about resources hosted by other devices that It provides information about resources hosted by other devices that
could otherwise only be obtained by directly querying the /.well- could otherwise only be obtained by directly querying the /.well-
known/core resource on these other devices, either by a unicast known/core resource on these other devices, either by a unicast
request or a multicast request. request or a multicast request.
Information SHOULD only be stored in the resource directory if it can Information SHOULD only be stored in the RD if it can be obtained by
be obtained by querying the described device's /.well-known/core querying the described device's /.well-known/core resource directly.
resource directly.
Data in the resource directory can only be provided by the device Data in the RD can only be provided by the device which hosts those
which hosts those data or a dedicated Commissioning Tool (CT). These data or a dedicated Commissioning Tool (CT). These CTs are thought
CTs are thought to act on behalf of endpoints too constrained, or to act on behalf of endpoints too constrained, or generally unable,
generally unable, to present that information themselves. No other to present that information themselves. No other client can modify
client can modify data in the resource directory. Changes to the data in the RD. Changes to the information in the RD do not
information in the Resource Directory do not propagate automatically propagate automatically back to the web servers from where the
back to the web servers from where the information originated. information originated.
3.2. Architecture 3.2. Architecture
The resource directory architecture is illustrated in Figure 1. A The RD architecture is illustrated in Figure 1. An RD is used as a
Resource Directory (RD) is used as a repository of registrations repository of registrations describing resources hosted on other web
describing resources hosted on other web servers, also called servers, also called endpoints (EP). An endpoint is a web server
endpoints (EP). An endpoint is a web server associated with a associated with a scheme, IP address and port. A physical node may
scheme, IP address and port. A physical node may host one or more host one or more endpoints. The RD implements a set of REST
endpoints. The RD implements a set of REST interfaces for endpoints interfaces for endpoints to register and maintain RD registrations,
to register and maintain resource directory registrations, and for and for endpoints to lookup resources from the RD. An RD can be
endpoints to lookup resources from the RD. An RD can be logically logically segmented by the use of Sectors.
segmented by the use of Sectors.
A mechanism to discover an RD using CoRE Link Format [RFC6690] is A mechanism to discover an RD using CoRE Link Format [RFC6690] is
defined. defined.
Registrations in the RD are soft state and need to be periodically Registrations in the RD are soft state and need to be periodically
refreshed. refreshed.
An endpoint uses specific interfaces to register, update and remove a An endpoint uses specific interfaces to register, update and remove a
registration. It is also possible for an RD to fetch Web Links from registration. It is also possible for an RD to fetch Web Links from
endpoints and add their contents to resource directory registrations. endpoints and add their contents to its registrations.
At the first registration of an endpoint, a "registration resource" At the first registration of an endpoint, a "registration resource"
is created, the location of which is returned to the registering is created, the location of which is returned to the registering
endpoint. The registering endpoint uses this registration resource endpoint. The registering endpoint uses this registration resource
to manage the contents of registrations. to manage the contents of registrations.
A lookup interface for discovering any of the Web Links stored in the A lookup interface for discovering any of the Web Links stored in the
RD is provided using the CoRE Link Format. RD is provided using the CoRE Link Format.
Registration Lookup Registration Lookup
skipping to change at page 8, line 19 skipping to change at page 8, line 22
+----+ ---- | | +----+ ---- | |
--|- +------+ | --|- +------+ |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
| EP | ---------|-----| RD |----|-----| Client | | EP | ---------|-----| RD |----|-----| Client |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
--|- +------+ | --|- +------+ |
+----+ ---- | | +----+ ---- | |
| CT |---- | | | CT |---- | |
+----+ +----+
Figure 1: The resource directory architecture. Figure 1: The RD 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
The Entity-Relationship (ER) models shown in Figure 2 and Figure 3 The Entity-Relationship (ER) models shown in Figure 2 and Figure 3
model the contents of /.well-known/core and the resource directory model the contents of /.well-known/core and the RD respectively, with
respectively, with entity-relationship diagrams [ER]. Entities entity-relationship diagrams [ER]. Entities (rectangles) are used
(rectangles) are used for concepts that exist independently. for concepts that exist independently. Attributes (ovals) are used
Attributes (ovals) are used for concepts that exist only in for concepts that exist only in connection with a related entity.
connection with a related entity. Relations (diamonds) give a Relations (diamonds) give a semantic meaning to the relation between
semantic meaning to the relation between entities. Numbers specify entities. Numbers specify the cardinality of the relations.
the cardinality of the relations.
Some of the attribute values are URIs. Those values are always full Some of the attribute values are URIs. Those values are always full
URIs and never relative references in the information model. They URIs and never relative references in the information model. They
can, however, be expressed as relative references in serializations, can, however, be expressed as relative references in serializations,
and often are. and often are.
These models provide an abstract view of the information expressed in These models provide an abstract view of the information expressed in
link-format documents and a Resource Directory. They cover the link-format documents and an RD. They cover the concepts, but not
concepts, but not necessarily all details of an RD's operation; they necessarily all details of an RD's operation; they are meant to give
are meant to give an overview, and not be a template for an overview, and not be a template for implementations.
implementations.
+----------------------+ +----------------------+
| /.well-known/core | | /.well-known/core |
+----------------------+ +----------------------+
| |
| 1 | 1
////////\\\\\\\ ////////\\\\\\\
< contains > < contains >
\\\\\\\\/////// \\\\\\\\///////
| |
skipping to change at page 9, line 32 skipping to change at page 9, line 32
oooooooooooo 0+ | oooooooooooo 0+ |
o target o--------+ o target o--------+
o attribute o | 0+ oooooo o attribute o | 0+ oooooo
oooooooooooo +-----o rel o oooooooooooo +-----o rel o
| oooooo | oooooo
| |
| 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: ER 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:
* 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
skipping to change at page 11, line 5 skipping to change at page 11, line 5
(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".
* 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 | + RD +
+----------------------+ +--------------+
| 1 | 1
| |
| |
| |
| |
//////\\\\ //////\\\\
< contains > < contains >
\\\\\///// \\\\\/////
| |
0+ | 0+ |
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: ER Model of the content of the RD
The model shown in Figure 3 models the contents of the resource The model shown in Figure 3 models the contents of the RD which
directory which contains in addition to /.well-known/core: contains in addition to /.well-known/core:
* 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:
* an endpoint name ("ep", a Unicode string) unique within a sector * an endpoint name ("ep", a Unicode string) unique within a sector
* 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)
skipping to change at page 13, line 8 skipping to change at page 13, line 8
focused on development of M2M solutions in order to expand the focused on development of M2M solutions in order to expand the
business to the new type of users: machines. The machines are business to the new type of users: machines. The machines are
connected directly to a mobile network using an appropriate embedded connected directly to a mobile network using an appropriate embedded
wireless interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing wireless interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing
short and wide range wireless interfaces. From the system design short and wide range wireless interfaces. From the system design
point of view, the ambition is to design horizontal solutions that point of view, the ambition is to design horizontal solutions that
can enable utilization of machines in different applications can enable utilization of machines in different applications
depending on their current availability and capabilities as well as depending on their current availability and capabilities as well as
application requirements, thus avoiding silo like solutions. One of application requirements, thus avoiding silo like solutions. One of
the crucial enablers of such design is the ability to discover the crucial enablers of such design is the ability to discover
resources (machines -- endpoints) capable of providing required resources (and thus the endpoints they are hosted on) capable of
information at a given time or acting on instructions from the end providing required information at a given time or acting on
users. instructions from the end users.
Imagine a scenario where endpoints installed on vehicles enable Imagine a scenario where endpoints installed on vehicles enable
tracking of the position of these vehicles for fleet management tracking of the position of these vehicles for fleet management
purposes and allow monitoring of environment parameters. During the purposes and allow monitoring of environment parameters. During the
boot-up process endpoints register with a Resource Directory, which boot-up process endpoints register with an RD, which is hosted by the
is hosted by the mobile operator or somewhere in the cloud. mobile operator or somewhere in the cloud. Periodically, these
Periodically, these endpoints update their registration and may endpoints update their registration and may modify resources they
modify resources they offer. offer.
When endpoints are not always connected, for example because they When endpoints are not always connected, for example because they
enter a sleep mode, a remote server is usually used to provide proxy enter a sleep mode, a remote server is usually used to provide proxy
access to the endpoints. Mobile apps or web applications for access to the endpoints. Mobile apps or web applications for
environment monitoring contact the RD, look up the endpoints capable environment monitoring contact the RD, look up the endpoints capable
of providing information about the environment using an appropriate of providing information about the environment using an appropriate
set of link parameters, obtain information on how to contact them set of link parameters, obtain information on how to contact them
(URLs of the proxy server), and then initiate interaction to obtain (URLs of the proxy server), and then initiate interaction to obtain
information that is finally processed, displayed on the screen and information that is finally processed, displayed on the screen and
usually stored in a database. Similarly, fleet management systems usually stored in a database. Similarly, fleet management systems
skipping to change at page 14, line 8 skipping to change at page 14, line 8
the nodes connected to the network can use the Internet services that the nodes connected to the network can use the Internet services that
are provided by the Internet Provider or the network administrator. are provided by the Internet Provider or the network administrator.
During the installation phase, the network is completely stand-alone, During the installation phase, the network is completely stand-alone,
no 6LBR is connected, and the network only supports the IP no 6LBR is connected, and the network only supports the IP
communication between the connected nodes. The installation phase is communication between the connected nodes. The installation phase is
usually followed by the operational phase. usually followed by the operational phase.
3.7. Use Case: Link Catalogues 3.7. Use Case: Link Catalogues
Resources may be shared through data brokers that have no knowledge Resources may be shared through data brokers that have no knowledge
beforehand of who is going to consume the data. Resource Directory beforehand of who is going to consume the data. An RD can be used to
can be used to hold links about resources and services hosted hold links about resources and services hosted anywhere to make them
anywhere to make them discoverable by a general class of discoverable by a general class of applications.
applications.
For example, environmental and weather sensors that generate data for For example, environmental and weather sensors that generate data for
public consumption may provide data to an intermediary server, or public consumption may provide data to an intermediary server, or
broker. Sensor data are published to the intermediary upon changes broker. Sensor data are published to the intermediary upon changes
or at regular intervals. Descriptions of the sensors that resolve to or at regular intervals. Descriptions of the sensors that resolve to
links to sensor data may be published to a Resource Directory. links to sensor data may be published to an RD. Applications wishing
Applications wishing to consume the data can use RD Lookup to to consume the data can use RD Lookup to discover and resolve links
discover and resolve links to the desired resources and endpoints. to the desired resources and endpoints. The RD service need not be
The Resource Directory service need not be coupled with the data coupled with the data intermediary service. Mapping of RDs 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 RDs. External
External catalogues that are represented in other formats may be catalogues that are represented in other formats may be converted to
converted to common web linking formats for storage and access by common web linking formats for storage and access by RDs. Since it
Resource Directories. Since it is common practice for these to be is common practice for these to be encoded in URNs [RFC8141], simple
encoded in URNs [RFC8141], simple and lossless structural transforms and lossless structural transforms should generally be sufficient to
should generally be sufficient to store external metadata in Resource store external metadata in RDs.
Directories.
The additional features of Resource Directory allow sectors to be The additional features of an RD allow sectors to be defined to
defined to enable access to a particular set of resources from enable access to a particular set of resources from particular
particular applications. This provides isolation and protection of applications. This provides isolation and protection of sensitive
sensitive data when needed. Application groups with multicast data when needed. Application groups with multicast addresses may be
addresses may be defined to support efficient data transport. defined to support efficient data transport.
4. RD discovery and other interface-independent components 4. RD discovery and other interface-independent components
This and the following sections define the required set of REST This and the following sections define the required set of REST
interfaces between a Resource Directory (RD), endpoints and lookup interfaces between an RD, endpoints and lookup clients. Although the
clients. Although the examples throughout these sections assume the examples throughout these sections assume the use of CoAP [RFC7252],
use of CoAP [RFC7252], these REST interfaces can also be realized these REST interfaces can also be realized using HTTP [RFC7230].
using HTTP [RFC7230]. Only multicast discovery operations are not Only multicast discovery operations are not possible on HTTP, and
possible on HTTP, and Simple Registration can not be executed as base Simple Registration can not be executed as base attribute (which is
attribute (which is mandatory for HTTP) can not be used there. In mandatory for HTTP) can not be used there. In all definitions in
all definitions in these sections, both CoAP response codes (with dot these sections, both CoAP response codes (with dot notation) and HTTP
notation) and HTTP response codes (without dot notation) are shown. response codes (without dot notation) are shown. An RD implementing
An RD implementing this specification MUST support the discovery, this specification MUST support the discovery, registration, update,
registration, update, lookup, and removal interfaces. lookup, and removal interfaces.
All operations on the contents of the Resource Directory MUST be All operations on the contents of the RD MUST be atomic and
atomic and idempotent. idempotent.
For several operations, interface templates are given in list form; For several operations, interface templates are given in list form;
those describe the operation participants, request codes, URIs, those describe the operation participants, request codes, URIs,
content formats and outcomes. Sections of those templates contain content formats and outcomes. Sections of those templates contain
normative content about Interaction, Method, URI Template and URI normative content about Interaction, Method, URI Template and URI
Template Variables as well as the details of the Success condition. Template Variables as well as the details of the Success condition.
The additional sections on options like Content-Format and on Failure The additional sections on options like Content-Format and on Failure
codes give typical cases that an implementation of the RD should deal codes give typical cases that an implementation of the RD should deal
with. Those serve to illustrate the typical responses to readers who with. Those serve to illustrate the typical responses to readers who
are not yet familiar with all the details of CoAP based interfaces; are not yet familiar with all the details of CoAP based interfaces;
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 and CTs during registration and
simple registrations) MUST be prepared to receive any unsuccessful maintenance, lookup clients, RD servers during simple registrations)
code and act upon it according to its definition, options and/or MUST be prepared to receive any unsuccessful code and act upon it
payload to the best of their capabilities, falling back to failing according to its definition, options and/or payload to the best of
the operation if recovery is not possible. In particular, they their capabilities, falling back to failing the operation if recovery
should retry the request upon 5.03 (Service Unavailable; 503 in HTTP) is not possible. In particular, they should retry the request upon
according to the Max-Age (Retry-After in HTTP) option, and fall back 5.03 (Service Unavailable; 503 in HTTP) according to the Max-Age
to link-format when receiving 4.15 (Unsupported Content-Format; 415 (Retry-After in HTTP) option, and fall back to link-format when
in HTTP). receiving 4.15 (Unsupported Content-Format; 415 in HTTP).
A resource directory MAY make the information submitted to it An RD MAY make the information submitted to it available to further
available to further directories, if it can ensure that a loop does directories, if it can ensure that a loop does not form. The
not form. The protocol used between directories to ensure loop-free protocol used between directories to ensure loop-free operation is
operation is outside the scope of this document. 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 RDs for discovery
directories for discovery purposes. Dependent on the operational purposes. Dependent on the operational conditions, one or more of
conditions, one or more of the techniques below apply. the techniques below apply.
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 RD:
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 3. It may be configured to use a service discovery mechanism such as
DNS-SD, as outlined in Section 4.1.2. 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 an RD, 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).
Finally, if neither the device nor the network offers any specific Finally, if neither the device nor the network offers any specific
configuration, the device may want to employ heuristics to find a configuration, the device may want to employ heuristics to find a
suitable resource directory. suitable RD.
The present specification does not fully define these heuristics, but The present specification does not fully define these heuristics, but
suggests a number of candidates: suggests a number of candidates:
1. In a 6LoWPAN, just assume the Border Router (6LBR) can act as a 1. In a 6LoWPAN, just assume the Border Router (6LBR) can act as an
resource directory (using the ABRO option to find that RD (using the ABRO option to find that [RFC6775]). Confirmation
[RFC6775]). Confirmation can be obtained by sending a Unicast to can be obtained by sending a Unicast to "coap://[6LBR]/.well-
"coap://[6LBR]/.well-known/core?rt=core.rd*". known/core?rt=core.rd*".
2. In a network that supports multicast well, discovering the RD 2. In a network that supports multicast well, discovering the RD
using a multicast query for /.well-known/core as specified in using a multicast query for /.well-known/core as specified in
CoRE Link Format [RFC6690]: Sending a Multicast GET to CoRE Link Format [RFC6690]: Sending a Multicast GET to
"coap://[MCD1]/.well-known/core?rt=core.rd*". RDs within the "coap://[MCD1]/.well-known/core?rt=core.rd*". RDs within the
multicast scope will answer the query. multicast scope will answer the query.
When answering a multicast request directed at a link-local address, When answering a multicast request directed at a link-local address,
the RD may want to respond from a routable address; this makes it the RD may want to respond from a routable address; this makes it
easier for registrants to use one of their own routable addresses for easier for registrants to use one of their own routable addresses for
skipping to change at page 17, line 26 skipping to change at page 17, line 33
recommended (e.g. installation phase described in Section 3.6). recommended (e.g. installation phase described in Section 3.6).
* In networks managed using DNS-SD, the use of DNS-SD for discovery * In networks managed using DNS-SD, the use of DNS-SD for discovery
as described in Section 4.1.2 is recommended. 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 RD. This
Directory (RD). This information is needed when endpoints cannot information is needed when endpoints cannot discover the RD with a
discover the Resource Directory with a link-local or realm-local link-local or realm-local scope multicast address, for instance
scope multicast address, for instance because the endpoint and the RD because the endpoint and the RD are separated by a Border Router
are separated by a Border Router (6LBR). In many circumstances the (6LBR). In many circumstances the availability of DHCP cannot be
availability of DHCP cannot be guaranteed either during commissioning guaranteed either during commissioning of the network. The presence
of the network. The presence and the use of the RD is essential and the use of the RD is essential during commissioning.
during commissioning.
It is possible to send multiple RDAO options in one message, It is possible to send multiple RDAO options in one message,
indicating as many resource directory addresses. indicating as many RD addresses.
The RDAO format is: The RDAO format is:
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length = 3 | Valid Lifetime | | Type | Length = 3 | Valid Lifetime |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reserved | | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
skipping to change at page 18, line 32 skipping to change at page 18, line 32
Type: TBD38 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 RD address is valid.
A value of all zero bits (0x0) indicates A value of all zero bits (0x0) indicates
that this Resource Directory address that this RD address
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 4.1.2. Using DNS-SD to discover a Resource Directory
A resource directory can advertise its presence in DNS-SD [RFC6763] An RD can advertise its presence in DNS-SD [RFC6763] using the
using the service name "_core-rd._udp" (for CoAP), "_core-rd- service name "_core-rd._udp" (for CoAP), "_core-rd-dtls._udp" (for
dtls._udp" (for CoAP over DTLS), "_core-rd._tcp" (for CoAP over TCP) CoAP over DTLS), "_core-rd._tcp" (for CoAP over TCP) or "_core-rd-
or "_core-rd-tls._tcp" (for CoAP over TLS) defined in this document. tls._tcp" (for CoAP over TLS) defined in this document. (For the
(For the WebSocket transports of CoAP, no service is defined as DNS- WebSocket transports of CoAP, no service is defined as DNS-SD is
SD is typically unavailable in environments where CoAP over typically unavailable in environments where CoAP over WebSockets is
WebSockets is used). used).
The selection of the service indicates the protocol used, and the SRV 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 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. point for the URI discovery steps of Section 4.3.
This section is a simplified concrete application of the more generic This section is a simplified concrete application of the more generic
mechanism specified in [I-D.ietf-core-rd-dns-sd]. 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 RDs implementing this specification MUST support the application/
support the application/link-format content format (ct=40). link-format content format (ct=40).
Resource Directories implementing this specification MAY support RDs implementing this specification MAY support additional content
additional content formats. formats.
Any additional content format supported by a Resource Directory Any additional content format supported by an RD implementing this
implementing this specification SHOULD be able to express all the specification SHOULD be able to express all the information
information expressible in link-format. It MAY be able to express expressible in link-format. It MAY be able to express information
information that is inexpressible in link-format, but those that is inexpressible in link-format, but those expressions SHOULD be
expressions SHOULD be avoided where possible. 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] after having known interface of the CoRE Link Format [RFC6690] after having
discovered a host as 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
skipping to change at page 20, line 9 skipping to change at page 20, line 9
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 An RD MAY provide hints about the content-formats it supports in the
supports in the links it exposes or registers, using the "ct" target links it exposes or registers, using the "ct" target attribute, as
attribute, as shown in the example below. Clients MAY use these shown in the example below. Clients MAY use these hints to select
hints to select alternate content-formats for interaction with the alternate content-formats for interaction with the RD.
Resource Directory.
HTTP does not support multicast and consequently only unicast HTTP does not support multicast and consequently only unicast
discovery can be supported at the using the HTTP "/.well-known/core" discovery can be supported at the using the HTTP "/.well-known/core"
resource. resource.
An implementation of this resource directory specification MUST RDs implementing this specification MUST support query filtering for
support query filtering for the rt parameter as defined in [RFC6690]. 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.
The URI Discovery operation can yield multiple URIs of a given The URI Discovery operation can yield multiple URIs of a given
resource type. The client of the RD can use any of the discovered resource type. The client of the RD can use any of the discovered
addresses initially. addresses initially.
skipping to change at page 21, line 18 skipping to change at page 21, line 16
interface, thus learning that the directory resource location, in interface, thus learning that the directory resource location, in
this example, is /rd, and that the content-format delivered by the this example, is /rd, and that the content-format delivered by the
server hosting the resource is application/link-format (ct=40). Note server hosting the resource is application/link-format (ct=40). Note
that it is up to the RD to choose its RD locations. that it is up to the RD to choose its RD locations.
Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* Req: GET coap://[MCD1]/.well-known/core?rt=core.rd*
Res: 2.05 Content Res: 2.05 Content
</rd>;rt="core.rd";ct=40, </rd>;rt="core.rd";ct=40,
</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 Figure 6: Example discovery exchange indicating additional
content-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.
skipping to change at page 26, line 17 skipping to change at page 26, line 17
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 An RD may optionally support HTTP. Here is an example of almost the
of almost the same registration operation above, when done using same registration operation above, when done using HTTP.
HTTP.
Req: Req:
POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1 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
</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"
skipping to change at page 27, line 25 skipping to change at page 27, line 25
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
* The Resource Directory queries the registrant-ep's discovery * The RD queries the registrant-ep's discovery resource to determine
resource to determine the success of the operation. It SHOULD the success of the operation. It SHOULD keep a cache of the
keep a cache of the discovery resource and not query it again as 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>
skipping to change at page 28, line 41 skipping to change at page 28, line 40
Interaction: RD -> EP Interaction: RD -> EP
Method: GET Method: GET
URI Template: /.well-known/core URI Template: /.well-known/core
The following response is expected on this interface: The following response is expected on this interface:
Success: 2.05 "Content". Success: 2.05 "Content".
When the RD is in a position to successfully execute this second
interaction and other network participants that can reach it are not,
it SHOULD verify that the apparent registrant-ep intends to register
with the given registration parameters before revealing the obtained
discovery information to lookup clients. An easy way to do that is
to verify the simple registration request's sender address using the
Echo option as described in [I-D.ietf-core-echo-request-tag]
Section 2.4.
The RD MUST delete registrations created by simple registration after The RD MUST delete registrations created by simple registration after
the expiration of their lifetime. Additional operations on the the expiration of their lifetime. Additional operations on the
registration resource cannot be executed because no registration registration resource cannot be executed because no registration
location is returned. location is returned.
5.2. Third-party registration 5.2. Third-party registration
For some applications, even Simple Registration may be too taxing for For some applications, even Simple Registration may be too taxing for
some very constrained devices, in particular if the security some very constrained devices, in particular if the security
requirements become too onerous. requirements become too onerous.
In a controlled environment (e.g. building control), the Resource In a controlled environment (e.g. building control), the RD can be
Directory can be filled by a third party device, called a filled by a third party device, called a Commissioning Tool (CT).
Commissioning Tool (CT). The commissioning tool can fill the The commissioning tool can fill the RD from a database or other
Resource Directory from a database or other means. For that purpose means. For that purpose scheme, IP address and port of the URI of
scheme, IP address and port of the URI of the registered device is the registered device is the value of the "base" parameter of the
the value of the "base" parameter of the registration described in registration described in Section 5.
Section 5.
It should be noted that the value of the "base" parameter applies to It should be noted that the value of the "base" parameter applies to
all the links of the registration and has consequences for the anchor all the links of the registration and has consequences for the anchor
value of the individual links as exemplified in Appendix B. An value of the individual links as exemplified in Appendix B. An
eventual (currently non-existing) "base" attribute of the link is not eventual (currently non-existing) "base" attribute of the link is not
affected by the value of "base" parameter in the registration. affected by the value of "base" parameter in the registration.
5.3. Operations on the Registration Resource 5.3. Operations on the Registration Resource
This section describes how the registering endpoint can maintain the This section describes how the registering endpoint can maintain the
registrations that it created. The registering endpoint can be the registrations that it created. The registering endpoint can be the
registrant-ep or the CT. An endpoint SHOULD NOT use this interface registrant-ep or the CT. The registrations are resources of the RD.
for registrations that it did not create. The registrations are
resources of the RD. An endpoint should not use this interface for registrations that it
did not create. This is usually enforced by security policies, which
in general require equivalent credentials for creation of and
operations on a registration.
After the initial registration, the registering endpoint retains the After the initial registration, the registering endpoint retains the
returned location of the Registration Resource for further returned location of the Registration Resource for further
operations, including refreshing the registration in order to extend operations, including refreshing the registration in order to extend
the lifetime and "keep-alive" the registration. When the lifetime of the lifetime and "keep-alive" the registration. When the lifetime of
the registration has expired, the RD SHOULD NOT respond to discovery the registration has expired, the RD SHOULD NOT respond to discovery
queries concerning this endpoint. The RD SHOULD continue to provide queries concerning this endpoint. The RD SHOULD continue to provide
access to the Registration Resource after a registration time-out access to the Registration Resource after a registration time-out
occurs in order to enable the registering endpoint to eventually occurs in order to enable the registering endpoint to eventually
refresh the registration. The RD MAY eventually remove the refresh the registration. The RD MAY eventually remove the
skipping to change at page 32, line 4 skipping to change at page 32, line 21
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:
* endpoint name (ep)=endpoint1 * endpoint name (ep)=endpoint1
* lifetime (lt)=500 * lifetime (lt)=500
* Base URI (base)=coap://local-proxy-old.example.com:5683 * Base URI (base)=coap://local-proxy-old.example.com:5683
* payload of Figure 8 * payload of Figure 8
The initial state of the Resource Directory is reflected in the The initial state of the RD is reflected in the following request:
following request:
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.05 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
skipping to change at page 32, line 44 skipping to change at page 33, line 13
The consecutive query returns: The consecutive query returns:
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.05 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
skipping to change at page 34, line 28 skipping to change at page 34, line 39
RD Lookup allows lookups for endpoints and resources using attributes RD Lookup allows lookups for endpoints and resources using attributes
defined in this document and for use with the CoRE Link Format. The defined in this document and for use with the CoRE Link Format. The
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
skipping to change at page 34, line 52 skipping to change at page 35, line 19
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
href or anchor was submitted as a (full) URI are returned with these href or anchor was submitted as a (full) URI are returned with these
attributes unmodified. attributes unmodified.
Above rules allow the client to interpret the response as links Above rules allow the client to interpret the response as links
without any further knowledge of the storage conventions of the RD. without any further knowledge of the storage conventions of the RD.
The Resource Directory MAY replace the registration base URIs with a The RD MAY replace the registration base URIs with a configured
configured intermediate proxy, e.g. in the case of an HTTP lookup intermediate proxy, e.g. in the case of an HTTP lookup interface for
interface for CoAP endpoints. CoAP endpoints.
If the base URI of a registration contains a link-local address, the If the base URI of a registration contains a link-local address, the
RD MUST NOT show its links unless the lookup was made from the same RD MUST NOT show its links unless the lookup was made from the same
link. The RD MUST NOT include zone identifiers in the resolved URIs. link. The RD MUST NOT include zone identifiers in the resolved URIs.
6.2. Lookup filtering 6.2. Lookup filtering
Using the Accept Option, the requester can control whether the Using the Accept Option, the requester can control whether the
returned list is returned in CoRE Link Format ("application/link- returned list is returned in CoRE Link Format ("application/link-
format", default) or in alternate content-formats (e.g. from format", default) or in alternate content-formats (e.g. from
skipping to change at page 35, line 28 skipping to change at page 35, line 44
The page and count parameters are used to obtain lookup results in The page and count parameters are used to obtain lookup results in
specified increments using pagination, where count specifies how many specified increments using pagination, where count specifies how many
links to return and page specifies which subset of links organized in links to return and page specifies which subset of links organized in
sequential pages, each containing 'count' links, starting with link sequential pages, each containing 'count' links, starting with link
zero and page zero. Thus, specifying count of 10 and page of 0 will zero and page zero. Thus, specifying count of 10 and page of 0 will
return the first 10 links in the result set (links 0-9). Count = 10 return the first 10 links in the result set (links 0-9). Count = 10
and page = 1 will return the next 'page' containing links 10-19, and and page = 1 will return the next 'page' containing links 10-19, and
so on. so on.
Multiple search criteria MAY be included in a lookup. All included Multiple search criteria MAY be included in a lookup. All included
criteria MUST match for a link to be returned. The Resource criteria MUST match for a link to be returned. The RD MUST support
Directory MUST support matching with multiple search criteria. matching with multiple search criteria.
A link matches a search criterion if it has an attribute of the same A link matches a search criterion if it has an attribute of the same
name and the same value, allowing for a trailing "*" wildcard name and the same value, allowing for a trailing "*" wildcard
operator as in Section 4.1 of [RFC6690]. Attributes that are defined operator as in Section 4.1 of [RFC6690]. Attributes that are defined
as "link-type" match if the search value matches any of their values as "link-type" match if the search value matches any of their values
(see Section 4.1 of [RFC6690]; e.g. "?if=core.s" matches ";if="abc (see Section 4.1 of [RFC6690]; e.g. "?if=core.s" matches ";if="abc
core.s";"). A resource link also matches a search criterion if its core.s";"). A resource link also matches a search criterion if its
endpoint would match the criterion, and vice versa, an endpoint link endpoint would match the criterion, and vice versa, an endpoint link
matches a search criterion if any of its resource links matches it. matches a search criterion if any of its resource links matches it.
skipping to change at page 36, line 34 skipping to change at page 37, line 5
URI Template: {+type-lookup-location}{?page,count,search*} URI Template: {+type-lookup-location}{?page,count,search*}
URI Template Variables: type-lookup-location := RD Lookup URI for a URI Template Variables: type-lookup-location := RD Lookup URI for a
given lookup type (mandatory). The address is discovered as given lookup type (mandatory). The address is discovered as
described in Section 4.3. described in Section 4.3.
search := Search criteria for limiting the search := Search criteria for limiting the
number of results (optional). number of results (optional).
The search criteria are an associative array, expressed in a
form-style query as per the URI template (see [RFC6570]
Sections 2.4.2 and 3.2.8)
page := Page (optional). Parameter cannot page := Page (optional). Parameter cannot
be used without the count parameter. Results are returned from be used without the count parameter. Results are returned from
result set in pages that contain 'count' links starting from result set in pages that contain 'count' links starting from
index (page * count). Page numbering starts with zero. index (page * count). Page numbering starts with zero.
count := Count (optional). Number of count := Count (optional). Number of
results is limited to this parameter value. If the page results is limited to this parameter value. If the page
parameter is also present, the response MUST only include parameter is also present, the response MUST only include
'count' links starting with the (page * count) link in the 'count' links starting with the (page * count) link in the
result set from the query. If the count parameter is not result set from the query. If the count parameter is not
skipping to change at page 40, line 7 skipping to change at page 41, line 9
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.
A Resource Directory can report endpoints in lookup that are not An RD can report endpoints in lookup that are not hosted at the same
hosted at the same address. Lookup clients MUST be prepared to see address. Lookup clients MUST be prepared to see arbitrary URIs as
arbitrary URIs as registration resources in the results and treat registration resources in the results and treat them as opaque
them as opaque identifiers; the precise semantics of such links are identifiers; the precise semantics of such links are left to future
left to future specifications. specifications.
The following example shows a client performing an endpoint type (et) The following example shows a client performing an endpoint type (et)
lookup with the value oic.d.sensor (which is currently a registered lookup with the value oic.d.sensor (which is currently a registered
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 security policies that are applicable to an RD strongly depend on
situated on a selection of nodes to discover endpoints on connected the application, and are not set out normatively here.
nodes. This section discusses different security aspects of
accessing the RD.
The contents of the RD are inserted in two ways: This section provides a list of aspects that applications should
consider when describing their use of the RD, without claiming to
cover all cases. It is using terminology of
[I-D.ietf-ace-oauth-authz], in which the RD acts as the Resource
Server (RS), and both registrant-eps and lookup clients act as
Clients (C) with support from an Authorization Server (AS), without
the intention of ruling out other (e.g. certificate / public-key
infrastructure (PKI) based) schemes.
1. The node hosting the discoverable endpoint fills the RD with the Any, all or none of the below can apply to an application. Which are
contents of /.well-known/core by: relevant depends on its protection objectives.
* Storing the contents directly into RD (see Section 5) 7.1. Endpoint name
* Requesting the RD to load the contents from /.well-known/core Whenever an RD needs to provide trustworthy results to clients doing
(see Section 5.1) endpoint lookup, or resource lookup with filtering on the endpoint
name, the RD must ensure that the registrant is authorized to use the
given endpoint name. This applies both to registration and later to
operations on the registration resource. It is immaterial there
whether the client is the registrant-ep itself or a CT is doing the
registration: The RD can not tell the difference, and CTs may use
authorization credentials authorizing only operations on that
particular endpoint name, or a wider range of endpoint names.
2. A Commissioning Tool (CT) fills the RD with endpoint information When certificates are used as authorization credentials, the
for a set of discoverable nodes. (see Section 5 with sector(s) and endpoint name(s) can be transported in the subject. In
base=authority parameter value) an ACE context, those are typically transported in a scope claim.
In both cases, the nodes filling the RD should be authenticated and 7.1.1. Random endpoint names
authorized to change the contents of the RD. An Authorization Server
(AS) is responsible to assign a token to the registering node to
authorize the node to discover or register endpoints in a given RD
[I-D.ietf-ace-oauth-authz].
It can be imagined that an installation is divided in a set of Conversely, in applications where the RD does not check the endpoint
security regions, each one with its own RD(s) to discover the name, the authorized registering endpoint can generate a random
endpoints that are part of a given security region. An endpoint that number (or string) that identifies the endpoint. The RD should then
wants to discover an RD, responsible for a given region, needs to be remember unique properties of the registrant, associate them with the
authorized to learn the contents of a given RD. Within a region, for registration for as long as its registration resource is active
a given RD, a more fine-grained security division is possible based (which may be longer than the registration's lifetime), and require
on the values of the endpoint registration parameters. Authorization the same properties for operations on the registration resource.
to discover endpoints with a given set of filter values is
recommended for those cases.
When a node registers its endpoints, criteria are needed to authorize Registrants that are prepared to pick a different identifier when
the node to enter them. An important aspect is the uniqueness of the their initial attempt at registration is unauthorized should pick an
(endpoint name, and optional sector) pair within the RD. Consider identifier at least twice as long as the expected number of
the two cases separately: (1) CT registers endpoints, and (2) the registrants; registrants without such a recovery options should pick
registering node registers its own endpoint(s). significantly longer endpoint names (e.g. using UUID URNs [RFC4122]).
* A CT needs authorization to register a set of endpoints. This 7.2. Entered resources
authorization can be based on the region, i.e. a given CT is
authorized to register any endpoint (endpoint name, sector) into a
given RD, or to register an endpoint with (endpoint name, sector)
value pairs assigned by the AS, or can be more fine-grained,
including a subset of registration parameter values.
* A given endpoint that registers itself, needs to proof its When lookup clients expect that certain types of links can only
possession of its unique (endpoint name, sector) value pair. originate from certain endpoints, then the RD needs to apply
Alternatively, the AS can authorize the endpoint to register with filtering to the links an endpoint may register.
an (endpoint name, sector) value pair assigned by the AS.
A separate document needs to specify these aspects to ensure For example, if clients use an RD to find a server that provides
interoperability between registering nodes and RD. The subsections firmware updates, then any registrant that wants to register (or
below give some hints how to handle a subset of the different update) links to firmware sources will need to provide suitable
aspects. credentials to do so, independently of its endpoint name.
7.1. Secure RD discovery Note that the impact of having undesirable links in the RD depends on
the application: if the client requires the firmware server to
present credentials as a firmware server, a fraudulent link's impact
is limited to the client revealing its intention to obtain updates
and slowing down the client until it finds a legitimate firmware
server; if the client accepts any credentials from the server as long
as they fit the provided URI, the impact is larger.
The Resource Server (RS) discussed in [I-D.ietf-ace-oauth-authz] is An RD may also require that only links are registered on whose anchor
equated to the RD. The client (C) needs to discover the RD as (or even target) the RD recognizes as authoritative of. One way to
discussed in Section 4.1. C can discover the related AS by sending a do this is to demand that the registrant present the same credentials
request to the RD. The RD denies the request by sending the address as a client that they'd need to present if contacted as a server at
of the related AS, as discussed in section 5.1 of the resources' URI, which may include using the address and port that
[I-D.ietf-ace-oauth-authz]. The client MUST send an authorization are part of the URI. Such a restriction places severe practical
request to the AS. When appropriate, the AS returns a token that limitations on the links that can be registered.
specifies the authorization permission which needs to be specified in
a separate document.
7.2. Secure RD filtering As above, the impact of undesirable links depends on the extent to
which the lookup client relies on the RD. To avoid the limitations,
RD applications should consider prescribe that lookup clients only
use the discovered information as hints, and describe which pieces of
information need to be verified with the server because they impact
the application's security.
The authorized parameter values for the queries by a given endpoint 7.3. Link confidentiality
must be registered by the AS. The AS communicates the parameter
values in the token. A separate document needs to specify the
parameter value combinations and their storage in the token. The RD
decodes the token and checks the validity of the queries of the
client.
7.3. Secure endpoint Name assignment When registrants publish information in the RD that is not available
to any client that would query the registrant's .well-known/core
interface, or when lookups to that interface are subject so stricter
firewalling than lookups to the RD, the RD may need to limit which
lookup clients may access the information.
This section only considers the assignment of a name to the endpoint In those situations, the registrant needs to be careful to
based on an automatic mechanism without use of AS. More elaborate authenticate the RD as well. The registrant needs to know in advance
protocols are out of scope. The registering endpoint is authorized which AS, audience and scope values indicate an RD it may trust for
by the AS to discover the RD and add registrations. A token is this purpose, and can not rely on the RD to provide AS address and
provided by the AS and communicated from registering endpoint to RD. token details. (In contrast, in the other scenarios it may try to
It is assumed that DTLS is used to secure the channel between register, and follow the pointers the RD gives it as to which
registering endpoint and RD, where the registering endpoint is the credentials it needs to provide in order to perform its
DTLS client. Assuming that the client is provided by a certificate registration).
at manufacturing time, the certificate is uniquely identified by the
CN field and the serial number (see [RFC5280] Section 4.1.2.2). The 7.4. Segmentation
RD can assign a unique endpoint name by using the certificate
identifier as endpoint name. Proof of possession of the endpoint Within a single RD, different security policies can apply.
name by the registering endpoint is checked by encrypting the
certificate identifier with the private key of the registering One example of this are multi-tenant deployments separated by the
endpoint, which the RD can decrypt with the public key stored in the sector (d) parameter. Some sectors might apply limitations on the
certificate. Even simpler, the authorized registering endpoint can endpoint names available, while others use a random identifier
generate a random number (or string) that identifies the endpoint. approach to endpoint names and place limits on the entered links
The RD can check for the improbable replication of the random value. based on their attributes instead.
The RD MUST check that registering endpoint uses only one random
value for each authorized endpoint. Care must be taken in such setups to determine the applicable access
control measures to each operation. One easy way to do that is to
mandate the use of the sector parameter on all operations, as no
credentials are suitable for operations across sector borders anyway.
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
An Endpoint (name, sector) pair is unique within the et of endpoints An Endpoint (name, sector) pair is unique within the set of endpoints
registered by the RD. An Endpoint MUST NOT be identified by its registered by the RD. An Endpoint MUST NOT be identified by its
protocol, port or IP address as these may change over the lifetime of protocol, port or IP address as these may change over the lifetime of
an Endpoint. an Endpoint.
Every operation performed by an Endpoint on a resource directory Every operation performed by an Endpoint on an RD SHOULD be mutually
SHOULD be mutually authenticated using Pre-Shared Key, Raw Public Key authenticated using Pre-Shared Key, Raw Public Key or Certificate
or Certificate based security. based security.
Consider the following threat: two devices A and B are registered at Consider the following threat: two devices A and B are registered at
a single server. Both devices have unique, per-device credentials a single server. Both devices have unique, per-device credentials
for use with DTLS to make sure that only parties with authorization for use with DTLS to make sure that only parties with authorization
to access A or B can do so. to access A or B can do so.
Now, imagine that a malicious device A wants to sabotage the device Now, imagine that a malicious device A wants to sabotage the device
B. It uses its credentials during the DTLS exchange. Then, it B. It uses its credentials during the DTLS exchange. Then, it
specifies the endpoint name of device B as the name of its own specifies the endpoint name of device B as the name of its own
endpoint in device A. If the server does not check whether the endpoint in device A. If the server does not check whether the
identifier provided in the DTLS handshake matches the identifier used identifier provided in the DTLS handshake matches the identifier used
at the CoAP layer then it may be inclined to use the endpoint name at the CoAP layer then it may be inclined to use the endpoint name
for looking up what information to provision to the malicious device. for looking up what information to provision to the malicious device.
Section 7.3 specifies an example that removes this threat for Endpoint authentication needs to be checked independently of whether
endpoints that have a certificate installed. there are configured requirements on the credentials for a given
endpoint name (Section 7.1) or whether arbitrary names are accepted
(Section 7.1.1).
Simple registration could be used to circumvent address based access
control: An attacker would send a simple registration request with
the victim's address as source address, and later look up the
victim's .well-known/core content in the RD. Mitigation for this is
recommended in Section 5.1.
8.2. Access Control 8.2. Access Control
Access control SHOULD be performed separately for the RD registration Access control SHOULD be performed separately for the RD registration
and Lookup API paths, as different endpoints may be authorized to and Lookup API paths, as different endpoints may be authorized to
register with an RD from those authorized to lookup endpoints from register with an RD from those authorized to lookup endpoints from
the RD. Such access control SHOULD be performed in as fine-grained a the RD. Such access control SHOULD be performed in as fine-grained a
level as possible. For example access control for lookups could be level as possible. For example access control for lookups could be
performed either at the sector, endpoint or resource level. performed either at the sector, endpoint or resource level.
skipping to change at page 43, line 49 skipping to change at page 45, line 35
source IP of the target entity and send requests to such a service source IP of the target entity and send requests to such a service
which would then respond to the target entity. This can be used for which would then respond to the target entity. This can be used for
large-scale DDoS attacks on the target. Especially, if the service large-scale DDoS attacks on the target. Especially, if the service
returns a response that is order of magnitudes larger than the returns a response that is order of magnitudes larger than the
request, the situation becomes even worse as now the attack can be request, the situation becomes even worse as now the attack can be
amplified. DNS servers have been widely used for DDoS amplification amplified. DNS servers have been widely used for DDoS amplification
attacks. There is also a danger that NTP Servers could become attacks. There is also a danger that NTP Servers could become
implicated in denial-of-service (DoS) attacks since they run on implicated in denial-of-service (DoS) attacks since they run on
unprotected UDP, there is no return routability check, and they can unprotected UDP, there is no return routability check, and they can
have a large amplification factor. The responses from the NTP server have a large amplification factor. The responses from the NTP server
were found to be 19 times larger than the request. A Resource were found to be 19 times larger than the request. An RD which
Directory (RD) which responds to wild-card lookups is potentially responds to wild-card lookups is potentially vulnerable if run with
vulnerable if run with CoAP over UDP. Since there is no return CoAP over UDP. Since there is no return routability check and the
routability check and the responses can be significantly larger than responses can be significantly larger than requests, RDs can
requests, RDs can unknowingly become part of a DDoS amplification unknowingly become part of a DDoS amplification attack.
attack.
[RFC7252] describes this at length in its Section 11.3, including
some mitigation by using small block sizes in responses. The
upcoming [I-D.ietf-core-echo-request-tag] updates that by describing
a source address verification mechanism using the Echo option.
[ If this document is published together with or after I-D.ietf-core-
echo-request-tag, the above paragraph is replaced with the following:
[RFC7252] describes this at length in its Section 11.3, and
[I-D.ietf-core-echo-request-tag] (which updates the former)
recommends using the Echo option to verify the request's source
address.
]
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 RD | RFCTHIS | | core.rd | Directory resource of an RD | RFCTHIS |
| | | Section 4.3 | | | | Section 4.3 |
+--------------------+-----------------------------+-------------+ +--------------------+-----------------------------+-------------+
| core.rd-lookup-res | Resource lookup of an RD | RFCTHIS | | core.rd-lookup-res | Resource lookup of an RD | RFCTHIS |
| | | Section 4.3 | | | | Section 4.3 |
+--------------------+-----------------------------+-------------+ +--------------------+-----------------------------+-------------+
| core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS | | core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS |
| | | Section 4.3 | | | | Section 4.3 |
skipping to change at page 45, line 12 skipping to change at page 47, line 12
Each entry in the registry must include Each entry in the registry must include
* the human readable name of the parameter, * the human readable name of the parameter,
* the short name as used in query parameters or target attributes, * the short name as used in query parameters or target attributes,
* 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,
* validity requirements if any, * syntax and validity requirements if any,
* a description, * a description,
* and a link to reference documentation. * 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.
skipping to change at page 46, line 5 skipping to change at page 48, line 5
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 | ep | Unicode* | RLA | Name of the |
| Name | | | | endpoint | | Name | | | | endpoint |
+--------------+-------+--------------+-----+---------------------+ +--------------+-------+--------------+-----+---------------------+
| Lifetime | lt | 1-4294967295 | R | Lifetime of the | | Lifetime | lt | 1-4294967295 | R | Lifetime of the |
| | | | | registration in | | | | | | registration in |
| | | | | seconds | | | | | | seconds |
+--------------+-------+--------------+-----+---------------------+ +--------------+-------+--------------+-----+---------------------+
| Sector | d | Unicode* | RLA | Sector to which | | Sector | d | Unicode* | RLA | Sector to which |
skipping to change at page 47, line 8 skipping to change at page 49, line 8
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
registration if it were not to be used in lookup or attributes, but registration if it were not to be used in lookup or attributes, but
would make a bad parameter for lookup, because a resource lookup with would make a bad parameter for lookup, because a resource lookup with
an "if" query parameter could ambiguously filter by the registered an "if" query parameter could ambiguously filter by the registered
endpoint property or the [RFC6690] target attribute). It is expected endpoint property or the [RFC6690] target attribute).
that the registry will receive between 5 and 50 registrations in
total over the next years.
9.3.1. Full description of the "Endpoint Type" Registration Parameter 9.3.1. Full description of the "Endpoint Type" Registration Parameter
An endpoint registering at an RD can describe itself with endpoint An endpoint registering at an RD can describe itself with endpoint
types, similar to how resources are described with Resource Types in types, similar to how resources are described with Resource Types in
[RFC6690]. An endpoint type is expressed as a string, which can be [RFC6690]. An endpoint type is expressed as a string, which can be
either a URI or one of the values defined in the Endpoint Type sub- either a URI or one of the values defined in the Endpoint Type sub-
registry. Endpoint types can be passed in the "et" query parameter registry. Endpoint types can be passed in the "et" query parameter
as part of extra-attrs at the Registration step, are shown on as part of extra-attrs at the Registration step, are shown on
endpoint lookups using the "et" target attribute, and can be filtered endpoint lookups using the "et" target attribute, and can be filtered
for using "et" as a search criterion in resource and endpoint lookup. for using "et" as a search criterion in resource and endpoint lookup.
Multiple endpoint types are given as separate query parameters or Multiple endpoint types are given as separate query parameters or
link attributes. link attributes.
Note that Endpoint Type differs from Resource Type in that it uses Note that Endpoint Type differs from Resource Type in that it uses
multiple attributes rather than space separated values. As a result, multiple attributes rather than space separated values. As a result,
Resource Directory implementations automatically support correct RDs implementing this specification automatically support correct
filtering in the lookup interfaces from the rules for unknown filtering in the lookup interfaces from the rules for unknown
endpoint attributes. endpoint attributes.
9.4. "Endpoint Type" (et=) RD Parameter values 9.4. "Endpoint Type" (et=) RD Parameter values
This specification establishes a new sub-registry under "CoRE This specification establishes a new sub-registry under "CoRE
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:
skipping to change at page 48, line 14 skipping to change at page 50, line 12
The registry initially contains one value: The registry initially contains one value:
* "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)
RFC 5771). [RFC5771].
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 9.6. Well-Known URIs
IANA is asked to extend the reference for the "core" URI suffix in IANA is asked to extend the reference for the "core" URI suffix in
the "Well-Known URIs" registry to reference this document next to the "Well-Known URIs" registry to reference this document next to
[RFC6690], as this defines the resource's behavior for POST requests. [RFC6690], as this defines the resource's behavior for POST requests.
9.7. Service Names and Transport Protocol Port Number Registry 9.7. Service Names and Transport Protocol Port Number Registry
IANA is asked to enter four new items into the Service Names and IANA is asked to enter four new items into the Service Names and
Transport Protocol Port Number Registry: Transport Protocol Port Number Registry:
* Service name: "core-rd", Protocol: "udp", Description: "Resource * Service name: "core-rd", Protocol: "udp", Description: "Resource
Directory accessed using CoAP" Directory accessed using CoAP"
* Service name "core-rd-dtls", Protocol: "udp", Description: * Service name "core-rd-dtls", Protocol: "udp", Description:
"Resource Directory accedded using CoAP over DTLS" "Resource Directory accessed using CoAP over DTLS"
* Service name: "core-rd", Protocol: "tcp", Description: "Resource * Service name: "core-rd", Protocol: "tcp", Description: "Resource
Directory accessed using CoAP over TCP" Directory accessed using CoAP over TCP"
* Service name "core-rd-tls", Protocol: "tcp", Description: * Service name "core-rd-tls", Protocol: "tcp", Description:
"Resource Directory accedded using CoAP over TLS" "Resource Directory accessed using CoAP over TLS"
All in common have this document as their reference. 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 RD with a CoAP interface to facilitate the installation and
the installation and start-up of the application code in the lights start-up of the application code in the lights and sensors. In
and sensors. In particular, the example leads to the definition of a particular, the example leads to the definition of a group and the
group and the enabling of the corresponding multicast address as enabling of the corresponding multicast address as described in
described in Appendix A. No conclusions must be drawn on the Appendix A. No conclusions must be drawn on the realization of
realization of actual installation or naming procedures, because the actual installation or naming procedures, because the example only
example only "emphasizes" some of the issues that may influence the "emphasizes" some of the issues that may influence the use of the RD
use of the RD and does not pretend to be normative. and does not pretend to be normative.
10.1.1. Installation Characteristics 10.1.1. Installation Characteristics
The example assumes that the installation is managed. That means The example assumes that the installation is managed. That means
that a Commissioning Tool (CT) is used to authorize the addition of that a Commissioning Tool (CT) is used to authorize the addition of
nodes, name them, and name their services. The CT can be connected nodes, name them, and name their services. The CT can be connected
to the installation in many ways: the CT can be part of the to the installation in many ways: the CT can be part of the
installation network, connected by WiFi to the installation network, installation network, connected by WiFi to the installation network,
or connected via GPRS link, or other method. or connected via GPRS link, or other method.
skipping to change at page 50, line 12 skipping to change at page 52, line 10
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 4 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 | | RD | 2001:db8:4::ff |
+--------------------+----------------+ +-----------------+----------------+
Table 4: 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 RD 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 5 identifiers relevant to the RD 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/middle | light |
+-----------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
| luminary1 | lm_R2-4-015_wndw | /light/right | light | | luminary1 | lm_R2-4-015_wndw | /light/right | light |
+-----------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
| luminary2 | lm_R2-4-015_door | /light/left | light | | luminary2 | lm_R2-4-015_door | /light/left | light |
+-----------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
| luminary2 | lm_R2-4-015_door | /light/middle | light | | luminary2 | lm_R2-4-015_door | /light/middle | light |
+-----------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
| luminary2 | lm_R2-4-015_door | /light/right | light | | luminary2 | lm_R2-4-015_door | /light/right | light |
+-----------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
| Presence | ps_R2-4-015_door | /ps | p-sensor | | Presence | ps_R2-4-015_door | /ps | p-sensor |
| sensor | | | | | sensor | | | |
+-----------+------------------+---------------+---------------+ +-----------+------------------+---------------+---------------+
Table 5: Resource Directory identifiers Table 5: RD 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 54, line 15 skipping to change at page 56, line 15
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
This example shows how the OMA LWM2M specification makes use of This example shows how the OMA LWM2M specification makes use of RDs.
Resource Directory (RD).
OMA LWM2M is a profile for device services based on CoAP(OMA Name OMA LWM2M is a profile for device services based on CoAP(OMA Name
Authority). LWM2M defines a simple object model and a number of Authority). LWM2M defines a simple object model and a number of
abstract interfaces and operations for device management and device abstract interfaces and operations for device management and device
service enablement. service enablement.
An LWM2M server is an instance of an LWM2M middleware service layer, An LWM2M server is an instance of an LWM2M middleware service layer,
containing a Resource Directory along with other LWM2M interfaces containing an RD along with other LWM2M interfaces defined by the
defined by the LWM2M specification. LWM2M specification.
CoRE Resource Directory (RD) is used to provide the LWM2M The registration interface of this specification is used to provide
Registration interface. the LWM2M Registration interface.
LWM2M does not provide for registration sectors and does not LWM2M does not provide for registration sectors and does not
currently use the rd-lookup interface. currently use the rd-lookup interface.
The LWM2M specification describes a set of interfaces and a resource The LWM2M specification describes a set of interfaces and a resource
model used between a LWM2M device and an LWM2M server. Other model used between a LWM2M device and an LWM2M server. Other
interfaces, proxies, and applications are currently out of scope for interfaces, proxies, and applications are currently out of scope for
LWM2M. LWM2M.
The location of the LWM2M Server and RD URI path is provided by the The location of the LWM2M Server and RD URI path is provided by the
skipping to change at page 55, line 48 skipping to change at page 58, line 4
(0-65535) or "undefined" to refer to all resources within an instance (0-65535) or "undefined" to refer to all resources within an instance
resource-instance := Resource instance identifier or "undefined" to resource-instance := Resource instance identifier or "undefined" to
refer to single instance of a resource refer to single instance of a resource
LWM2M IDs are 16 bit unsigned integers represented in decimal (no LWM2M IDs are 16 bit unsigned integers represented in decimal (no
leading zeroes except for the value 0) by URI format strings. For leading zeroes except for the value 0) by URI format strings. For
example, a LWM2M URI might be: example, a LWM2M URI might be:
/1/0/1 /1/0/1
The base URI is empty, the Object ID is 1, the instance ID is 0, the
The base uri is empty, the Object ID is 1, the instance ID is 0, the
resource ID is 1, and the resource instance is "undefined". This resource ID is 1, and the resource instance is "undefined". This
example URI points to internal resource 1, which represents the example URI points to internal resource 1, which represents the
registration lifetime configured, in instance 0 of a type 1 object registration lifetime configured, in instance 0 of a type 1 object
(LWM2M Server Object). (LWM2M Server Object).
10.2.2. LWM2M Register Endpoint 10.2.2. LWM2M Register Endpoint
LWM2M defines a registration interface based on the REST API, LWM2M defines a registration interface based on the REST API,
described in Section 5. The RD registration URI path of the LWM2M described in Section 5. The RD registration URI path of the LWM2M RD
Resource Directory is specified to be "/rd". is specified to be "/rd".
LWM2M endpoints register object IDs, for example </1>, to indicate LWM2M endpoints register object IDs, for example </1>, to indicate
that a particular object type is supported, and register object that a particular object type is supported, and register object
instances, for example </1/0>, to indicate that a particular instance instances, for example </1/0>, to indicate that a particular instance
of that object type exists. of that object type exists.
Resources within the LWM2M object instance are not registered with Resources within the LWM2M object instance are not registered with
the RD, but may be discovered by reading the resource links from the the RD, but may be discovered by reading the resource links from the
object instance using GET with a CoAP Content-Format of application/ object instance using GET with a CoAP Content-Format of application/
link-format. Resources may also be read as a structured object by link-format. Resources may also be read as a structured object by
skipping to change at page 57, line 5 skipping to change at page 59, line 5
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 | | LWM2M | ver | 1.0 | Spec |
| Version | | | Version | | Version | | | Version |
+---------+-------+-------------------------------+-------------+ +---------+-------+-------------------------------+-------------+
+---------+-------+-------------------------------+-------------+ +---------+-------+-------------------------------+-------------+
skipping to change at page 58, line 28 skipping to change at page 60, line 28
registration proceeds as described in Section 5.3.2. registration proceeds as described in Section 5.3.2.
11. Acknowledgments 11. Acknowledgments
Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders
Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen,
Hannes Tschofenig, Sampo Ukkola, Linyi Tian, 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 RD concepts were originally developed.
developed.
12. Changelog 12. Changelog
changes from -24 to -25
* Large rework of section 7 (Security policies)
Rather than prescribing which data in the RD _is_ authenticated
(and how), it now describes what applications built on an RD _can_
choose to authenticate, show possibilities on how to do it and
outline what it means for clients.
This addresses Russ' Genart review points on details in the text
in a rather broad fashion. That is because the discussion on the
topic inside the WG showed that that text on security has been
driven more review-by-review than by an architectural plan of the
authors and WG.
* Add concrete suggestions (twice as long as registrant number with
retries, or UUIDs without) for random endpoint names
* Point out that simple registration can have faked origins,
RECOMMEND mitigation when applicable and suggest the Echo
mechanism to implement it.
* Reference existing and upcoming specifications for DDOS mitigation
in CoAP.
* Explain the provenance of the example's multicast address.
* Make "SHOULD" of not manipulating foreign registrations a "should"
and explain how it is enforced
* Clarify application of RFC6570 to search parameters
* Syntactic fixes in examples
* IANA:
- Don't announce expected number of registrations (goes to write-
up)
- Include syntax as part of a field's validity in entry
requirements
* Editorial changes
- Align wording between abstract and introduction
- Abbreviation normalization: "ER model", "RD"
- RFC8174 boilerplate update
- Minor clarity fixes
- Markup and layouting
changes from -23 to -24 changes from -23 to -24
* Discovery using DNS-SD added again * Discovery using DNS-SD added again
* Minimum lifetime (lt) reduced from 60 to 1 * Minimum lifetime (lt) reduced from 60 to 1
* References added * References added
* IANA considerations * IANA considerations
skipping to change at page 69, line 16 skipping to change at page 72, line 18
[RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013,
<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>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
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
unified view of data", DOI 10.1145/320434.320440, ACM view of data", DOI 10.1145/320434.320440, ACM Transactions
Transactions on Database Systems Vol. 1, pp. 9-36, March on Database Systems Vol. 1, pp. 9-36, March 1976,
1976, <https://doi.org/10.1145/320434.320440>. <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", Work in Progress, disclosing implementation information", Work in Progress,
Internet-Draft, draft-bormann-t2trg-rel-impl-00, 28 Internet-Draft, draft-bormann-t2trg-rel-impl-01, 27 March
January 2018, <http://www.ietf.org/internet-drafts/draft- 2020, <http://www.ietf.org/internet-drafts/draft-bormann-
bormann-t2trg-rel-impl-00.txt>. t2trg-rel-impl-01.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)", Work in Progress, Internet-Draft, draft-hartke- (CoRAL)", Work in Progress, Internet-Draft, draft-hartke-
t2trg-coral-09, 8 July 2019, <http://www.ietf.org/ t2trg-coral-09, 8 July 2019, <http://www.ietf.org/
internet-drafts/draft-hartke-t2trg-coral-09.txt>. 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)", Work in Progress, Internet-Draft, Framework (ACE-OAuth)", Work in Progress, Internet-Draft,
draft-ietf-ace-oauth-authz-33, 6 February 2020, draft-ietf-ace-oauth-authz-35, 24 June 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-ace-oauth- <http://www.ietf.org/internet-drafts/draft-ietf-ace-oauth-
authz-33.txt>. authz-35.txt>.
[I-D.ietf-core-echo-request-tag]
Amsuess, C., Mattsson, J., and G. Selander, "CoAP: Echo,
Request-Tag, and Token Processing", Work in Progress,
Internet-Draft, draft-ietf-core-echo-request-tag-09, 9
March 2020, <http://www.ietf.org/internet-drafts/draft-
ietf-core-echo-request-tag-09.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", Work in Progress, Internet-Draft, draft- JSON and CBOR", Work in Progress, Internet-Draft, draft-
ietf-core-links-json-10, 26 February 2018, ietf-core-links-json-10, 26 February 2018,
<http://www.ietf.org/internet-drafts/draft-ietf-core- <http://www.ietf.org/internet-drafts/draft-ietf-core-
links-json-10.txt>. links-json-10.txt>.
[I-D.ietf-core-rd-dns-sd] [I-D.ietf-core-rd-dns-sd]
skipping to change at page 70, line 19 skipping to change at page 73, line 34
<http://www.ietf.org/internet-drafts/draft-ietf-core-rd- <http://www.ietf.org/internet-drafts/draft-ietf-core-rd-
dns-sd-05.txt>. 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",
Work in Progress, Internet-Draft, draft-silverajan-core- Work in Progress, Internet-Draft, draft-silverajan-core-
coap-protocol-negotiation-09, 2 July 2018, coap-protocol-negotiation-09, 2 July 2018,
<http://www.ietf.org/internet-drafts/draft-silverajan- <http://www.ietf.org/internet-drafts/draft-silverajan-
core-coap-protocol-negotiation-09.txt>. core-coap-protocol-negotiation-09.txt>.
[RFC3306] Haberman, B. and D. Thaler, "Unicast-Prefix-based IPv6
Multicast Addresses", RFC 3306, DOI 10.17487/RFC3306,
August 2002, <https://www.rfc-editor.org/info/rfc3306>.
[RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix
Reserved for Documentation", RFC 3849,
DOI 10.17487/RFC3849, July 2004,
<https://www.rfc-editor.org/info/rfc3849>.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122,
DOI 10.17487/RFC4122, July 2005,
<https://www.rfc-editor.org/info/rfc4122>.
[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., [RFC5771] Cotton, M., Vegoda, L., and D. Meyer, "IANA Guidelines for
Housley, R., and W. Polk, "Internet X.509 Public Key IPv4 Multicast Address Assignments", BCP 51, RFC 5771,
Infrastructure Certificate and Certificate Revocation List DOI 10.17487/RFC5771, March 2010,
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, <https://www.rfc-editor.org/info/rfc5771>.
<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,
skipping to change at page 71, line 33 skipping to change at page 75, line 16
(URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
<https://www.rfc-editor.org/info/rfc8141>. <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 an RD.
Groups are represented by endpoint registrations. Their base address Groups are represented by endpoint registrations. Their base address
is a multicast address, and they SHOULD be entered with the endpoint is a multicast address, and they SHOULD be entered with the endpoint
type "core.rd-group". The endpoint name can also be referred to as a type "core.rd-group". The endpoint name can also be referred to as a
group name in this context. group name in this context.
The registration is inserted into the RD by a Commissioning Tool, The registration is inserted into the RD by a Commissioning Tool,
which might also be known as a group manager here. It performs third which might also be known as a group manager here. It performs third
party registration and registration updates. party registration and registration updates.
The links it registers SHOULD be available on all members that join The links it registers SHOULD be available on all members that join
the group. Depending on the application, members that lack some the group. Depending on the application, members that lack some
resource MAY be permissible if requests to them fail gracefully. resource MAY be permissible if requests to them fail gracefully.
The following example shows a CT registering a group with the name The following example shows a CT registering a group with the name
"lights" which provides two resources. The directory resource path "lights" which provides two resources. The directory resource path
/rd is an example RD location discovered in a request similar to /rd is an example RD location discovered in a request similar to
Figure 5. Figure 5. The group address in the example is constructed from
[RFC3849]'s reserved 2001:db8:: prefix as a unicast-prefix based
site-local address (see [RFC3306].
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
skipping to change at page 75, line 31 skipping to change at page 79, line 11
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"".
Following the same resolution steps, the fourth record can be read as Following the same resolution steps, the fourth record can be read as
""coap://[2001:db8:f0::1]/sensors/temp" is described by ""coap://[2001:db8:f0::1]/sensors/temp" is described by
"http://www.example.com/sensors/t123"". "http://www.example.com/sensors/t123"".
B.3. Enter the Resource Directory B.3. Enter the Resource Directory
The resource directory tries to carry the semantics obtainable by The RD tries to carry the semantics obtainable by classical CoAP
classical CoAP discovery over to the resource lookup interface as discovery over to the resource lookup interface as faithfully as
faithfully as possible. possible.
For the following queries, we will assume that the simple host has For the following queries, we will assume that the simple host has
used Simple Registration to register at the resource directory that used Simple Registration to register at the RD that was announced to
was announced to it, sending this request from its UDP port it, sending this request from its UDP port "[2001:db8:f0::1]:6553":
"[2001:db8:f0::1]:6553":
POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1 POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1
Figure 32: Example request starting a simple registration Figure 32: Example request starting a simple registration
The resource directory would have accepted the registration, and The RD would have accepted the registration, and queried the simple
queried the simple host's ".well-known/core" by itself. As a result, host's ".well-known/core" by itself. As a result, the host is
the host is registered as an endpoint in the RD with the name registered as an endpoint in the RD with the name "simple-host1".
"simple-host1". The registration is active for 90000 seconds, and The registration is active for 90000 seconds, and the endpoint
the endpoint registration Base URI is ""coap://[2001:db8:f0::1]"" registration Base URI is ""coap://[2001:db8:f0::1]"" following the
following the resolution steps described in Appendix B.1.1. It resolution steps described in Appendix B.1.1. It should be remarked
should be remarked that the Base URI constructed that way always that the Base URI constructed that way always yields a URI of the
yields a URI of the form: scheme://authority without path suffix. form: scheme://authority without path suffix.
If the client now queries the RD as it would previously have issued a If the client now queries the RD as it would previously have issued a
multicast request, it would go through the RD discovery steps by multicast request, it would go through the RD discovery steps by
fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd-
lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the
resource lookup endpoint, and issue a request to resource lookup endpoint, and issue a request to
"coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive "coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive
the following data: the following data:
<coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0; <coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0;
skipping to change at page 78, line 18 skipping to change at page 81, line 44
</temperature/Malmö>;rel="live-environment-data" </temperature/Malmö>;rel="live-environment-data"
Parsers and producers of link-format and header fields 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 an RD (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
Limited Link Format. The rules herein are not very limiting in Limited Link Format. The rules herein are not very limiting in
practice - all examples in RFC6690, and all deployments the authors practice - all examples in RFC6690, and all deployments the authors
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. RD 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:
* 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
 End of changes. 141 change blocks. 
439 lines changed or deleted 551 lines changed or added

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