draft-ietf-core-resource-directory-21.txt   draft-ietf-core-resource-directory-22.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: December 15, 2019 SmartThings Expires: January 3, 2020 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
C. Amsuess, Ed. C. Amsuess, Ed.
June 13, 2019 July 02, 2019
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-21 draft-ietf-core-resource-directory-22
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
skipping to change at page 1, line 47 skipping to change at page 1, line 47
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 15, 2019. This Internet-Draft will expire on January 3, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 40 skipping to change at page 2, line 40
3.6. Use Case: Home and Building Automation . . . . . . . . . 13 3.6. Use Case: Home and Building Automation . . . . . . . . . 13
3.7. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 14 3.7. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 14
4. RD discovery and other interface-independent components . . . 14 4. RD discovery and other interface-independent components . . . 14
4.1. Finding a Resource Directory . . . . . . . . . . . . . . 15 4.1. Finding a Resource Directory . . . . . . . . . . . . . . 15
4.1.1. Resource Directory Address Option (RDAO) . . . . . . 17 4.1.1. Resource Directory Address Option (RDAO) . . . . . . 17
4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 18 4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 18
4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19 4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19
5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 21 5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 21
5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26 5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26
5.2. Third-party registration . . . . . . . . . . . . . . . . 28 5.2. Third-party registration . . . . . . . . . . . . . . . . 28
5.3. Operations on the Registration Resource . . . . . . . . . 28 5.3. Operations on the Registration Resource . . . . . . . . . 29
5.3.1. Registration Update . . . . . . . . . . . . . . . . . 29 5.3.1. Registration Update . . . . . . . . . . . . . . . . . 29
5.3.2. Registration Removal . . . . . . . . . . . . . . . . 32 5.3.2. Registration Removal . . . . . . . . . . . . . . . . 32
5.3.3. Further operations . . . . . . . . . . . . . . . . . 32 5.3.3. Further operations . . . . . . . . . . . . . . . . . 33
6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 33 6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 34
6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 34 6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 34
6.3. Resource lookup examples . . . . . . . . . . . . . . . . 36 6.3. Resource lookup examples . . . . . . . . . . . . . . . . 36
6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 38 6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 39
7. Security policies . . . . . . . . . . . . . . . . . . . . . . 39 7. Security policies . . . . . . . . . . . . . . . . . . . . . . 40
7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 40 7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 41
7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 40 7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 42
7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 41 7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 42
8. Security Considerations . . . . . . . . . . . . . . . . . . . 41 8. Security Considerations . . . . . . . . . . . . . . . . . . . 42
8.1. Endpoint Identification and Authentication . . . . . . . 41 8.1. Endpoint Identification and Authentication . . . . . . . 42
8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 42 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 43
8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 42 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 43
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 43 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 44
9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 43 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 44
9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 43 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 44
9.3.1. Full description of the "Endpoint Type" Registration 9.3.1. Full description of the "Endpoint Type" Registration
Parameter . . . . . . . . . . . . . . . . . . . . . . 45 Parameter . . . . . . . . . . . . . . . . . . . . . . 46
9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 45 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 46
9.5. Multicast Address Registration . . . . . . . . . . . . . 46 9.5. Multicast Address Registration . . . . . . . . . . . . . 47
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 46 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47
10.1. Lighting Installation . . . . . . . . . . . . . . . . . 46 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 48
10.1.1. Installation Characteristics . . . . . . . . . . . . 47 10.1.1. Installation Characteristics . . . . . . . . . . . . 48
10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 48 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 49
10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 50 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 52
10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 51 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 52
10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 52 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 54
10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 54 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 55
10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 54 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 56
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 56
12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 54 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 56
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 63 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 65
13.1. Normative References . . . . . . . . . . . . . . . . . . 63 13.1. Normative References . . . . . . . . . . . . . . . . . . 65
13.2. Informative References . . . . . . . . . . . . . . . . . 64 13.2. Informative References . . . . . . . . . . . . . . . . . 66
Appendix A. Groups Registration and Lookup . . . . . . . . . . . 66 Appendix A. Groups Registration and Lookup . . . . . . . . . . . 68
Appendix B. Web links and the Resource Directory . . . . . . . . 67 Appendix B. Web links and the Resource Directory . . . . . . . . 70
B.1. A simple example . . . . . . . . . . . . . . . . . . . . 68 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 70
B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 68 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 71
B.1.2. Interpreting attributes and relations . . . . . . . . 68 B.1.2. Interpreting attributes and relations . . . . . . . . 71
B.2. A slightly more complex example . . . . . . . . . . . . . 69 B.2. A slightly more complex example . . . . . . . . . . . . . 71
B.3. Enter the Resource Directory . . . . . . . . . . . . . . 69 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 72
B.4. A note on differences between link-format and Link B.4. A note on differences between link-format and Link
headers . . . . . . . . . . . . . . . . . . . . . . . . . 71 headers . . . . . . . . . . . . . . . . . . . . . . . . . 74
Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 72 Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 75
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75
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 17, line 11 skipping to change at page 17, line 11
addresses that don't work out. For example, an ICMP Destination addresses that don't work out. For example, an ICMP Destination
Unreachable message (and, in particular, the port unreachable code Unreachable message (and, in particular, the port unreachable code
for this message) may indicate the lack of a CoAP server on the for this message) may indicate the lack of a CoAP server on the
candidate host, or a CoAP error response code such as 4.05 "Method candidate host, or a CoAP error response code such as 4.05 "Method
Not Allowed" may indicate unwillingness of a CoAP server to act as a Not Allowed" may indicate unwillingness of a CoAP server to act as a
directory server. directory server.
The following RD discovery mechanisms are recommended: The following RD discovery mechanisms are recommended:
o In managed networks with border routers that need stand-alone o In managed networks with border routers that need stand-alone
operation, the RDA0 option is recommended (e.g. operational phase operation, the RDAO option is recommended (e.g. operational phase
described in Section 3.6). described in Section 3.6).
o In managed networks without border router (no Internet services o In managed networks without border router (no Internet services
available), the use of a preconfigured anycast address is available), the use of a preconfigured anycast address is
recommended (e.g. installation phase described in Section 3.6). recommended (e.g. installation phase described in Section 3.6).
o The use of DNS facilities is described in o The use of DNS facilities is described in
[I-D.ietf-core-rd-dns-sd]. [I-D.ietf-core-rd-dns-sd].
The use of multicast discovery in mesh networks is NOT recommended. The use of multicast discovery in mesh networks is NOT recommended.
skipping to change at page 21, line 12 skipping to change at page 21, line 12
"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.
[ The RFC editor is asked to replace this and later occurrences of
MCD1 with the assigned IPv6 site-local address for "all CoRE Resource
Directories". ]
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: Exemple discovery exchange indicating additional content-
formats
From a management and maintenance perspective, it is necessary to From a management and maintenance perspective, it is necessary to
identify the components that constitute the RD server. The identify the components that constitute the RD server. The
identification refers to information about for example client-server identification refers to information about for example client-server
incompatibilities, supported features, required updates and other incompatibilities, supported features, required updates and other
aspects. The URI discovery address, a described in section 4 of aspects. The URI discovery address, a described in section 4 of
[RFC6690] can be used to find the identification. [RFC6690] can be used to find the identification.
It would typically be stored in an implementation information link It would typically be stored in an implementation information link
(as described in [I-D.bormann-t2trg-rel-impl]): (as described in [I-D.bormann-t2trg-rel-impl]):
Req: GET /.well-known/core?rel=impl-info Req: GET /.well-known/core?rel=impl-info
Res: 2.05 Content Res: 2.05 Content
<http://software.example.com/shiny-resource-directory/1.0beta1>; <http://software.example.com/shiny-resource-directory/1.0beta1>;
rel="impl-info" rel="impl-info"
Figure 7: Exemple exchange of obtaining implementation information
Note that depending on the particular server's architecture, such a Note that depending on the particular server's architecture, such a
link could be anchored at the RD server's root, at the discovery site link could be anchored at the RD server's root, at the discovery site
(as in this example) or at individual RD components. The latter is (as in this example) or at individual RD components. The latter is
to be expected when different applications are run on the same to be expected when different applications are run on the same
server. server.
5. Registration 5. Registration
After discovering the location of an RD, a registrant-ep or CT MAY After discovering the location of an RD, a registrant-ep or CT MAY
register the resources of the registrant-ep using the registration register the resources of the registrant-ep using the registration
skipping to change at page 25, line 30 skipping to change at page 25, line 35
the whole registration time, not only for a single operation. the whole registration time, not only for a single operation.
The following example shows a registrant-ep with the name "node1" The following example shows a registrant-ep with the name "node1"
registering two resources to an RD using this interface. The registering two resources to an RD using this interface. The
location "/rd" is an example RD location discovered in a request location "/rd" is an example RD location discovered in a request
similar to Figure 5. similar to Figure 5.
Req: POST coap://rd.example.com/rd?ep=node1 Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor"; </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
anchor="coap://spurious.example.com:5683", <http://www.example.com/sensors/temp>;
</sensors/light>;ct=41;rt="light-lux";if="sensor" anchor="/sensors/temp";rel="describedby"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/4521 Location-Path: /rd/4521
Figure 6: Example registration payload Figure 8: Example registration payload
A Resource Directory may optionally support HTTP. Here is an example A Resource Directory may optionally support HTTP. Here is an example
of almost the same registration operation above, when done using of almost the same registration operation above, when done using
HTTP. HTTP.
Req: POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1 Req: POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/link-format Content-Type: application/link-format
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor"; </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
anchor="coap://spurious.example.com:5683", <http://www.example.com/sensors/temp>;
</sensors/light>;ct=41;rt="light-lux";if="sensor" anchor="/sensors/temp";rel="describedby"
Res: 201 Created Res: 201 Created
Location: /rd/4521 Location: /rd/4521
Figure 9: Example registration payload as expressed using HTTP
5.1. Simple Registration 5.1. Simple Registration
Not all endpoints hosting resources are expected to know how to Not all endpoints hosting resources are expected to know how to
upload links to an RD as described in Section 5. Instead, simple upload links to an RD as described in Section 5. Instead, simple
endpoints can implement the Simple Registration approach described in endpoints can implement the Simple Registration approach described in
this section. An RD implementing this specification MUST implement this section. An RD implementing this specification MUST implement
Simple Registration. However, there may be security reasons why this Simple Registration. However, there may be security reasons why this
form of directory discovery would be disabled. form of directory discovery would be disabled.
This approach requires that the registrant-ep makes available the This approach requires that the registrant-ep makes available the
skipping to change at page 26, line 41 skipping to change at page 27, line 8
POST request as it would per Section 5. The registration base URI POST request as it would per Section 5. The registration base URI
of the registration is taken from the registrant-ep's network of the registration is taken from the registrant-ep's network
address (as is default with regular registrations). address (as is default with regular registrations).
Example request from registrant-EP to RD (unanswered until the Example request from registrant-EP to RD (unanswered until the
next step): next step):
Req: POST /.well-known/core?lt=6000&ep=node1 Req: POST /.well-known/core?lt=6000&ep=node1
(No payload) (No payload)
Figure 10: First half example exchange of a simple registration
o The Resource Directory queries the registrant-ep's discovery o The Resource Directory queries the registrant-ep's discovery
resource to determine the success of the operation. It SHOULD resource to determine the success of the operation. It SHOULD
keep a cache of the discovery resource and not query it again as keep a cache of the discovery resource and not query it again as
long as it is fresh. long as it is fresh.
Example request from the RD to the registrant-EP: Example request from the RD to the registrant-EP:
Req: GET /.well-known/core Req: GET /.well-known/core
Accept: 40 Accept: 40
Res: 2.05 Content Res: 2.05 Content
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sen/temp> </sen/temp>
Figure 11: Example exchange of the RD querying the simple endpoint
With this response, the RD would answer the previous step's request: With this response, the RD would answer the previous step's request:
Res: 2.04 Changed Res: 2.04 Changed
Figure 12: Second half example exchange of a simple registration
The sequence of fetching the registration content before sending a The sequence of fetching the registration content before sending a
successful response was chosen to make responses reliable, and the successful response was chosen to make responses reliable, and the
caching item was chosen to still allow very constrained registrants. caching item was chosen to still allow very constrained registrants.
Registrants MUST be able to serve a GET request to "/.well-known/ Registrants MUST be able to serve a GET request to "/.well-known/
core" after having requested registration. Constrained devices MAY core" after having requested registration. Constrained devices MAY
regard the initial request as temporarily failed when they need RAM regard the initial request as temporarily failed when they need RAM
occupied by their own request to serve the RD's GET, and retry later occupied by their own request to serve the RD's GET, and retry later
when the RD already has a cached representation of their discovery when the RD already has a cached representation of their discovery
resources. Then, the RD can reply immediately and the registrant can resources. Then, the RD can reply immediately and the registrant can
receive the response. receive the response.
skipping to change at page 31, line 4 skipping to change at page 31, line 20
Max-Age/Retry-After exceeds the remaining lifetime, the registering Max-Age/Retry-After exceeds the remaining lifetime, the registering
endpoint SHOULD attempt registration again. endpoint SHOULD attempt registration again.
The following example shows how the registering endpoint updates its The following example shows how the registering endpoint updates its
registration resource at an RD using this interface with the example registration resource at an RD using this interface with the example
location value: /rd/4521. location value: /rd/4521.
Req: POST /rd/4521 Req: POST /rd/4521
Res: 2.04 Changed Res: 2.04 Changed
Figure 13: Example update of a registration
The following example shows the registering endpoint updating its The following example shows the registering endpoint updating its
registration resource at an RD using this interface with the example registration resource at an RD using this interface with the example
location value: /rd/4521. The initial registration by the location value: /rd/4521. The initial registration by the
registering endpoint set the following values: registering endpoint set the following values:
o endpoint name (ep)=endpoint1 o endpoint name (ep)=endpoint1
o lifetime (lt)=500 o lifetime (lt)=500
o Base URI (base)=coap://local-proxy-old.example.com:5683 o Base URI (base)=coap://local-proxy-old.example.com:5683
o payload of Figure 6 o payload of Figure 8
The initial state of the Resource Directory is reflected in the The initial state of the Resource Directory is reflected in the
following request: following request:
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content Res: 2.01 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"; anchor="coap://spurious.example.com:5683", rt="temperature-c";if="sensor";
<coap://local-proxy-old.example.com:5683/sensors/light>;ct=41; anchor="coap://local-proxy-old.example.com:5683/",
rt="light-lux"; if="sensor"; <http://www.example.com/sensors/temp>;
anchor="coap://local-proxy-old.example.com:5683" anchor="coap://local-proxy-old.example.com:5683/sensors/temp";rel="describedby"
Figure 14: Example lookup before a change to the base address
The following example shows the registering endpoint changing the The following example shows the registering endpoint changing the
Base URI to "coaps://new.example.com:5684": Base URI to "coaps://new.example.com:5684":
Req: POST /rd/4521?base=coaps://new.example.com:5684 Req: POST /rd/4521?base=coaps://new.example.com:5684
Res: 2.04 Changed Res: 2.04 Changed
Figure 15: Example registration update that changes the base address
The consecutive query returns: The consecutive query returns:
Req: GET /rd-lookup/res?ep=endpoint1 Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content Res: 2.01 Content
Payload: Payload:
<coaps://new.example.com:5684/sensors/temp>;ct=41;rt="temperature"; <coap://new.example.com:5684/sensors/temp>;ct=41;
anchor="coap://spurious.example.com:5683", rt="temperature-c";if="sensor";
<coaps://new.example.com:5684/sensors/light>;ct=41;rt="light-lux"; anchor="coap://new.example.com:5684/",
if="sensor"; anchor="coaps://new.example.com:5684", <http://www.example.com/sensors/temp>;
anchor="coap://new.example.com:5684/sensors/temp";rel="describedby"
Figure 16: Example lookup after a change to the base address
5.3.2. Registration Removal 5.3.2. Registration Removal
Although RD registrations have soft state and will eventually timeout Although RD registrations have soft state and will eventually timeout
after their lifetime, the registering endpoint SHOULD explicitly after their lifetime, the registering endpoint SHOULD explicitly
remove an entry from the RD if it knows it will no longer be remove an entry from the RD if it knows it will no longer be
available (for example on shut-down). This is accomplished using a available (for example on shut-down). This is accomplished using a
removal interface on the RD by performing a DELETE on the endpoint removal interface on the RD by performing a DELETE on the endpoint
resource. resource.
skipping to change at page 32, line 41 skipping to change at page 33, line 12
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may already have been removed). exist (e.g. may already have been removed).
The following examples shows successful removal of the endpoint from The following examples shows successful removal of the endpoint from
the RD with example location value /rd/4521. the RD with example location value /rd/4521.
Req: DELETE /rd/4521 Req: DELETE /rd/4521
Res: 2.02 Deleted Res: 2.02 Deleted
Figure 17: Example of a registration removal
5.3.3. Further operations 5.3.3. Further operations
Additional operations on the registration can be specified in future Additional operations on the registration can be specified in future
documents, for example: documents, for example:
o Send iPATCH (or PATCH) updates ([RFC8132]) to add, remove or o Send iPATCH (or PATCH) updates ([RFC8132]) to add, remove or
change the links of a registration. change the links of a registration.
o Use GET to read the currently stored set of links in a o Use GET to read the currently stored set of links in a
registration resource. registration resource.
skipping to change at page 36, line 26 skipping to change at page 36, line 51
The following example shows a client performing a resource lookup The following example shows a client performing a resource lookup
with the example resource look-up locations discovered in Figure 5: with the example resource look-up locations discovered in Figure 5:
Req: GET /rd-lookup/res?rt=temperature Req: GET /rd-lookup/res?rt=temperature
Res: 2.05 Content Res: 2.05 Content
<coap://[2001:db8:3::123]:61616/temp>;rt="temperature"; <coap://[2001:db8:3::123]:61616/temp>;rt="temperature";
anchor="coap://[2001:db8:3::123]:61616" anchor="coap://[2001:db8:3::123]:61616"
Figure 18: Example a resource lookup
A client that wants to be notified of new resources as they show up A client that wants to be notified of new resources as they show up
can use observation: can use observation:
Req: GET /rd-lookup/res?rt=light Req: GET /rd-lookup/res?rt=light
Observe: 0 Observe: 0
Res: 2.05 Content Res: 2.05 Content
Observe: 23 Observe: 23
Payload: empty Payload: empty
skipping to change at page 36, line 48 skipping to change at page 37, line 27
Res: 2.05 Content Res: 2.05 Content
Observe: 24 Observe: 24
Payload: Payload:
<coap://[2001:db8:3::124]/west>;rt="light"; <coap://[2001:db8:3::124]/west>;rt="light";
anchor="coap://[2001:db8:3::124]", anchor="coap://[2001:db8:3::124]",
<coap://[2001:db8:3::124]/south>;rt="light"; <coap://[2001:db8:3::124]/south>;rt="light";
anchor="coap://[2001:db8:3::124]", anchor="coap://[2001:db8:3::124]",
<coap://[2001:db8:3::124]/east>;rt="light"; <coap://[2001:db8:3::124]/east>;rt="light";
anchor="coap://[2001:db8:3::124]" anchor="coap://[2001:db8:3::124]"
Figure 19: Example an observing resource lookup
The following example shows a client performing a paginated resource The following example shows a client performing a paginated resource
lookup lookup
Req: GET /rd-lookup/res?page=0&count=5 Req: GET /rd-lookup/res?page=0&count=5
Res: 2.05 Content Res: 2.05 Content
<coap://[2001:db8:3::123]:61616/res/0>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/0>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/1>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/1>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/2>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/2>;rt=sensor;ct=60;
skipping to change at page 37, line 32 skipping to change at page 38, line 32
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/6>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/6>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/7>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/7>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/8>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/8>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616", anchor="coap://[2001:db8:3::123]:61616",
<coap://[2001:db8:3::123]:61616/res/9>;rt=sensor;ct=60; <coap://[2001:db8:3::123]:61616/res/9>;rt=sensor;ct=60;
anchor="coap://[2001:db8:3::123]:61616" anchor="coap://[2001:db8:3::123]:61616"
Figure 20: Examples of paginated resource lookup
The following example shows a client performing a lookup of all The following example shows a client performing a lookup of all
resources from endpoints of all endpoints of a given endpoint type. resources of all endpoints of a given endpoint type. It assumes that
It assumes that two endpoints (with endpoint names "sensor1" and two endpoints (with endpoint names "sensor1" and "sensor2") have
"sensor2") have previously registered with their respective addresses previously registered with their respective addresses
"coap://sensor1.example.com" and "coap://sensor2.example.com", and "coap://sensor1.example.com" and "coap://sensor2.example.com", and
posted the very payload of the 6th request of section 5 of [RFC6690]. posted the very payload of the 6th request of section 5 of [RFC6690].
It demonstrates how absolute link targets stay unmodified, while It demonstrates how absolute link targets stay unmodified, while
relative ones are resolved: relative ones are resolved:
Req: GET /rd-lookup/res?et=oic.d.sensor Req: GET /rd-lookup/res?et=oic.d.sensor
<coap://sensor1.example.com/sensors>;ct=40;title="Sensor Index"; <coap://sensor1.example.com/sensors>;ct=40;title="Sensor Index";
anchor="coap://sensor1.example.com", anchor="coap://sensor1.example.com",
skipping to change at page 38, line 28 skipping to change at page 39, line 28
anchor="coap://sensor2.example.com", anchor="coap://sensor2.example.com",
<coap://sensor2.example.com/sensors/temp>;rt="temperature-c"; <coap://sensor2.example.com/sensors/temp>;rt="temperature-c";
if="sensor"; anchor="coap://sensor2.example.com", if="sensor"; anchor="coap://sensor2.example.com",
<coap://sensor2.example.com/sensors/light>;rt="light-lux"; <coap://sensor2.example.com/sensors/light>;rt="light-lux";
if="sensor"; anchor="coap://sensor2.example.com", if="sensor"; anchor="coap://sensor2.example.com",
<http://www.example.com/sensors/t123>;rel="describedby"; <http://www.example.com/sensors/t123>;rel="describedby";
anchor="coap://sensor2.example.com/sensors/temp", anchor="coap://sensor2.example.com/sensors/temp",
<coap://sensor2.example.com/t>;rel="alternate"; <coap://sensor2.example.com/t>;rel="alternate";
anchor="coap://sensor2.example.com/sensors/temp" anchor="coap://sensor2.example.com/sensors/temp"
Figure 21: Example of resource lookup from multiple endpoints
6.4. Endpoint lookup 6.4. Endpoint lookup
The endpoint lookup returns registration resources which can only be The endpoint lookup returns registration resources which can only be
manipulated by the registering endpoint. manipulated by the registering endpoint.
Endpoint registration resources are annotated with their endpoint Endpoint registration resources are annotated with their endpoint
names (ep), sectors (d, if present) and registration base URI (base; names (ep), sectors (d, if present) and registration base URI (base;
reports the registrant-ep's address if no explicit base was given) as reports the registrant-ep's address if no explicit base was given) as
well as a constant resource type (rt="core.rd-ep"); the lifetime (lt) well as a constant resource type (rt="core.rd-ep"); the lifetime (lt)
is not reported. Additional endpoint attributes are added as target is not reported. Additional endpoint attributes are added as target
skipping to change at page 39, line 23 skipping to change at page 40, line 27
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
7. Security policies 7. Security policies
The Resource Directory (RD) provides assistance to applications The Resource Directory (RD) provides assistance to applications
situated on a selection of nodes to discover endpoints on connected situated on a selection of nodes to discover endpoints on connected
nodes. This section discusses different security aspects of nodes. This section discusses different security aspects of
accessing the RD. accessing the RD.
The contents of the RD are inserted in two ways: The contents of the RD are inserted in two ways:
1. The node hosting the discoverable endpoint fills the RD with the 1. The node hosting the discoverable endpoint fills the RD with the
skipping to change at page 44, line 24 skipping to change at page 45, line 28
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 | | RLA | Name of the | | Endpoint | ep | Unicode* | RLA | Name of the endpoint |
| Name | | | | endpoint, max 63 | | Name | | | | |
| | | | | bytes |
| Lifetime | lt | 60-4294967295 | R | Lifetime of the | | Lifetime | lt | 60-4294967295 | R | Lifetime of the |
| | | | | registration in | | | | | | registration in |
| | | | | seconds | | | | | | seconds |
| Sector | d | | RLA | Sector to which this | | Sector | d | Unicode* | RLA | Sector to which this |
| | | | | endpoint belongs | | | | | | endpoint belongs |
| Registration | base | URI | RLA | The scheme, address | | Registration | base | URI | RLA | The scheme, address |
| Base URI | | | | and port and path at | | Base URI | | | | and port and path at |
| | | | | which this server is | | | | | | which this server is |
| | | | | available | | | | | | available |
| Page | page | Integer | L | Used for pagination | | Page | page | Integer | L | Used for pagination |
| Count | count | Integer | L | Used for pagination | | Count | count | Integer | L | Used for pagination |
| Endpoint | et | | RLA | Semantic name of the | | Endpoint | et | Section 9.3.1 | RLA | Semantic type of the |
| Type | | | | endpoint (see | | Type | | | | endpoint (see |
| | | | | Section 9.4) | | | | | | Section 9.4) |
+--------------+-------+---------------+-----+----------------------+ +--------------+-------+---------------+-----+----------------------+
Table 2: RD Parameters Table 2: RD Parameters
(Short: Short name used in query parameters or target attributes. (Short: Short name used in query parameters or target attributes.
Use: R = used at registration, L = used at lookup, A = expressed in Validity: Unicode* = 63 Bytes of UTF-8 encoded Unicode, with no
target attribute control characters as per Section 5. Use: R = used at registration,
L = used at lookup, A = expressed in target attribute
The descriptions for the options defined in this document are only The descriptions for the options defined in this document are only
summarized here. To which registrations they apply and when they are summarized here. To which registrations they apply and when they are
to be shown is described in the respective sections of this document. to be shown is described in the respective sections of this document.
The IANA policy for future additions to the sub-registry is "Expert The IANA policy for future additions to the sub-registry is "Expert
Review" as described in [RFC8126]. The evaluation should consider Review" as described in [RFC8126]. The evaluation should consider
formal criteria, duplication of functionality (Is the new entry formal criteria, duplication of functionality (Is the new entry
redundant with an existing one?), topical suitability (E.g. is the redundant with an existing one?), topical suitability (E.g. is the
described property actually a property of the endpoint and not a described property actually a property of the endpoint and not a
property of a particular resource, in which case it should go into property of a particular resource, in which case it should go into
skipping to change at page 46, line 20 skipping to change at page 47, line 25
o It is recommended to use the period "." character for o It is recommended to use the period "." character for
segmentation. segmentation.
The registry initially contains one value: The registry initially contains one value:
o "core.rd-group": An application group as described in Appendix A. o "core.rd-group": An application group as described in Appendix A.
9.5. Multicast Address Registration 9.5. Multicast Address Registration
IANA has assigned the following multicast addresses for use by CoAP IANA is asked to assign the following multicast addresses for use by
nodes: CoAP nodes:
IPv4 - "all CoRE resource directories" address, from the "IPv4 IPv4 - "all CoRE resource directories" address MCD2 (suggestion:
Multicast Address Space Registry" equal to "All CoAP Nodes", 224.0.1.189), from the "IPv4 Multicast Address Space Registry". As
224.0.1.187. As the address is used for discovery that may span the address is used for discovery that may span beyond a single
beyond a single network, it has come from the Internetwork Control network, it has come from the Internetwork Control Block (224.0.1.x,
Block (224.0.1.x, RFC 5771). RFC 5771).
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
addresses throughout the document. ]
10. Examples 10. Examples
Two examples are presented: a Lighting Installation example in Two examples are presented: a Lighting Installation example in
Section 10.1 and a LWM2M example in Section 10.2. Section 10.1 and a LWM2M example in Section 10.2.
10.1. Lighting Installation 10.1. Lighting Installation
This example shows a simplified lighting installation which makes use This example shows a simplified lighting installation which makes use
of the Resource Directory (RD) with a CoAP interface to facilitate of the Resource Directory (RD) with a CoAP interface to facilitate
the installation and start-up of the application code in the lights the installation and start-up of the application code in the lights
skipping to change at page 49, line 33 skipping to change at page 50, line 41
Location-Path: /rd/4522 Location-Path: /rd/4522
Req: POST coap://[2001:db8:4::ff]/rd Req: POST coap://[2001:db8:4::ff]/rd
?ep=ps_R2-4-015_door&base=coap://[2001:db8:4::3]d&d=R2-4-015 ?ep=ps_R2-4-015_door&base=coap://[2001:db8:4::3]d&d=R2-4-015
Payload: Payload:
</ps>;rt="p-sensor" </ps>;rt="p-sensor"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/4523 Location-Path: /rd/4523
Figure 23: Example of registrations a CT enters into an RD
The sector name d=R2-4-015 has been added for an efficient lookup The sector name d=R2-4-015 has been added for an efficient lookup
because filtering on "ep" name is more awkward. The same sector name because filtering on "ep" name is more awkward. The same sector name
is communicated to the two luminaries and the presence sensor by the is communicated to the two luminaries and the presence sensor by the
CT. CT.
The group is specified in the RD. The base parameter is set to the The group is specified in the RD. The base parameter is set to the
site-local multicast address allocated to the group. In the POST in site-local multicast address allocated to the group. In the POST in
the example below, the resources supported by all group members are the example below, the resources supported by all group members are
published. published.
Req: POST coap://[2001:db8:4::ff]/rd Req: POST coap://[2001:db8:4::ff]/rd
?ep=grp_R2-4-015&et=core.rd-group&base=coap://[ff05::1] ?ep=grp_R2-4-015&et=core.rd-group&base=coap://[ff05::1]
Payload: Payload:
</light/left>;rt="light", </light/left>;rt="light",
</light/middle>;rt="light", </light/middle>;rt="light",
</light/right>;rt="light" </light/right>;rt="light"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/501 Location-Path: /rd/501
Figure 24: Example of a multicast group a CT enters into an RD
After the filling of the RD by the CT, the application in the After the filling of the RD by the CT, the application in the
luminaries can learn to which groups they belong, and enable their luminaries can learn to which groups they belong, and enable their
interface for the multicast address. interface for the multicast address.
The luminary, knowing its sector and being configured to join any The luminary, knowing its sector and being configured to join any
group containing lights, searches for candidate groups and joins group containing lights, searches for candidate groups and joins
them: them:
Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep
?d=R2-4-015&et=core.rd-group&rt=light ?d=R2-4-015&et=core.rd-group&rt=light
Res: 2.05 Content Res: 2.05 Content
</rd/501>;ep="grp_R2-4-015";et="core.rd-group"; </rd/501>;ep="grp_R2-4-015";et="core.rd-group";
base="coap://[ff05::1]";rt="core.rd-ep" base="coap://[ff05::1]";rt="core.rd-ep"
Figure 25: Example of a lookup exchange to find suitable multicast
addresses
From the returned base parameter value, the luminary learns the From the returned base parameter value, the luminary learns the
multicast address of the multicast group. multicast address of the multicast group.
Alternatively, the CT can communicate the multicast address directly Alternatively, the CT can communicate the multicast address directly
to the luminaries by using the "coap-group" resource specified in to the luminaries by using the "coap-group" resource specified in
[RFC7390]. [RFC7390].
Req: POST coap://[2001:db8:4::1]/coap-group Req: POST coap://[2001:db8:4::1]/coap-group
Content-Format: application/coap-group+json Content-Format: application/coap-group+json
Payload: Payload:
{ "a": "[ff05::1]", "n": "grp_R2-4-015"} { "a": "[ff05::1]", "n": "grp_R2-4-015"}
Res: 2.01 Created Res: 2.01 Created
Location-Path: /coap-group/1 Location-Path: /coap-group/1
Figure 26: Example use of direct multicast address configuration
Dependent on the situation, only the address, "a", or the name, "n", Dependent on the situation, only the address, "a", or the name, "n",
is specified in the coap-group resource. is specified in the coap-group resource.
The presence sensor can learn the presence of groups that support The presence sensor can learn the presence of groups that support
resources with rt=light in its own sector by sending the same resources with rt=light in its own sector by sending the same
request, as used by the luminary. The presence sensor learns the request, as used by the luminary. The presence sensor learns the
multicast address to use for sending messages to the luminaries. multicast address to use for sending messages to the luminaries.
10.2. OMA Lightweight M2M (LWM2M) Example 10.2. OMA Lightweight M2M (LWM2M) Example
skipping to change at page 54, line 38 skipping to change at page 56, line 19
LWM2M allows for de-registration using the delete method on the LWM2M allows for de-registration using the delete method on the
returned location from the initial registration operation. LWM2M de- returned location from the initial registration operation. LWM2M de-
registration proceeds as described in Section 5.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 and Jaime Jimenez have provided helpful comments, Kovatsch, Jaime Jimenez and Ted Lemon have provided helpful comments,
discussions and ideas to improve and shape this document. Zach would discussions and ideas to improve and shape this document. Zach would
also like to thank his colleagues from the EU FP7 SENSEI project, also like to thank his colleagues from the EU FP7 SENSEI project,
where many of the resource directory concepts were originally where many of the resource directory concepts were originally
developed. developed.
12. Changelog 12. Changelog
changes from -21 to -22
o Request a dedicated IPv4 address from IANA (rather than sharing
with All CoAP nodes)
o Fix erroneous examples
o Editorial changes
* Add figure numbers to examples
* Update RD parameters table to reflect changes of earlier
versions in the text
* Typos and minor wording
changes from -20 to -21
(Processing comments during WGLC)
o Defer outdated description of using DNS-SD to find an RD to the
defining document
o Describe operational conditions in automation example
o Recommend particular discovery mechanisms for some managed network
scenarios
changes from -19 to -20 changes from -19 to -20
(Processing comments from the WG chair review) (Processing comments from the WG chair review)
o Define the permissible characters in endpoint and sector names o Define the permissible characters in endpoint and sector names
o Express requirements on NAT situations in more abstract terms o Express requirements on NAT situations in more abstract terms
o Shifted heading levels to have the interfaces on the same level o Shifted heading levels to have the interfaces on the same level
o Group instructions for error handling into general section o Group instructions for error handling into general section
o Simple Registration: process reflowed into items list o Simple Registration: process reflowed into items list
o Updated introduction to reflect state of CoRE in general, o Updated introduction to reflect state of CoRE in general,
reference RFC7228 (defining "constrained") and use "IoT" term in reference RFC7228 (defining "constrained") and use "IoT" term in
skipping to change at page 66, line 47 skipping to change at page 69, line 15
Req: POST coap://rd.example.com/rd?ep=lights&et=core.rd-group Req: POST coap://rd.example.com/rd?ep=lights&et=core.rd-group
&base=coap://[ff35:30:2001:db8::1] &base=coap://[ff35:30:2001:db8::1]
Content-Format: 40 Content-Format: 40
Payload: Payload:
</light>;rt="light";if="core.a", </light>;rt="light";if="core.a",
</color-temperature>;if="core.p";u="K" </color-temperature>;if="core.p";u="K"
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/12 Location-Path: /rd/12
Figure 27: Example registration of a group
In this example, the group manager can easily permit devices that In this example, the group manager can easily permit devices that
have no writable color-temperature to join, as they would still have no writable color-temperature to join, as they would still
respond to brightness changing commands. Had the group instead respond to brightness changing commands. Had the group instead
contained a single resource that sets brightness and color contained a single resource that sets brightness and color
temperature atomically, endpoints would need to support both temperature atomically, endpoints would need to support both
properties. properties.
The resources of a group can be looked up like any other resource, The resources of a group can be looked up like any other resource,
and the group registrations (along with any additional registration and the group registrations (along with any additional registration
parameters) can be looked up using the endpoint lookup interface. parameters) can be looked up using the endpoint lookup interface.
skipping to change at page 67, line 21 skipping to change at page 69, line 40
Req: GET /rd-lookup/ep?et=core.rd-group Req: GET /rd-lookup/ep?et=core.rd-group
Res: 2.01 Content Res: 2.01 Content
Payload: Payload:
</rd/501>;ep="GRP_R2-4-015";et="core.rd-group"; </rd/501>;ep="GRP_R2-4-015";et="core.rd-group";
base="coap://[ff05::1]", base="coap://[ff05::1]",
</rd/12>;ep=lights&et=core.rd-group; </rd/12>;ep=lights&et=core.rd-group;
base="coap://[ff35:30:2001:db8::1]";rt="core.rd-ep" base="coap://[ff35:30:2001:db8::1]";rt="core.rd-ep"
Figure 28: Example lookup of groups
The following example shows a client performing a lookup of all The following example shows a client performing a lookup of all
resources of all endpoints (groups) with et=core.rd-group. resources of all endpoints (groups) with et=core.rd-group.
Req: GET /rd-lookup/res?et=core.rd-group Req: GET /rd-lookup/res?et=core.rd-group
<coap://[ff35:30:2001:db8::1]/light>;rt="light";if="core.a"; <coap://[ff35:30:2001:db8::1]/light>;rt="light";if="core.a";
et="core.rd-group";anchor="coap://[ff35:30:2001:db8::1]", et="core.rd-group";anchor="coap://[ff35:30:2001:db8::1]",
<coap://[ff35:30:2001:db8::1]/color-temperature>;if="core.p";u="K"; <coap://[ff35:30:2001:db8::1]/color-temperature>;if="core.p";u="K";
et="core.rd-group"; et="core.rd-group";
anchor="coap://[ff35:30:2001:db8::1]" anchor="coap://[ff35:30:2001:db8::1]"
Figure 29: Example lookup of resources inside groups
Appendix B. Web links and the Resource Directory Appendix B. Web links and the Resource Directory
Understanding the semantics of a link-format document and its URI Understanding the semantics of a link-format document and its URI
references is a journey through different documents ([RFC3986] references is a journey through different documents ([RFC3986]
defining URIs, [RFC6690] defining link-format documents based on defining URIs, [RFC6690] defining link-format documents based on
[RFC8288] which defines link headers, and [RFC7252] providing the [RFC8288] which defines link headers, and [RFC7252] providing the
transport). This appendix summarizes the mechanisms and semantics at transport). This appendix summarizes the mechanisms and semantics at
play from an entry in ".well-known/core" to a resource lookup. play from an entry in ".well-known/core" to a resource lookup.
This text is primarily aimed at people entering the field of This text is primarily aimed at people entering the field of
skipping to change at page 68, line 19 skipping to change at page 70, line 46
sends the following multicast request to learn about neighbours sends the following multicast request to learn about neighbours
supporting resources with resource-type "temperature". supporting resources with resource-type "temperature".
The client sends a link-local multicast: The client sends a link-local multicast:
GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature
RES 2.05 Content RES 2.05 Content
</temp>;rt=temperature;ct=0 </temp>;rt=temperature;ct=0
Figure 30: Example of direct resource discovery
where the response is sent by the server, "[2001:db8:f0::1]:5683". where the response is sent by the server, "[2001:db8:f0::1]:5683".
While the client - on the practical or implementation side - can just While the client - on the practical or implementation side - can just
go ahead and create a new request to "[2001:db8:f0::1]:5683" with go ahead and create a new request to "[2001:db8:f0::1]:5683" with
Uri-Path: "temp", the full resolution steps for insertion into and Uri-Path: "temp", the full resolution steps for insertion into and
retrieval from the RD without any shortcuts are: retrieval from the RD without any shortcuts are:
B.1.1. Resolving the URIs B.1.1. Resolving the URIs
The client parses the single returned record. The link's target The client parses the single returned record. The link's target
skipping to change at page 69, line 27 skipping to change at page 72, line 11
Omitting the "rt=temperature" filter, the discovery query would have Omitting the "rt=temperature" filter, the discovery query would have
given some more records in the payload: given some more records in the payload:
GET coap://[ff02::fd]:5683/.well-known/core GET coap://[ff02::fd]:5683/.well-known/core
RES 2.05 Content RES 2.05 Content
</temp>;rt=temperature;ct=0, </temp>;rt=temperature;ct=0,
</light>;rt=light-lux;ct=0, </light>;rt=light-lux;ct=0,
</t>;anchor="/sensors/temp";rel=alternate, </t>;anchor="/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>;anchor="/sensors/temp"; <http://www.example.com/sensors/t123>;anchor="/temp";
rel="describedby" rel="describedby"
Figure 31: Extended example of direct resource discovery
Parsing the third record, the client encounters the "anchor" Parsing the third record, the client encounters the "anchor"
parameter. It is a URI relative to the Base URI of the request and parameter. It is a URI relative to the Base URI of the request and
is thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That is thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That
is the context resource of the link, so the "rel" statement is not is the context resource of the link, so the "rel" statement is not
about the target and the Base URI any more, but about the target and about the target and the Base URI any more, but about the target and
the resolved URI. Thus, the third record could be read as the resolved URI. Thus, the third record could be read as
""coap://[2001:db8:f0::1]/sensors/temp" has an alternate ""coap://[2001:db8:f0::1]/sensors/temp" has an alternate
representation at "coap://[2001:db8:f0::1]/t"". representation at "coap://[2001:db8:f0::1]/t"".
Following the same resolution steps, the fourth record can be read as Following the same resolution steps, the fourth record can be read as
skipping to change at page 70, line 9 skipping to change at page 72, line 42
classical CoAP discovery over to the resource lookup interface as classical CoAP discovery over to the resource lookup interface as
faithfully as possible. faithfully as 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 resource directory that
was announced to it, sending this request from its UDP port was announced to 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
The resource directory would have accepted the registration, and The resource directory would have accepted the registration, and
queried the simple host's ".well-known/core" by itself. As a result, queried the simple host's ".well-known/core" by itself. As a result,
the host is registered as an endpoint in the RD with the name the host is registered as an endpoint in the RD with the name
"simple-host1". The registration is active for 90000 seconds, and "simple-host1". The registration is active for 90000 seconds, and
the endpoint registration Base URI is ""coap://[2001:db8:f0::1]"" the endpoint registration Base URI is ""coap://[2001:db8:f0::1]""
following the resolution steps described in Appendix B.1.1. It following the resolution steps described in Appendix B.1.1. It
should be remarked that the Base URI constructed that way always should be remarked that the Base URI constructed that way always
yields a URI of the form: scheme://authority without path suffix. yields a URI of the 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;
anchor="coap://[2001:db8:f0::1]" anchor="coap://[2001:db8:f0::1]"
Figure 33: Example payload of a response to a resource lookup
This is not _literally_ the same response that it would have received This is not _literally_ the same response that it would have received
from a multicast request, but it contains the equivalent statement: from a multicast request, but it contains the equivalent statement:
'"coap://[2001:db8:f0::1]" is hosting the resource '"coap://[2001:db8:f0::1]" is hosting the resource
"coap://[2001:db8:f0::1]/temp", which is of the resource type "coap://[2001:db8:f0::1]/temp", which is of the resource type
"temperature" and can be accessed using the text/plain content "temperature" and can be accessed using the text/plain content
format.' format.'
(The difference is whether "/" or "/.well-known/core" hosts the (The difference is whether "/" or "/.well-known/core" hosts the
resources, which does not matter in this application; if it did, the resources, which does not matter in this application; if it did, the
skipping to change at page 71, line 4 skipping to change at page 73, line 36
(The difference is whether "/" or "/.well-known/core" hosts the (The difference is whether "/" or "/.well-known/core" hosts the
resources, which does not matter in this application; if it did, the resources, which does not matter in this application; if it did, the
endpoint would have been more explicit. Actually, /.well-known/core endpoint would have been more explicit. Actually, /.well-known/core
does NOT host the resource but stores a URI reference to the does NOT host the resource but stores a URI reference to the
resource.) resource.)
To complete the examples, the client could also query all resources To complete the examples, the client could also query all resources
hosted at the endpoint with the known endpoint name "simple-host1". hosted at the endpoint with the known endpoint name "simple-host1".
A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1" A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1"
would return would return
<coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0; <coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0;
anchor="coap://[2001:db8:f0::1]", anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0; <coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0;
anchor="coap://[2001:db8:f0::1]", anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/t>; <coap://[2001:db8:f0::1]/t>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>; <http://www.example.com/sensors/t123>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby" anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby"
Figure 34: Extended example payload of a response to a resource
lookup
All the target and anchor references are already in absolute form All the target and anchor references are already in absolute form
there, which don't need to be resolved any further. there, which don't need to be resolved any further.
Had the simple host done an equivalent full registration with a base= Had the simple host done an equivalent full registration with a base=
parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple- parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple-
host1.example.com"), that context would have been used to resolve the host1.example.com"), that context would have been used to resolve the
relative anchor values instead, giving relative anchor values instead, giving
<coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0; <coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0;
anchor="coap+tcp://simple-host1.example.com" anchor="coap+tcp://simple-host1.example.com"
Figure 35: Example payload of a response to a resource lookup with a
dedicated base URI
and analogous records. and analogous records.
B.4. A note on differences between link-format and Link headers B.4. A note on differences between link-format and Link headers
While link-format and Link headers look very similar and are based on While link-format and Link headers look very similar and are based on
the same model of typed links, there are some differences between the same model of typed links, there are some differences between
[RFC6690] and [RFC8288], which are dealt with differently: [RFC6690] and [RFC8288], which are dealt with differently:
o "Resolving the target against the anchor": [RFC6690] Section 2.1 o "Resolving the target against the anchor": [RFC6690] Section 2.1
states that the anchor of a link is used as the Base URI against states that the anchor of a link is used as the Base URI against
 End of changes. 61 change blocks. 
95 lines changed or deleted 187 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/