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