rfc9176v7.txt   rfc9176.txt 
Internet Engineering Task Force (IETF) C. Amsüss, Ed. Internet Engineering Task Force (IETF) C. Amsüss, Ed.
Request for Comments: 9176 Request for Comments: 9176
Category: Standards Track Z. Shelby Category: Standards Track Z. Shelby
ISSN: 2070-1721 Edge Impulse ISSN: 2070-1721 Edge Impulse
M. Koster M. Koster
PassiveLogic PassiveLogic
C. Bormann C. Bormann
Universitaet Bremen TZI Universität Bremen TZI
P. van der Stok P. van der Stok
vanderstok consultancy vanderstok consultancy
March 2022 April 2022
Constrained RESTful Environments (CoRE) Resource Directory Constrained RESTful Environments (CoRE) Resource Directory
Abstract Abstract
In many Internet of Things (IoT) applications, direct discovery of In many Internet of Things (IoT) applications, direct discovery of
resources is not practical due to sleeping nodes or networks where resources is not practical due to sleeping nodes 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
skipping to change at line 94 skipping to change at line 94
5.3.3. Further Operations 5.3.3. Further Operations
5.3.4. Request Freshness 5.3.4. Request Freshness
6. RD Lookup 6. RD Lookup
6.1. Resource Lookup 6.1. Resource Lookup
6.2. Lookup Filtering 6.2. Lookup Filtering
6.3. Resource Lookup Examples 6.3. Resource Lookup Examples
6.4. Endpoint Lookup 6.4. Endpoint Lookup
7. Security Policies 7. Security Policies
7.1. Endpoint Name 7.1. Endpoint Name
7.1.1. Random Endpoint Names 7.1.1. Random Endpoint Names
7.2. Entered Resources 7.2. Entered Links
7.3. Link Confidentiality 7.3. Link Confidentiality
7.4. Segmentation 7.4. Segmentation
7.5. "First Come First Remembered": A Default Policy 7.5. "First Come First Remembered": A Default Policy
8. Security Considerations 8. Security Considerations
8.1. Discovery 8.1. Discovery
8.2. Endpoint Identification and Authentication 8.2. Endpoint Identification and Authentication
8.3. Access Control 8.3. Access Control
8.4. Denial-of-Service Attacks 8.4. Denial-of-Service Attacks
8.5. Skipping Freshness Checks 8.5. Skipping Freshness Checks
9. IANA Considerations 9. IANA Considerations
skipping to change at line 516 skipping to change at line 516
Therefore, it is advisable in many scenarios to use addresses with Therefore, it is advisable in many scenarios to use addresses with
larger scopes, if available. larger scopes, if available.
3.5. Use Case: Cellular M2M 3.5. Use Case: Cellular M2M
Over the last few years, mobile operators around the world have Over the last few years, mobile operators around the world have
focused on development of M2M solutions in order to expand the focused on development of M2M solutions in order to expand the
business to the new type of users: machines. The machines are business to the new type of users: machines. The machines are
connected directly to a mobile network using an appropriate embedded connected directly to a mobile network using an appropriate embedded
wireless interface (GSM/General Packet Radio Service (GPRS), Wideband wireless interface (GSM/General Packet Radio Service (GPRS), Wideband
Code Division Multiple Access (W-CDMA), LTE) or via a gateway Code Division Multiple Access (W-CDMA), LTE, etc.) or via a gateway
providing short- and wide-range wireless interfaces. The ambition in providing short- and wide-range wireless interfaces. The ambition in
such systems is to build them from reusable components. These speed such systems is to build them from reusable components. These speed
up development and deployment and enable shared use of machines up development and deployment and enable shared use of machines
across different applications. One crucial component of such systems across different applications. One crucial component of such systems
is the discovery of resources (and thus the endpoints they are hosted is the discovery of resources (and thus the endpoints they are hosted
on) capable of providing required information at a given time or on) capable of providing required information at a given time or
acting on instructions from the end users. acting on 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
skipping to change at line 587 skipping to change at line 587
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 an RD. Applications wishing links to sensor data may be published to an RD. Applications wishing
to consume the data can use RD lookup to discover and resolve links to consume the data can use RD lookup to discover and resolve links
to the desired resources and endpoints. The RD service need not be to the desired resources and endpoints. The RD service need not be
coupled with the data intermediary service. Mapping of RDs to data coupled with the data intermediary service. Mapping of RDs to data
intermediaries may be many-to-many. intermediaries may be many-to-many.
Metadata in web link formats like the one defined in [RFC6690], which Metadata in web link formats, such as the one defined in [RFC6690],
may be internally stored as triples or relation/attribute pairs which may be internally stored as triples or relation/attribute pairs
providing metadata about resource links, need to be supported by RDs. providing metadata about resource links, need to be supported by RDs.
External catalogues that are represented in other formats may be External catalogues that are represented in other formats may be
converted to common web linking formats for storage and access by converted to common web linking formats for storage and access by
RDs. Since it is common practice for these to be encoded in URNs RDs. Since it is common practice for these to be encoded in URNs
[RFC8141], simple and lossless structural transforms should generally [RFC8141], simple and lossless structural transforms should generally
be sufficient to store external metadata in RDs. be sufficient to store external metadata in RDs.
The additional features of an RD allow sectors to be defined to The additional features of an RD allow sectors to be defined to
enable access to a particular set of resources from particular enable access to a particular set of resources from particular
applications. This provides isolation and protection of sensitive applications. This provides isolation and protection of sensitive
skipping to change at line 624 skipping to change at line 624
interfaces. interfaces.
All operations on the contents of the RD MUST be atomic and All operations on the contents of the RD MUST be 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 for options (like Content-Format) and for The additional sections for options (such as Content-Format) and for
Failure codes give typical cases that an implementation of the RD Failure codes give typical cases that an implementation of the RD
should deal with. Those serve to illustrate the typical responses to should deal with. Those serve to illustrate the typical responses to
readers who are not yet familiar with all the details of CoAP-based readers who are not yet familiar with all the details of CoAP-based
interfaces; they do not limit how a server may respond under atypical interfaces; they do not limit how a server may respond under atypical
circumstances. circumstances.
REST clients (registrant-EPs and CTs during registration and REST clients (registrant-EPs and CTs during registration and
maintenance, lookup clients, and RD servers during simple maintenance, lookup clients, and RD servers during simple
registrations) must be prepared to receive any unsuccessful code and registrations) must be prepared to receive any unsuccessful code and
act upon it according to its definition, options, and/or payload to act upon it according to its definition, options, and/or payload to
skipping to change at line 835 skipping to change at line 835
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 is performed by sending either a Discovery of the RD registration URI is performed by sending either a
multicast or unicast GET request to /.well-known/core and including a multicast or unicast GET request to /.well-known/core and including a
resource type (rt) parameter [RFC6690] with the value "core.rd" in resource type (rt) parameter [RFC6690] with the value "core.rd" in
the query string. Likewise, a resource type parameter value of the query string. Likewise, a resource type parameter value of
"core.rd-lookup*" is used to discover the URIs for RD lookup "core.rd-lookup*" is used to discover the URIs for RD lookup
operations, and core.rd* is used to discover all URIs for RD operations, and "core.rd*" is used to discover all URIs 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).
An RD MAY provide hints about the content formats it supports in the An RD MAY provide hints about the content formats it supports in the
links it exposes or registers, using the "ct" target attribute, as links it exposes or registers, using the "ct" target attribute, as
shown in the example below. Clients MAY use these hints to select shown in the example below. Clients MAY use these hints to select
skipping to change at line 869 skipping to change at line 869
With security policies where the client requires the RD to be With security policies where the client requires the RD to be
authorized to act as an RD, that authorization may be limited to authorized to act as an RD, that authorization may be limited to
resources on which the authorized RD advertises the adequate resource resources on which the authorized RD advertises the adequate resource
types. Clients that have obtained links they cannot rely on yet can types. Clients that have obtained links they cannot rely on yet can
repeat the "URI discovery" step at the /.well-known/core resource of repeat the "URI discovery" step at the /.well-known/core resource of
the indicated host to obtain the resource type information from an the indicated host to obtain the resource type information from an
authorized source. authorized source.
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 try out any of the
addresses initially. discovered addresses.
The discovery request interface is specified as follows (this is The discovery request interface is specified as follows (this is
exactly the well-known interface of [RFC6690], Section 4, with the exactly the well-known interface of [RFC6690], Section 4, with the
additional requirement that the server MUST support query filtering): additional requirement that the server MUST support query filtering):
Interaction: EP, CT, or Client -> RD Interaction: EP, CT, or Client -> RD
Method: GET Method: GET
URI Template: /.well-known/core{?rt} URI Template: /.well-known/core{?rt}
skipping to change at line 930 skipping to change at line 930
in the style of [CORE-LINKS-JSON] (for which the experimental values in the style of [CORE-LINKS-JSON] (for which the experimental values
65060 and 65050 are used in this example). The RD resource locations 65060 and 65050 are used in this example). The RD resource locations
/rd and /rd-lookup are example values. The server in this example /rd and /rd-lookup are example values. The server in this example
also indicates that it is capable of providing observation on also indicates that it is capable of providing observation on
resource lookups. resource lookups.
Req: GET coap://[ff02::fe]/.well-known/core?rt=core.rd* Req: GET coap://[ff02::fe]/.well-known/core?rt=core.rd*
Res: 2.05 Content Res: 2.05 Content
Payload: Payload:
</rd>;rt=core.rd;ct="40 65225", </rd>;rt=core.rd;ct=40,
</rd-lookup/res>;rt=core.rd-lookup-res;ct="40 65060 65050";obs, </rd-lookup/res>;rt=core.rd-lookup-res;ct="40 65060 65050";obs,
</rd-lookup/ep>;rt=core.rd-lookup-ep;ct="40 65060 65050" </rd-lookup/ep>;rt=core.rd-lookup-ep;ct="40 65060 65050"
Figure 6: Example Discovery Exchange Indicating Additional Figure 6: Example Discovery Exchange Indicating Additional
Content-Formats Content-Formats
For maintenance, management, and debugging, it can be useful to For maintenance, management, and debugging, it can be useful to
identify the components that constitute the RD server. The identify the components that constitute the RD server. The
identification can be used to find client-server incompatibilities, identification can be used to find client-server incompatibilities,
supported features, required updates, and other aspects. The well- supported features, required updates, and other aspects. The well-
skipping to change at line 995 skipping to change at line 995
The following rules apply for a registration request targeting a The following rules apply for a registration request targeting a
given (ep, d) value pair: given (ep, d) value pair:
* When the (ep, d) value pair of the registration request is * When the (ep, d) value pair of the registration request is
different from any existing registration, a new registration is different from any existing registration, a new registration is
generated. generated.
* When the (ep, d) value pair of the registration request is equal * When the (ep, d) value pair of the registration request is equal
to an existing registration, the content and parameters of the to an existing registration, the content and parameters of the
existing registration are replaced with the content of the existing registration are replaced with the content of the
registration request. Like the later changes to registration registration request. As with changes to registration resources,
resources, security policies (Section 7) usually require such security policies (Section 7) usually require such requests to
requests to come from the same device. come from the same device.
The posted link-format document can (and typically does) contain The posted link-format document can (and typically does) contain
relative references both in its link targets and in its anchors; it relative references both in its link targets and in its anchors; it
can also contain empty anchors. The RD server needs to resolve these can also contain empty anchors. The RD server needs to resolve these
references in order to faithfully represent them in lookups. They references in order to faithfully represent them in lookups. They
are resolved against the base URI of the registration, which is are resolved against the base URI of the registration, which is
provided either explicitly in the base parameter or constructed provided either explicitly in the base parameter or constructed
implicitly from the requester's URI, as constructed from its network implicitly from the requester's URI, as constructed from its network
address and scheme. address and scheme.
skipping to change at line 1029 skipping to change at line 1029
URI Template Variables: URI Template Variables:
rd := RD registration URI (mandatory). This is the location of rd := RD registration URI (mandatory). This is the location of
the RD, as obtained from discovery. the RD, as obtained from discovery.
ep := Endpoint name (mostly mandatory). The endpoint name is an ep := Endpoint name (mostly mandatory). The endpoint name is an
identifier that MUST be unique within a sector. identifier that MUST be unique within a sector.
As the endpoint name is a Unicode string, it is encoded in As the endpoint name is a Unicode string, it is encoded in
UTF-8 (and possibly encoded in pct) during variable expansion UTF-8 (and possibly percent encoded) during variable expansion
(see [RFC6570], Section 3.2.1). The endpoint name MUST NOT (see [RFC6570], Section 3.2.1). The endpoint name MUST NOT
contain any character in the inclusive ranges 0-31 or 127-159. contain any character in the inclusive ranges 0-31 or 127-159.
The maximum length of this parameter is 63 bytes encoded in The maximum length of this parameter is 63 bytes encoded in
UTF-8. UTF-8.
If the RD is configured to recognize the endpoint that is to be If the RD is configured to recognize the endpoint that is to be
authorized to use exactly one endpoint name, the RD assigns authorized to use exactly one endpoint name, the RD assigns
that name. In that case, giving the endpoint name becomes that name. In that case, giving the endpoint name becomes
optional for the client; if the client gives any other endpoint optional for the client; if the client gives any other endpoint
skipping to change at line 1198 skipping to change at line 1198
/.well-known/core interface, as specified in [RFC6690]. The links in /.well-known/core interface, as specified in [RFC6690]. The links in
that document are subject to the same limitations as the payload of a that document are subject to the same limitations as the payload of a
registration (with respect to Appendix C). registration (with respect to Appendix C).
* The registrant-EP finds one or more addresses of the directory * The registrant-EP finds one or more addresses of the directory
server, as described in Section 4.1. server, as described in Section 4.1.
* The registrant-EP sends (and regularly refreshes with) a POST * The registrant-EP sends (and regularly refreshes with) a POST
request to the /.well-known/rd URI of the directory server of request to the /.well-known/rd URI of the directory server of
choice. The body of the POST request is empty and triggers the choice. The body of the POST request is empty and triggers the
resource directory server to perform GET requests at the resource directory server to perform GET requests (redone before
requesting registrant-EP's /.well-known/core to obtain the link- lifetime expiry) at the requesting registrant-EP's /.well-known/
format payload to register. core to obtain the link-format payload to register.
The registrant-EP includes the same registration parameters in the The registrant-EP includes the same registration parameters in the
POST request as it would with a regular registration, per POST request as it would with a regular registration, per
Section 5. The registration base URI of the registration is taken Section 5. The registration base URI of the registration is taken
from the registrant-EP's network address (as is default with from the registrant-EP's network address (as is default with
regular registrations). regular registrations).
The following is an example request from the registrant-EP to the The following is an example request from the registrant-EP to the
RD (unanswered until the next step): RD (unanswered until the next step):
skipping to change at line 1313 skipping to change at line 1313
In a controlled environment (e.g., building control), the RD can be In a controlled environment (e.g., building control), the RD can be
filled by a third-party device, called a Commissioning Tool (CT). filled by a third-party device, called a Commissioning Tool (CT).
The CT can fill the RD from a database or other means. For that The CT can fill the RD from a database or other means. For that
purpose scheme, the IP address and port of the URI of the registered purpose scheme, the IP address and port of the URI of the registered
device is the value of the "base" parameter of the registration device is the value of the "base" parameter of the registration
described in Section 5. described in 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. A
eventual (currently nonexistent) "base" attribute of the link is not potential (currently nonexistent) "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. The registrations are resources of the RD. registrant-EP or the CT. The registrations are resources of the RD.
An endpoint should not use this interface for registrations that it An endpoint should not use this interface for registrations that it
did not create. This is usually enforced by security policies, did not create. This is usually enforced by security policies,
skipping to change at line 1357 skipping to change at line 1357
The operations on the registration resource are described below. The operations on the registration resource are described below.
5.3.1. Registration Update 5.3.1. Registration Update
The update interface is used by the registering endpoint to refresh The update interface is used by the registering endpoint to refresh
or update its registration with an RD. To use the interface, the or update its registration with an RD. To use the interface, the
registering endpoint sends a POST request to the registration registering endpoint sends a POST request to the registration
resource returned by the initial registration operation. resource returned by the initial registration operation.
An update MAY update registration parameters like lifetime, base URI, An update MAY update registration parameters, such as lifetime, base
or others. Parameters that are not being changed should not be URI, or others. Parameters that are not being changed should not be
included in an update. Adding parameters that have not changed included in an update. Adding parameters that have not changed
increases the size of the message but does not have any other increases the size of the message but does not have any other
implications. Parameters are included as query parameters in an implications. Parameters are included as query parameters in an
update operation, as in Section 5. update operation, as in Section 5.
A registration update resets the timeout of the registration to the A registration update resets the timeout of the registration to the
(possibly updated) lifetime of the registration, independent of (possibly updated) lifetime of the registration, independent of
whether an lt parameter was given. whether an lt parameter was given.
If the base URI of the registration is changed in an update, relative If the base URI of the registration is changed in an update, relative
skipping to change at line 1571 skipping to change at line 1571
This ordering of operations is expressed in terms of freshness, as This ordering of operations is expressed in terms of freshness, as
defined in [RFC9175]. Requests that alter a resource's state need to defined in [RFC9175]. Requests that alter a resource's state need to
be fresh relative to the latest request that altered that state in a be fresh relative to the latest request that altered that state in a
conflicting way. conflicting way.
An RD SHOULD determine a request's freshness and MUST use the Echo An RD SHOULD determine a request's freshness and MUST use the Echo
option if it requires request freshness and cannot determine it in option if it requires request freshness and cannot determine it in
any other way. An endpoint MUST support the use of the Echo option. any other way. An endpoint MUST support the use of the Echo option.
(One reason why an RD would not require freshness is when no relevant (One reason why an RD would not require freshness is when no relevant
registration properties are covered by is security policies.) registration properties are covered by its security policies.)
5.3.4.1. Efficient Use of Echo by an RD 5.3.4.1. Efficient Use of Echo by an RD
To keep latency and traffic added by the freshness requirements to a To keep latency and traffic added by the freshness requirements to a
minimum, RDs should avoid naive (sufficient but inefficient) minimum, RDs should avoid naive (sufficient but inefficient)
freshness criteria. freshness criteria.
Some simple mechanisms the RD can employ are: Some simple mechanisms the RD can employ are:
* State counter. The RD can keep a monotonous counter that * State counter. The RD can keep a monotonous counter that
skipping to change at line 1666 skipping to change at line 1666
context- or semantic-based lookup) on different resources that are context- or semantic-based lookup) on different resources that are
discovered independently. discovered independently.
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 implemented by a lookup resource is indicated by a
a resource type, as per Table 1: resource type, as per Table 1:
+=============+====================+===========+ +=============+====================+===========+
| 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
skipping to change at line 1751 skipping to change at line 1751
starting with link zero and page zero. Thus, specifying a count of starting with link zero and page zero. Thus, specifying a count of
10 and page of 0 will return the first 10 links in the result set 10 and page of 0 will return the first 10 links in the result set
(links 0-9). Specifying a count of 10 and page of 1 will return the (links 0-9). Specifying a count of 10 and page of 1 will return the
next 'page' containing links 10-19, and so on. Unlike block-wise next 'page' containing links 10-19, and so on. Unlike block-wise
transfer of a complete result set, these parameters ensure that each transfer of a complete result set, these parameters ensure that each
chunk of results can be interpreted on its own. This simplifies the chunk of results can be interpreted on its own. This simplifies the
processing but can result in duplicate or missed items when processing but can result in duplicate or missed items when
coinciding with changes from the registration interface. coinciding with changes from the registration interface.
Endpoints that are interested in a lookup result repeatedly or Endpoints that are interested in a lookup result repeatedly or
continuously can use mechanisms like ETag caching, resource continuously can use mechanisms such as ETag caching, resource
observation [RFC7641], or any future mechanism that might allow more observation [RFC7641], or any future mechanism that might allow more
efficient observations of collections. These are advertised, efficient observations of collections. These are advertised,
detected, and used according to their own specifications and can be detected, and used according to their own specifications and can be
used with the lookup interface as with any other resource. used with the lookup interface as with any other resource.
When resource observation is used, every time the set of matching When resource observation is used, every time the set of matching
links changes or the content of a matching link changes, the RD sends links changes or the content of a matching link changes, the RD sends
a notification with the matching link set. The notification contains a notification with the matching link set. The notification contains
the successful current response to the given request, especially with the successful current response to the given request, especially with
respect to representing zero matching links (see "Success" item respect to representing zero matching links (see "Success" item
skipping to change at line 2007 skipping to change at line 2007
name, the authorized registering endpoint can generate a random name, the authorized registering endpoint can generate a random
number (or string) that identifies the endpoint. The RD should then number (or string) that identifies the endpoint. The RD should then
remember unique properties of the registrant, associate them with the remember unique properties of the registrant, associate them with the
registration for as long as its registration resource is active registration for as long as its registration resource is active
(which may be longer than the registration's lifetime), and require (which may be longer than the registration's lifetime), and require
the same properties for operations on the registration resource. the same properties for operations on the registration resource.
Registrants that are prepared to pick a different identifier when Registrants that are prepared to pick a different identifier when
their initial attempt (or attempts, in the unlikely case of two their initial attempt (or attempts, in the unlikely case of two
subsequent collisions) at registration is unauthorized should pick an subsequent collisions) at registration is unauthorized should pick an
identifier at least twice as long as the expected number of identifier at least twice as long as would be needed to enumerate the
registrants; registrants without any such recovery options should expected number of registrants; registrants without any such recovery
pick significantly longer endpoint names (e.g., using Universally options should pick significantly longer endpoint names (e.g., using
Unique Identifier (UUID) URNs [RFC4122]). Universally Unique Identifier (UUID) URNs [RFC4122]).
7.2. Entered Resources 7.2. Entered Links
When lookup clients expect that certain types of links can only When lookup clients expect that certain types of links can only
originate from certain endpoints, then the RD needs to apply originate from certain endpoints, then the RD needs to apply
filtering to the links an endpoint may register. filtering to the links an endpoint may register.
For example, if clients use an RD to find a server that provides For example, if clients use an RD to find a server that provides
firmware updates, then any registrant that wants to register (or firmware updates, then any registrant that wants to register (or
update) links to firmware sources will need to provide suitable update) links to firmware sources will need to provide suitable
credentials to do so, independently of its endpoint name. credentials to do so, independently of its endpoint name.
skipping to change at line 2085 skipping to change at line 2085
Care must be taken in such setups to determine the applicable access 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 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 mandate the use of the sector parameter on all operations, as no
credentials are suitable for operations across sector borders anyway. credentials are suitable for operations across sector borders anyway.
7.5. "First Come First Remembered": A Default Policy 7.5. "First Come First Remembered": A Default Policy
The "First Come First Remembered" policy is provided both as a The "First Come First Remembered" policy is provided both as a
reference example for a security policy definition and as a policy reference example for a security policy definition and as a policy
that implementations may choose to use as default policy in the that implementations may choose to use as default policy in the
absence of another configuration. It is designed to enable efficient absence of any other configuration. It is designed to enable
discovery operations even in ad hoc settings. efficient discovery operations even in ad hoc settings.
Under this policy, the RD accepts registrations for any endpoint name Under this policy, the RD accepts registrations for any endpoint name
that is not assigned to an active registration resource and only that is not assigned to an active registration resource and only
accepts registration updates from the same endpoint. The policy is accepts registration updates from the same endpoint. The policy is
minimal in that it does not make any promises to lookup clients about minimal in that it does not make any promises to lookup clients about
the claims of Sections 7.2 and 7.3, and promises about the claims in the claims of Sections 7.2 and 7.3, and promises about the claims in
Section 7.1 are limited to the lifetime of that endpoint's Section 7.1 are limited to the lifetime of that endpoint's
registration. It does however promise the endpoint that, for the registration. It does however promise the endpoint that, for the
duration of its registration, its links will be discoverable on the duration of its registration, its links will be discoverable on the
RD. RD.
skipping to change at line 2177 skipping to change at line 2177
8.1. Discovery 8.1. Discovery
Most steps in discovery of the RD, and possibly its resources, are Most steps in discovery of the RD, and possibly its resources, are
not covered by CoAP's security mechanisms. This will not endanger not covered by CoAP's security mechanisms. This will not endanger
the security properties of the registrations and lookup itself (where the security properties of the registrations and lookup itself (where
the client requires authorization of the RD if it expects any the client requires authorization of the RD if it expects any
security properties of the operation) but may leak the client's security properties of the operation) but may leak the client's
intention to third parties and allow them to slow down the process. intention to third parties and allow them to slow down the process.
To mitigate that, clients can retain the RD's address, use secure To mitigate that, clients can retain the RD's address, use secure
discovery options like configured addresses, and send queries for RDs discovery options (such as configured addresses), and send queries
in a very general form (e.g., ?rt=core.rd* rather than ?rt=core.rd- for RDs in a very general form (e.g., ?rt=core.rd* rather than
lookup-ep). ?rt=core.rd-lookup-ep).
8.2. Endpoint Identification and Authentication 8.2. Endpoint Identification and Authentication
An endpoint (name, sector) pair is unique within the set 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 protocol, port, or IP address, as these may change over the lifetime
of an endpoint. of an endpoint.
Every operation performed by an endpoint on an RD SHOULD be mutually Every operation performed by an endpoint on an RD SHOULD be mutually
authenticated using a pre-shared key, a raw public key, or authenticated using a pre-shared key, a raw public key, or
skipping to change at line 2221 skipping to change at line 2221
Simple registration could be used to circumvent address-based access Simple registration could be used to circumvent address-based access
control. An attacker would send a simple registration request with control. An attacker would send a simple registration request with
the victim's address as the source address and later look up the the victim's address as the source address and later look up the
victim's /.well-known/core content in the RD. Mitigation for this is victim's /.well-known/core content in the RD. Mitigation for this is
recommended in Section 5.1. recommended in Section 5.1.
The registration resource path is visible to any client that is The registration resource path is visible to any client that is
allowed endpoint lookup and can be extracted by resource lookup allowed endpoint lookup and can be extracted by resource lookup
clients as well. The same goes for registration attributes that are clients as well. The same goes for registration attributes that are
shown as target attributes or lookup attributes. The RD needs to shown as target attributes or lookup attributes. The RD needs to
consider this in the choice of registration resource paths and consider this in the choice of registration resource paths, as do
administrators or endpoint in their choice of attributes. administrators or endpoints in their choice of attributes.
8.3. Access Control 8.3. 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 look up endpoints from register with an RD from those authorized to look up 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 line 2392 skipping to change at line 2392
+--------------+-------+--------------+-----+---------------------+ +--------------+-------+--------------+-----+---------------------+
Table 4: New RD Parameters Registry Table 4: New RD Parameters Registry
Where: Where:
Short: Short name used in query parameters or target attributes Short: Short name used in query parameters or target attributes
Validity: Validity:
Unicode* = 63 bytes of UTF-8-encoded Unicode, with no control Unicode* = up to 63 bytes of UTF-8-encoded Unicode, with no
characters as per Section 5 control characters as per Section 5
Use: Use:
R = used at registration R = used at registration
L = used at lookup L = used at lookup
A = expressed in the target attribute A = expressed in the 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 are described in the respective sections of this to be shown are described in the respective sections of this
skipping to change at line 2546 skipping to change at line 2546
10.1. Lighting Installation 10.1. Lighting Installation
This example shows a simplified lighting installation that makes use This example shows a simplified lighting installation that makes use
of the RD with a CoAP interface to facilitate the installation and of the RD with a CoAP interface to facilitate the installation and
startup of the application code in the lights and sensors. In startup of the application code in the lights and sensors. In
particular, the example leads to the definition of a group and the particular, the example leads to the definition of a group and the
enabling of the corresponding multicast address, as described in enabling of the corresponding multicast address, as described in
Appendix A. No conclusions must be drawn on the realization of Appendix A. No conclusions must be drawn on the realization of
actual installation or naming procedures, because the example only actual installation or naming procedures, because the example only
"emphasizes" some of the issues that may influence the use of the RD emphasizes some of the issues that may influence the 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 Wi-Fi to the installation network, installation network, connected by Wi-Fi to the installation network,
connected via GPRS link, or connected by another method. connected via GPRS link, or connected by another method.
skipping to change at line 2742 skipping to change at line 2742
sensor learns the multicast address to use for sending messages to sensor learns the multicast address to use for sending messages to
the luminaries. the luminaries.
10.2. OMA Lightweight M2M (LwM2M) 10.2. OMA Lightweight M2M (LwM2M)
OMA LwM2M is a profile for device services based on CoAP, providing OMA LwM2M is a profile for device services based on CoAP, providing
interfaces and operations for device management and device service interfaces and operations for device management and device service
enablement. 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 an RD ([LwM2M], page 36f). containing an RD ([LwM2M], starting at page 36).
That RD only implements the registration interface, and no lookup is That RD only implements the registration interface, and no lookup is
implemented. Instead, the LwM2M server provides access to the implemented. Instead, the LwM2M server provides access to the
registered resources in a similar way to a reverse proxy. registered resources in a similar way to a reverse proxy.
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
LwM2M bootstrap process, so no dynamic discovery of the RD is used. LwM2M bootstrap process, so no dynamic discovery of the RD is used.
LwM2M servers and endpoints are not required to implement the /.well- LwM2M servers and endpoints are not required to implement the /.well-
known/core resource. known/core resource.
skipping to change at line 2814 skipping to change at line 2814
"Constrained Application Protocol (CoAP): Echo, Request- "Constrained Application Protocol (CoAP): Echo, Request-
Tag, and Token Processing", RFC 9175, Tag, and Token Processing", RFC 9175,
DOI 10.17487/RFC9175, February 2022, DOI 10.17487/RFC9175, February 2022,
<https://www.rfc-editor.org/info/rfc9175>. <https://www.rfc-editor.org/info/rfc9175>.
11.2. Informative References 11.2. Informative References
[ACE-OAUTH-AUTHZ] [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 Using the OAuth 2.0 Framework
Framework (ACE-OAuth)", Work in Progress, Internet-Draft, (ACE-OAuth)", Work in Progress, Internet-Draft, draft-
draft-ietf-ace-oauth-authz-46, 8 November 2021, ietf-ace-oauth-authz-46, 8 November 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-ace- <https://datatracker.ietf.org/doc/html/draft-ietf-ace-
oauth-authz-46>. oauth-authz-46>.
[COAP-PROT-NEG] [COAP-PROT-NEG]
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,
<https://datatracker.ietf.org/doc/html/draft-silverajan- <https://datatracker.ietf.org/doc/html/draft-silverajan-
core-coap-protocol-negotiation-09>. core-coap-protocol-negotiation-09>.
skipping to change at line 3050 skipping to change at line 3050
Req: GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature Req: GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature
Res: 2.05 Content Res: 2.05 Content
Payload: Payload:
</sensors/temp>;rt=temperature;ct=0 </sensors/temp>;rt=temperature;ct=0
Figure 30: Example of Direct Resource Discovery 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 While a practical client side implementation might just go ahead and
just go ahead and create a new request to [2001:db8:f0::1]:5683 with create a new request to [2001:db8:f0::1]:5683 with Uri-Path sensors
Uri-Path sensors and temp, the full resolution steps for insertion and temp, the full resolution steps for insertion into and retrieval
into and retrieval from the RD without any shortcuts are as follows. from the RD without any shortcuts are as follows.
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 link. Its target (sometimes
(sometimes called "href") is /sensors/temp, which is a relative URI called "href") is /sensors/temp, which is a relative URI that needs
that needs resolving. The base URI coap://[ff02::fd]:5683/.well- resolving. The base URI coap://[ff02::fd]:5683/.well-known/core is
known/core is used to resolve the reference against /sensors/temp. used to resolve the reference against /sensors/temp.
The base URI of the requested resource can be composed from the The base URI of the requested resource can be composed from the
options of the CoAP GET request by following the steps of [RFC7252], options of the CoAP GET request by following the steps of [RFC7252],
Section 6.5 (with an addition at the end of Section 8.2) into Section 6.5 (with an addition at the end of Section 8.2) into
coap://[2001:db8:f0::1]/.well-known/core. coap://[2001:db8:f0::1]/.well-known/core.
Because /sensors/temp starts with a single slash, the record's target Because /sensors/temp starts with a single slash, the link's target
is resolved by replacing the path /.well-known/core from the base URI is resolved by replacing the path /.well-known/core from the base URI
([RFC3986], Section 5.2) with the relative target URI /sensors/temp ([RFC3986], Section 5.2) with the relative target URI /sensors/temp
into coap://[2001:db8:f0::1]/sensors/temp. into coap://[2001:db8:f0::1]/sensors/temp.
B.1.2. Interpreting Attributes and Relations B.1.2. Interpreting Attributes and Relations
Some more information about the record's target can be obtained from Some more information about the link's target can be obtained from
the payload: the resource type of the target is "temperature", and the payload: the resource type of the target is "temperature", and
its content format is text/plain (ct=0). its content format is text/plain (ct=0).
A relation in a web link is a three-part statement that specifies a A relation in a web link is a three-part statement that specifies a
named relation between the so-called "context resource" and the named relation between the so-called "context resource" and the
target resource, like "_This page_ has _its table of contents_ at _/ target resource, like "_This page_ has _its table of contents_ at _/
toc.html_". In link-format documents, there is an implicit "host toc.html_". In link-format documents, there is an implicit "host
relation" specified with default parameter rel="hosts". relation" specified with default parameter rel="hosts".
In our example, the context resource of the link is implied to be In our example, the context resource of the link is implied to be
coap:://[2001:db8:f0::1] by the default value of the anchor (see coap:://[2001:db8:f0::1] by the default value of the anchor (see
Appendix B.4). A full English expression of the "host relation" is: Appendix B.4). A full English expression of the "host relation" is:
coap://[2001:db8:f0::1] is hosting the resource coap://[2001:db8:f0::1] is hosting the resource
coap://[2001:db8:f0::1]/sensors/temp, which is of the resource coap://[2001:db8:f0::1]/sensors/temp, which is of the resource
type "temperature" and can be accessed using the text/plain type "temperature" and can be read in the text/plain content
content format. format.
B.2. A Slightly More Complex Example B.2. A Slightly More Complex Example
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 links in the payload:
Req: GET coap://[ff02::fd]:5683/.well-known/core Req: GET coap://[ff02::fd]:5683/.well-known/core
Res: 2.05 Content Res: 2.05 Content
Payload: Payload:
</sensors/temp>;rt=temperature;ct=0, </sensors/temp>;rt=temperature;ct=0,
</sensors/light>;rt=light-lux;ct=0, </sensors/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="/sensors/temp";
rel=describedby rel=describedby
Figure 31: Extended Example of Direct Resource Discovery Figure 31: Extended Example of Direct Resource Discovery
Parsing the third record, the client encounters the "anchor" Parsing the third link, the client encounters the "anchor" parameter.
parameter. It is a URI relative to the base URI of the request and It is a URI relative to the base URI of the request and is thus
is thus resolved to coap://[2001:db8:f0::1]/sensors/temp. That is resolved to coap://[2001:db8:f0::1]/sensors/temp. That is the
the context resource of the link, so the "rel" statement is not about context resource of the link, so the "rel" statement is not about the
the target and the base URI any more but about the target and the target and the base URI any more but about the target and the
resolved URI. Thus, the third record could be read as: resolved URI. Thus, the third link 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 link 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 RD tries to carry the semantics obtainable by classical CoAP The RD tries to carry the semantics obtainable by classical CoAP
discovery over to the resource lookup interface as faithfully as discovery over to the resource lookup interface 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
skipping to change at line 3193 skipping to change at line 3193
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=describedby anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=describedby
Figure 34: Extended Example Exchange Performing Resource Lookup Figure 34: Extended Example Exchange Performing 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://sh1.example.com), parameter (e.g., ?ep=simple-host1&base=coap+tcp://sh1.example.com),
that context would have been used to resolve the relative anchor that context would have been used to resolve the relative anchor
values instead, giving the following and analogous records: values instead, giving the following and analogous links:
<coap+tcp://sh1.example.com/sensors/temp>;rt=temperature;ct=0 <coap+tcp://sh1.example.com/sensors/temp>;rt=temperature;ct=0
Figure 35: Example Payload of a Response to a Resource Lookup Figure 35: Example Payload of a Response to a Resource Lookup
with a Dedicated Base URI with a Dedicated Base URI
B.4. A Note on Differences between Link-Format and Link Header Fields B.4. A Note on Differences between Link-Format and Link Header Fields
While link-format and Link header fields look very similar and are While link-format and Link header fields look very similar and are
based on the same model of typed links, there are some differences based on the same model of typed links, there are some differences
skipping to change at line 3262 skipping to change at line 3262
RD 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 the Limited Link Format if, for A link format representation is in the Limited Link Format if, for
each link in it, the following applies: each 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, the target and anchor each either start with rule of [RFC3986] (i.e., the target and anchor each either start with
a scheme or with a single slash). a scheme or with a single slash).
Acknowledgments 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 Kovatsch, Jaime Jimenez, and Ted Lemon have provided helpful
comments, discussions, and ideas to improve and shape this document. comments, discussions, and ideas to improve and shape this document.
Zach would also like to thank his colleagues from the EU FP7 SENSEI Zach would also like to thank his colleagues from the EU FP7 SENSEI
skipping to change at line 3296 skipping to change at line 3296
Michael Koster Michael Koster
PassiveLogic PassiveLogic
524 H Street 524 H Street
Antioch, CA 94509 Antioch, CA 94509
United States of America United States of America
Phone: +1-707-502-5136 Phone: +1-707-502-5136
Email: michaeljohnkoster@gmail.com Email: michaeljohnkoster@gmail.com
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universität Bremen TZI
Postfach 330440 Postfach 330440
D-28359 Bremen D-28359 Bremen
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org Email: cabo@tzi.org
Peter van der Stok Peter van der Stok
vanderstok consultancy vanderstok consultancy
Email: stokcons@bbhmail.nl Email: stokcons@bbhmail.nl
 End of changes. 37 change blocks. 
68 lines changed or deleted 68 lines changed or added

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