Constrained RESTful Environments (CoRE) Resource Directory
Extracted elements (31)
Registrations are soft state and must be periodically refreshed rather than being persistent. This design tolerates node failures and network partitions gracefully: a registration that is not refreshed automatically expires, keeping the RD consistent without explicit cleanup from crashed nodes.
Simple registration (POST to /.well-known/rd with empty body, RD fetches /.well-known/core) exists because many constrained devices cannot implement the full link-upload registration. The RD fetches links directly from the device rather than requiring the device to push them.
Although all examples use CoAP, the RD REST interfaces can equally be realized using HTTP. Multicast discovery and simple registration are exceptions: they rely on CoAP-specific mechanisms unavailable in HTTP, so only unicast discovery is supported over HTTP.
A registrant-EP that uses an ephemeral port to register MUST include the base parameter in the registration to provide a valid network path. A registrant behind NAT MUST provide a reachable base address.
A successful registration response MUST include a Location-Path option (or Location header for HTTP) containing a stable identifier generated by the RD. The location MUST NOT have a query or fragment component, and the Location-Query option MUST NOT be present.
An endpoint lookup MUST return a list of endpoints, and a resource lookup MUST return a list of links to resources. The RD MUST support matching with multiple search criteria, all of which must match for a link to be returned.
An RD implementing this specification MUST implement simple registration. Registrants MUST be able to serve a GET request to /.well-known/core after having requested simple registration. The RD MUST delete simple registrations after their lifetime expires.
An RD implementing this specification MUST support the discovery, registration, update, lookup, and removal interfaces. All operations on the contents of the RD MUST be atomic and idempotent.
An RD SHOULD determine a request's freshness and MUST use the Echo option if it requires request freshness and cannot determine it in any other way. An endpoint MUST support the use of the Echo option.
Endpoints MUST make use of any error messages to very strictly rate-limit requests to candidate RD IP addresses that do not work out, to avoid flooding unresponsive hosts during RD discovery.
If the base URI of a registration contains a link-local address, the RD MUST NOT show its links unless the lookup was made from the link on which the registered endpoint can be reached. The RD MUST NOT include zone identifiers in resolved URIs.
RDs implementing this specification MUST support the application/link-format content format (ct=40). Additional content formats MAY be supported, but SHOULD be able to express all information expressible in link format.
The endpoint name MUST be unique within a sector, MUST NOT contain characters in the inclusive ranges 0–31 or 127–159, and is limited to 63 bytes encoded in UTF-8.
The registration interface MUST be implemented to be idempotent: registering twice with the same endpoint parameters ep and d (sector) does not create multiple registration resources; the existing registration is replaced instead.
Link confidentiality: the set of links stored in the RD may reveal sensitive information about devices and their capabilities. The RD SHOULD enforce access control on lookup so that only authorized clients can discover registered resources. Segmentation via sectors is one mechanism.
A registration resource in the RD has six attribute types: endpoint name (ep, Unicode string unique within sector), registration base URI (base), lifetime (lt), registration resource location (href), optional sector (d), and optional additional endpoint attributes. Links registered by the endpoint are also stored in the registration.
Endpoint lookup returns links to registration resources annotated with ep, d (if present), base, and rt=core.rd-ep. Lifetime (lt) is not reported. Clients SHOULD NOT attempt to dereference or manipulate registration resource URIs obtained via endpoint lookup.
Registration removal is accomplished by sending DELETE to the registration resource location. The RD responds 2.02 (Deleted) or 404 (Not Found). Endpoints SHOULD explicitly remove registrations on shutdown rather than waiting for lifetime expiry.
Simple registration uses a POST to /.well-known/rd with an empty body; the RD then performs a GET to the registrant's /.well-known/core to obtain links. No registration location is returned, so subsequent management operations are unavailable.
The RD lookup interface is a GET to the type-specific lookup URI with optional search criteria (attribute filters), page, and count query parameters for pagination. Both resource lookup (core.rd-lookup-res) and endpoint lookup (core.rd-lookup-ep) are mandatory.
The registration interface accepts a POST to the RD URI with query parameters ep (endpoint name), d (sector), lt (lifetime, default 90000 seconds), base (base URI), and extra-attrs. The body carries the list of links in CoRE Link Format or equivalent.
The registration update interface is a POST to the registration resource location returned at initial registration. It resets the registration timeout and may update lt, base URI, or extra-attrs query parameters; parameters not being changed should be omitted.
A new IPv6 Neighbor Discovery option type 41 (Resource Directory Address Option, RDAO) is registered. DNS-SD service names _core-rd._udp, _core-rd-dtls._udp, _core-rd._tcp, and _core-rd-tls._tcp are registered for RD discovery (Section 9.7). The well-known URI 'rd' is registered (Section 9.6).
A new 'RD Parameters' registry is defined (Section 9.3) for parameters used in registration and lookup queries. Each entry has a name, validity (for registration/lookup), use as endpoint attribute, and description. Initial entries include ep, d, lt, base, extra-attrs, and et.
An 'Endpoint Type (et=) RD Parameter Values' registry (Section 9.4) is defined for named endpoint types used as the et= parameter. A multicast address for RD CoAP discovery is registered in the IPv6 multicast address registry (Section 9.5).
Resource Types registry is updated with core.rd, core.rd-lookup-res, and core.rd-lookup-ep to identify the RD registration URI and lookup URIs during URI discovery via /.well-known/core.
Denial-of-service attacks: because the RD stores state on behalf of registrants, an attacker can exhaust memory by flooding registrations. Rate-limiting, authentication, and authorization at the RD are the primary mitigations.
Endpoint identification and authentication: the RD must ensure that a registrant is authorized to use the claimed endpoint name and sector, both at registration and for subsequent operations on the registration resource. CTs may carry credentials scoped to one or a range of endpoint names.
Skipping freshness checks allows replay attacks on registration updates: an attacker who captures an earlier registration update could re-submit it to revert state. The Echo option (Section 5.3.4) is the normative mechanism to enforce freshness.
A registration resource transitions through active (within lifetime), timed-out (lifetime expired but resource retained), and removed (garbage collected) states. When timed-out, the RD SHOULD NOT respond to discovery queries for the endpoint but SHOULD continue providing access to the registration resource to allow refresh.
The Resource Directory Address Option (RDAO) for IPv6 Neighbor Discovery has Type=41, Length=3 (24 bytes total), a 16-bit Reserved field (initialized to zero, ignored on receipt), a 32-bit Valid Lifetime in seconds, and a 128-bit RD Address (IPv6).