idnits 2.17.1 draft-ietf-core-resource-directory-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 07, 2016) is 2850 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-05 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft ARM 4 Intended status: Standards Track M. Koster 5 Expires: January 8, 2017 SmartThings 6 C. Bormann 7 Universitaet Bremen TZI 8 P. van der Stok 9 consultant 10 July 07, 2016 12 CoRE Resource Directory 13 draft-ietf-core-resource-directory-08 15 Abstract 17 In many M2M applications, direct discovery of resources is not 18 practical due to sleeping nodes, disperse networks, or networks where 19 multicast traffic is inefficient. These problems can be solved by 20 employing an entity called a Resource Directory (RD), which hosts 21 descriptions of resources held on other servers, allowing lookups to 22 be performed for those resources. This document specifies the web 23 interfaces that a Resource Directory supports in order for web 24 servers to discover the RD and to register, maintain, lookup and 25 remove resources descriptions. Furthermore, new link attributes 26 useful in conjunction with an RD are defined. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on January 8, 2017. 45 Copyright Notice 47 Copyright (c) 2016 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 65 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6 66 3.2. Use Case: Home and Building Automation . . . . . . . . . 7 67 3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7 68 4. Finding a Directory Server . . . . . . . . . . . . . . . . . 8 69 4.1. Resource Directory Address Option (RDAO) . . . . . . . . 9 70 5. Simple Registration . . . . . . . . . . . . . . . . . . . . . 10 71 5.1. Simple publishing to Resource Directory Server . . . . . 11 72 5.2. Third-party registration . . . . . . . . . . . . . . . . 12 73 6. Resource Directory Function Set . . . . . . . . . . . . . . . 12 74 6.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 13 75 6.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 13 76 6.3. Registration . . . . . . . . . . . . . . . . . . . . . . 15 77 6.4. Registration Update . . . . . . . . . . . . . . . . . . . 18 78 6.5. Registration Removal . . . . . . . . . . . . . . . . . . 20 79 6.6. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 21 80 6.7. Update Endpoint Links . . . . . . . . . . . . . . . . . . 22 81 7. Group Function Set . . . . . . . . . . . . . . . . . . . . . 24 82 7.1. Register a Group . . . . . . . . . . . . . . . . . . . . 24 83 7.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 26 84 8. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . 27 85 9. New Link-Format Attributes . . . . . . . . . . . . . . . . . 32 86 9.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 32 87 9.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 33 88 10. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 33 89 10.1. DNS-based Service discovery . . . . . . . . . . . . . . 33 90 10.2. mapping ins to . . . . . . . . . . . . . . . 34 91 10.3. Mapping rt to . . . . . . . . . . . . . . 35 92 10.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 35 93 10.5. TXT Record key=value strings . . . . . . . . . . . . . . 35 94 10.6. Importing resource links into DNS-SD . . . . . . . . . . 36 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 36 96 11.1. Endpoint Identification and Authentication . . . . . . . 37 97 11.2. Access Control . . . . . . . . . . . . . . . . . . . . . 37 98 11.3. Denial of Service Attacks . . . . . . . . . . . . . . . 37 99 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 100 12.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 38 101 12.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 38 102 12.3. IPv6 ND Resource Directory Address Option . . . . . . . 38 103 12.4. RD Parameter Registry . . . . . . . . . . . . . . . . . 38 104 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 39 105 13.1. Lighting Installation . . . . . . . . . . . . . . . . . 39 106 13.1.1. Installation Characteristics . . . . . . . . . . . . 40 107 13.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 41 108 13.1.3. DNS entries . . . . . . . . . . . . . . . . . . . . 44 109 13.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 44 110 13.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 45 111 13.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 46 112 13.2.3. Alternate Base URI . . . . . . . . . . . . . . . . . 48 113 13.2.4. LWM2M Update Endpoint Registration . . . . . . . . . 48 114 13.2.5. LWM2M De-Register Endpoint . . . . . . . . . . . . . 48 115 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48 116 15. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 49 117 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 118 16.1. Normative References . . . . . . . . . . . . . . . . . . 52 119 16.2. Informative References . . . . . . . . . . . . . . . . . 53 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 122 1. Introduction 124 The work on Constrained RESTful Environments (CoRE) aims at realizing 125 the REST architecture in a suitable form for the most constrained 126 nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and 127 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 128 applications such as smart energy and building automation. 130 The discovery of resources offered by a constrained server is very 131 important in machine-to-machine applications where there are no 132 humans in the loop and static interfaces result in fragility. The 133 discovery of resources provided by an HTTP Web Server is typically 134 called Web Linking [RFC5988]. The use of Web Linking for the 135 description and discovery of resources hosted by constrained web 136 servers is specified by the CoRE Link Format [RFC6690]. However, 137 [RFC6690] only describes how to discover resources from the web 138 server that hosts them by requesting "/.well-known/core". In many 139 M2M scenarios, direct discovery of resources is not practical due to 140 sleeping nodes, disperse networks, or networks where multicast 141 traffic is inefficient. These problems can be solved by employing an 142 entity called a Resource Directory (RD), which hosts descriptions of 143 resources held on other servers, allowing lookups to be performed for 144 those resources. 146 This document specifies the web interfaces that a Resource Directory 147 supports in order for web servers to discover the RD and to register, 148 maintain, lookup and remove resource descriptions. Furthermore, new 149 link attributes useful in conjunction with a Resource Directory are 150 defined. Although the examples in this document show the use of 151 these interfaces with CoAP [RFC7252], they can be applied in an 152 equivalent manner to HTTP [RFC7230]. 154 2. Terminology 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 158 "OPTIONAL" in this document are to be interpreted as described in 159 [RFC2119]. The term "byte" is used in its now customary sense as a 160 synonym for "octet". 162 This specification requires readers to be familiar with all the terms 163 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 164 should also be familiar with the terms and concepts discussed in 165 [RFC7252]. To describe the REST interfaces defined in this 166 specification, the URI Template format is used [RFC6570]. 168 This specification makes use of the following additional terminology: 170 Resource Directory 171 A web entity that stores information about web resources and 172 implements the REST interfaces defined in this specification for 173 registration and lookup of those resources. 175 Domain 176 In the context of a Resource Directory, a domain is a logical 177 grouping of endpoints. This specification assumes that the list 178 of Domains supported by an RD is pre-configured by that RD. When 179 a domain is exported to DNS, the domain value equates to the DNS 180 domain name. 182 Group 183 In the context of a Resource Directory, a group is a logical 184 grouping of endpoints for the purpose of group communications. 185 All groups within a domain are unique. 187 Endpoint 188 Endpoint (EP) is a term used to describe a web server or client in 189 [RFC7252]. In the context of this specification an endpoint is 190 used to describe a web server that registers resources to the 191 Resource Directory. An endpoint is identified by its endpoint 192 name, which is included during registration, and is unique within 193 the associated domain of the registration. 195 Commissioning Tool Commissioning Tool (CT) is a device that assists 196 during the installation of the network by assigning values to 197 parameters, naming endpoints and groups, or adapting the 198 installation to the needs of the applications. 200 3. Architecture and Use Cases 202 The resource directory architecture is illustrated in Figure 1. A 203 Resource Directory (RD) is used as a repository for Web Links 204 [RFC5988] about resources hosted on other web servers, which are 205 called endpoints (EP). An endpoint is a web server associated with a 206 scheme, IP address and port (called Context), thus a physical node 207 may host one or more endpoints. The RD implements a set of REST 208 interfaces for endpoints to register and maintain sets of Web Links 209 (called resource directory entries), and for clients to lookup 210 resources from the RD or maintain groups. Endpoints themselves can 211 also act as clients. An RD can be logically segmented by the use of 212 Domains. The domain an endpoint is associated with can be defined by 213 the RD or configured by an outside entity. This information 214 hierarchy is shown in Figure 2. 216 Endpoints are assumed to proactively register and maintain resource 217 directory entries on the RD, which are soft state and need to be 218 periodically refreshed. An endpoint is provided with interfaces to 219 register, update and remove a resource directory entry. Furthermore, 220 a mechanism to discover an RD using the CoRE Link Format [RFC6690] is 221 defined. It is also possible for an RD to proactively discover Web 222 Links from endpoints and add them as resource directory entries. A 223 lookup interface for discovering any of the Web Links held in the RD 224 is provided using the CoRE Link Format. 226 Registration Lookup, Group 227 Interface Interfaces 228 +----+ | | 229 | EP |---- | | 230 +----+ ---- | | 231 --|- +------+ | 232 +----+ | ----| | | +--------+ 233 | EP | ---------|-----| RD |----|-----| Client | 234 +----+ | ----| | | +--------+ 235 --|- +------+ | 236 +----+ ---- | | 237 | EP |---- | | 238 +----+ 240 Figure 1: The resource directory architecture. 242 +------------+ 243 | Domain | <-- Name 244 +------------+ 245 | | 246 | +------------+ 247 | | Group | <-- Name, Scheme, IP, Port 248 | +------------+ 249 | | 250 +------------+ 251 | Endpoint | <-- Name, Scheme, IP, Port 252 +------------+ 253 | 254 | 255 +------------+ 256 | Resource | <-- Target, Parameters 257 +------------+ 259 Figure 2: The resource directory information hierarchy. 261 3.1. Use Case: Cellular M2M 263 Over the last few years, mobile operators around the world have 264 focused on development of M2M solutions in order to expand the 265 business to the new type of users: machines. The machines are 266 connected directly to a mobile network using an appropriate embedded 267 air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short 268 and wide range wireless interfaces. From the system design point of 269 view, the ambition is to design horizontal solutions that can enable 270 utilization of machines in different applications depending on their 271 current availability and capabilities as well as application 272 requirements, thus avoiding silo like solutions. One of the crucial 273 enablers of such design is the ability to discover resources 274 (machines -- endpoints) capable of providing required information at 275 a given time or acting on instructions from the end users. 277 In a typical scenario, during a boot-up procedure (and periodically 278 afterwards), the machines (endpoints) register with a Resource 279 Directory (for example EPs installed on vehicles enabling tracking of 280 their position for fleet management purposes and monitoring 281 environment parameters) hosted by the mobile operator or somewhere 282 else in the network, periodically a description of its own 283 capabilities. Due to the usual network configuration of mobile 284 networks, the EPs attached to the mobile network may not always be 285 efficiently reachable. Therefore, a remote server is usually used to 286 provide proxy access to the EPs. The address of each (proxy) 287 endpoint on this server is included in the resource description 288 stored in the RD. The users, for example mobile applications for 289 environment monitoring, contact the RD, look up the endpoints capable 290 of providing information about the environment using appropriate set 291 of link parameters, obtain information on how to contact them (URLs 292 of the proxy server) and then initiate interaction to obtain 293 information that is finally processed, displayed on the screen and 294 usually stored in a database. Similarly, fleet management systems 295 provide the appropriate link parameters to the RD to look up for EPs 296 deployed on the vehicles the application is responsible for. 298 3.2. Use Case: Home and Building Automation 300 Home and commercial building automation systems can benefit from the 301 use of M2M web services. The discovery requirements of these 302 applications are demanding. Home automation usually relies on run- 303 time discovery to commission the system, whereas in building 304 automation a combination of professional commissioning and run-time 305 discovery is used. Both home and building automation involve peer- 306 to-peer interactions between endpoints, and involve battery-powered 307 sleeping devices. 309 The exporting of resource information to other discovery systems is 310 also important in these automation applications. In home automation 311 there is a need to interact with other consumer electronics, which 312 may already support DNS-SD, and in building automation DNS-SD in 313 combination with resource directories can cover multiple buildings. 315 3.3. Use Case: Link Catalogues 317 Resources may be shared through data brokers that have no knowledge 318 beforehand of who is going to consume the data. Resource Directory 319 can be used to hold links about resources and services hosted 320 anywhere to make them discoverable by a general class of 321 applications. 323 For example, environmental and weather sensors that generate data for 324 public consumption may provide the data to an intermediary server, or 325 broker. Sensor data are published to the intermediary upon changes 326 or at regular intervals. Descriptions of the sensors that resolve to 327 links to sensor data may be published to a Resource Directory. 328 Applications wishing to consume the data can use the Resource 329 Directory lookup function set to discover and resolve links to the 330 desired resources and endpoints. The Resource Directory service need 331 not be coupled with the data intermediary service. Mapping of 332 Resource Directories to data intermediaries may be many-to-many. 334 Metadata in web link compatible representations are supplied by 335 Resource Directories, which may be internally stored as triples, or 336 relation/attribute pairs providing metadata about resource links. 337 External catalogs that are represented in other formats may be 338 converted to common web linking formats for storage and access by 339 Resource Directories. Since it is common practice for these to be 340 URN encoded, simple and lossless structural transforms should 341 generally be sufficient to store external metadata in Resource 342 Directories. 344 The additional features of Resource Directory allow domains to be 345 defined to enable access to a particular set of resources from 346 particular applications. This provides isolation and protection of 347 sensitive data when needed. Resource groups may defined to allow 348 batched reads from multiple resources. 350 4. Finding a Directory Server 352 Endpoints that want to contact a directory server can obtain 353 candidate IP addresses for such servers in a number of ways. 355 In a 6LoWPAN, good candidates can be taken from: 357 o specific static configuration (e.g., anycast addresses), if any, 359 o the ABRO option of 6LoWPAN-ND [RFC6775], 361 o other ND options that happen to point to servers (such as RDNSS), 363 o DHCPv6 options that might be defined later. 365 o The IPv6 Neighbor Discovery Resource Directory Address Option 366 described in Section 4.1 368 In networks with more inexpensive use of multicast, the candidate IP 369 address may be a well-known multicast address, i.e. directory servers 370 are found by simply sending GET requests to that well-known multicast 371 address (see Section 6.2). 373 As some of these sources are just (more or less educated) guesses, 374 endpoints MUST make use of any error messages to very strictly rate- 375 limit requests to candidate IP addresses that don't work out. For 376 example, an ICMP Destination Unreachable message (and, in particular, 377 the port unreachable code for this message) may indicate the lack of 378 a CoAP server on the candidate host, or a CoAP error response code 379 such as 4.05 "Method Not Allowed" may indicate unwillingness of a 380 CoAP server to act as a directory server. 382 4.1. Resource Directory Address Option (RDAO) 384 The Resource Directory Option (RDAO) using IPv6 neighbor Discovery 385 (ND) carries information about the address of the Resource Directory 386 (RD). This information is needed when endpoints cannot discover the 387 Resource Directory with link-local multicast address because the 388 endpoint and the RD are separated by a border Router (6LBR). In many 389 circumstances the availability of DHCP cannot be guaranteed either 390 during commissioning of the network. The presence and the use of the 391 RD is essential during commissioning. 393 The RDAO format is: 395 0 1 2 3 396 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 397 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 398 | Type | Length = 3 | Valid Lifetime | 399 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 400 | Reserved | 401 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 402 | | 403 + + 404 | | 405 + RD Address + 406 | | 407 + + 408 | | 409 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 411 Fields: 413 Type: 38 415 Length: 8-bit unsigned integer. The length of 416 the option in units of 8 bytes. 417 Always 3. 419 Valid Lifetime: 16-bit unsigned integer. The length of 420 time in units of 60 seconds (relative to 421 the time the packet is received) that 422 this set of border router information is 423 valid. A value of all zero bits (0x0) 424 assumes a default value of 10,000 425 (~one week). 427 Reserved: This field is unused. It MUST be 428 initialized to zero by the sender and 429 MUST be ignored by the receiver. 431 RD Address: IPv6 address of the RD. 433 Figure 3: Resource Directory Address Option 435 5. Simple Registration 437 Not all endpoints hosting resources are expected to know how to 438 implement the Resource Directory Function Set (see Section 6) hence 439 cannot register with a Resource Directory. Instead, simple endpoints 440 can implement the generic Simple Directory Discovery approach 441 described in this section. An RD implementing this specification 442 MUST implement Simple Directory Discovery. However, there may be 443 security reasons why this form of directory discovery would be 444 disabled. 446 This approach requires that the endpoint makes available the hosted 447 resources that it wants to be discovered, as links on its "/.well- 448 known/core" interface as specified in [RFC6690]. 450 The endpoint then finds one or more addresses of the directory server 451 as described in Section 4. 453 An endpoint can send (a selection of) hosted resources to a directory 454 server for publication as described in Section 5.1. 456 The directory server integrates the information it received this way 457 into its resource directory. It MAY make the information available 458 to further directories, if it can ensure that a loop does not form. 459 The protocol used between directories to ensure loop-free operation 460 is outside the scope of this document. 462 5.1. Simple publishing to Resource Directory Server 464 An endpoint that wants to make itself discoverable occasionally sends 465 a POST request to the "/.well-known/core" URI of any candidate 466 directory server that it finds. The body of the POST request is 467 empty, which triggers the resource directory server to perform GET 468 requests at the requesting server's default discovery URI to obtain 469 the link-format payload to register. 471 The endpoint MAY include registration parameters in the POST request 472 as per Section 6.3 474 The following example shows an endpoint using simple publishing, by 475 simply sending an empty POST to a resource directory. 477 Req:(to RD server from [ff02::1]) 478 POST coap://rd.example.com/.well-known/core?lt=6000 480 Content-Format: 40 482 payload: 484 (empty payload) 486 Res: 2.04 Changed 488 (later) 490 Req: (from RD server to [ff02::1]) 491 GET coap://[ff02::1]/.well-known/core 493 Accept: 40 495 Res: 2.05 Content 497 payload: 499 501 5.2. Third-party registration 503 For some applications, even Simple Directory Discovery may be too 504 taxing for certain very constrained devices, in particular if the 505 security requirements become too onerous. 507 In a controlled environment (e.g. building control), the Resource 508 Directory can be filled by a third device, called a commissioning 509 tool. The commissioning tool can fill the Resource Directory from a 510 database or other means. For that purpose the scheme, IP address and 511 port of the registered device is indicated in the Context parameter 512 of the registration described in Section 6.3. 514 6. Resource Directory Function Set 516 This section defines the REST interfaces between an RD and endpoints, 517 which is called the Resource Directory Function Set. Although the 518 examples throughout this section assume the use of CoAP [RFC7252], 519 these REST interfaces can also be realized using HTTP [RFC7230]. In 520 all definitions in this section, both CoAP response codes (with dot 521 notation) and HTTP response codes (without dot notation) are shown. 522 An RD implementing this specification MUST support the discovery, 523 registration, update, lookup, and removal interfaces defined in this 524 section. 526 Resource directory entries are designed to be easily exported to 527 other discovery mechanisms such as DNS-SD. For that reason, 528 parameters that would meaningfully be mapped to DNS SHOULD be limited 529 to a maximum length of 63 bytes. 531 6.1. Content Formats 533 Resource Directory implementations using this specification MUST 534 support the application/link-format content format (ct=40). 536 Resource Directories implementing this specification MAY support 537 additional content formats. 539 Any additional content format supported by a Resource Directory 540 implementing this specification MUST have an equivalent serialization 541 in the application/link-format content format. 543 6.2. Discovery 545 Before an endpoint can make use of an RD, it must first know the RD's 546 address and port, and the path of its RD Function Set. There can be 547 several mechanisms for discovering the RD including assuming a 548 default location (e.g. on an Edge Router in a LoWPAN), by assigning 549 an anycast address to the RD, using DHCP, or by discovering the RD 550 using the CoRE Link Format (see also Section 4). This section 551 defines discovery of the RD using the well-known interface of the 552 CoRE Link Format [RFC6690] as the required mechanism. It is however 553 expected that RDs will also be discoverable via other methods 554 depending on the deployment. 556 Discovery of the RD function set is performed by sending either a 557 multicast or unicast GET request to "/.well-known/core" and including 558 a Resource Type (rt) parameter [RFC6690] with the value "core.rd" in 559 the query string. Likewise, a Resource Type parameter value of 560 "core.rd-lookup" is used to discover the RD Lookup Function Set. 561 Upon success, the response will contain a payload with a link format 562 entry for each RD discovered, with the URL indicating the root 563 resource of the RD. When performing multicast discovery, the 564 multicast IP address used will depend on the scope required and the 565 multicast capabilities of the network. 567 A Resource Directory MAY provide hints about the content-formats it 568 supports in the links it exposes or registers, using the "ct" link 569 attribute, as shown in the example below. Clients MAY use these 570 hints to select alternate content-formats for interaction with the 571 Resource Directory. 573 HTTP does not support multicast and consequently only unicast 574 discovery can be supported using HTTP. Links to Resource Directories 575 MAY be registered in other Resource Directories, and well-known entry 576 points SHOULD be provided to enable the bootstrapping of unicast 577 discovery. 579 An RD implementation of this specification MUST support query 580 filtering for the rt parameter as defined in [RFC6690]. 582 The discovery request interface is specified as follows: 584 Interaction: EP -> RD 586 Method: GET 588 URI Template: /.well-known/core{?rt} 590 URI Template Variables: 592 rt := Resource Type (optional). MAY contain one or more of the 593 values "core.rd", "core.rd-lookup", "core.rd-group" or 594 "core.rd*" 596 Content-Format: application/link-format (if any) 598 Content-Format: application/link-format+json (if any) 600 Content-Format: application/link-format+cbor (if any) 602 The following response codes are defined for this interface: 604 Success: 2.05 "Content" with an application/link-format, 605 application/link-format+json, or application/link-format+cbor 606 payload containing one or more matching entries for the RD 607 resource. 609 Failure: 4.04 "Not Found" is returned in case no matching entry is 610 found for a unicast request. 612 Failure: 4.00 "Bad Request" is returned in case of a malformed 613 request for a unicast request. 615 Failure: No error response to a multicast request. 617 HTTP support : YES (Unicast only) 619 The following example shows an endpoint discovering an RD using this 620 interface, thus learning that the base RD resource is, in this 621 example, at /rd and that the content_format delivered by the server 622 hosting the resource is application.xml (ct=40). Note that it is up 623 to the RD to choose its base RD resource, although diagnostics and 624 debugging is facilitated by using the base paths specified here where 625 possible. 627 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 629 Res: 2.05 Content 630 ;rt="core.rd";ct=40, 631 ;rt="core.rd-lookup";ct=40, 632 ;rt="core.rd-group";ct=40 634 The following example shows the way of indicating that a client may 635 request alternate content-formats. The Content-Format code attribute 636 "ct" MAY include a space-separated sequence of Content-Format codes 637 as specified in [RFC7252], indicating that multiple content-formats 638 are available. The example below shows the required ct=40 639 (application/link-format) indicated as well as a vendor-specific 640 content format (21225). 642 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 644 Res: 2.05 Content 645 ;rt="core.rd";ct="40 21225", 646 ;rt="core.rd-lookup";ct="40 21225", 647 ;rt="core.rd-group";ct="40 21225" 649 6.3. Registration 651 After discovering the location of an RD Function Set, an endpoint MAY 652 register its resources using the registration interface. This 653 interface accepts a POST from an endpoint containing the list of 654 resources to be added to the directory as the message payload in the 655 CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link- 656 format+json), or CBOR CoRE Link Format (application/link-format+cbor) 657 [I-D.ietf-core-links-json], along with query string parameters 658 indicating the name of the endpoint, its domain and the lifetime of 659 the registration. All parameters except the endpoint name are 660 optional. It is expected that other specifications will define 661 further parameters (see Section 12.4). The RD then creates a new 662 resource or updates an existing resource in the RD and returns its 663 location. An endpoint MUST use that location when refreshing 664 registrations using this interface. Endpoint resources in the RD are 665 kept active for the period indicated by the lifetime parameter. The 666 endpoint is responsible for refreshing the entry within this period 667 using either the registration or update interface. The registration 668 interface MUST be implemented to be idempotent, so that registering 669 twice with the same endpoint parameter does not create multiple RD 670 entries. A new registration may be created at any time to supercede 671 an existing registration, replacing the registration parameters and 672 links. 674 The registration request interface is specified as follows: 676 Interaction: EP -> RD 678 Method: POST 680 URI Template: /{+rd}{?ep,d,et,lt,con} 682 URI Template Variables: 684 rd := RD Function Set path (mandatory). This is the path of the 685 RD Function Set, as obtained from discovery. An RD SHOULD use 686 the value "rd" for this variable whenever possible. 688 ep := Endpoint name (mandatory). The endpoint name is an 689 identifier that MUST be unique within a domain. The maximum 690 length of this parameter is 63 bytes. 692 d := Domain (optional). The domain to which this endpoint 693 belongs. The maximum length of this parameter is 63 bytes. 694 When this parameter is elided, the RD MAY associate the 695 endpoint with a configured default domain. The domain value is 696 needed to export the endpoint to DNS-SD (see Section 10). 698 et := Endpoint Type (optional). The semantic type of the 699 endpoint. This parameter SHOULD be less than 63 bytes. 701 lt := Lifetime (optional). Lifetime of the registration in 702 seconds. Range of 60-4294967295. If no lifetime is included, 703 a default value of 86400 (24 hours) SHOULD be assumed. 705 con := Context (optional). This parameter sets the scheme, 706 address and port at which this server is available in the form 707 scheme://host:port. In the absence of this parameter the 708 scheme of the protocol, source IP address and source port of 709 the register request are assumed. This parameter is mandatory 710 when the directory is filled by a third party such as an 711 commissioning tool. 713 Content-Format: application/link-format 715 Content-Format: application/link-format+json 716 Content-Format: application/link-format+cbor 718 The following response codes are defined for this interface: 720 Success: 2.01 "Created" or 201 "Created". The Location header MUST 721 be included with the new resource entry for the endpoint. This 722 Location MUST be a stable identifier generated by the RD as it is 723 used for all subsequent operations on this registration. The 724 resource returned in the Location is for the purpose of updating 725 the lifetime of the registration and for maintaining the content 726 of the registered links, including updating and deleting links. 728 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 729 request. 731 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 732 Service could not perform the operation. 734 HTTP support: YES 736 The following example shows an endpoint with the name "node1" 737 registering two resources to an RD using this interface. The 738 resulting location /rd/4521 is just an example of an RD generated 739 location. 741 Req: POST coap://rd.example.com/rd?ep=node1 742 Content-Format: 40 743 Payload: 744 ;ct=41;rt="temperature-c";if="sensor", 745 ;ct=41;rt="light-lux";if="sensor" 747 Res: 2.01 Created 748 Location: /rd/4521 750 Req: POST /rd?ep=node1 HTTP/1.1 751 Host : example.com 752 Content-Type: application/link-format 753 Payload: 754 ;ct=41;rt="temperature-c";if="sensor", 755 ;ct=41;rt="light-lux";if="sensor" 757 Res: 201 Created 758 Location: /rd/4521 760 6.4. Registration Update 762 The update interface is used by an endpoint to refresh or update its 763 registration with an RD. To use the interface, the endpoint sends a 764 POST request to the resource returned in the Location option in the 765 response to the first registration. 767 An update MAY update the lifetime or context registration parameters 768 "lt", "con" as in Section 6.3 ) if they have changed since the last 769 registration or update. Parameters that have not changed SHOULD NOT 770 be included in an update. Adding parameters that have not changed 771 increases the size of the message but does not have any other 772 implications. Parameters MUST be included as query parameters in an 773 update operation as in {registration}. 775 Upon receiving an update request, an RD MUST reset the timeout for 776 that endpoint and update the scheme, IP address and port of the 777 endpoint, using the source address of the update, or the context 778 ("con") parameter if present. If the lifetime parameter "lt" is 779 included in the received update request, the RD MUST update the 780 lifetime of the registration and set the timeout equal to the new 781 lifetime. 783 An update MAY optionally add or replace links for the endpoint by 784 including those links in the payload of the update as a CoRE Link 785 Format document. A link is replaced only if both the target URI and 786 relation type match. 788 In addition to the use of POST, as described in this section, there 789 is an alternate way to add, replace, and delete links using PATCH as 790 described in Section 6.7. 792 The update registration request interface is specified as follows: 794 Interaction: EP -> RD 796 Method: POST 798 URI Template: /{+location}{?lt,con} 800 URI Template Variables: 802 location := This is the Location path returned by the RD as a 803 result of a successful earlier registration. 805 lt := Lifetime (optional). Lifetime of the registration in 806 seconds. Range of 60-4294967295. If no lifetime is included, 807 a default value of 86400 (24 hours) SHOULD be assumed. 809 con := Context (optional). This parameter sets the scheme, 810 address and port at which this server is available in the form 811 scheme://host:port. Optional. In the absence of this 812 parameter the scheme of the protocol, source IP address and 813 source port used to register are assumed. This parameter is 814 compulsory when the directory is filled by a third party such 815 as a commissioning tool. 817 Content-Format: application/link-format (mandatory) 819 Content-Format: application/link-format+json (optional) 821 Content-Format: application/link-format+cbor (optional) 823 The following response codes are defined for this interface: 825 Success: 2.04 "Changed" or 204 "No Content" if the update was 826 successfully processed. 828 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 829 request. 831 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 832 exist (e.g. may have expired). 834 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 835 Service could not perform the operation. 837 HTTP support: YES 839 The following example shows an endpoint updating its registration at 840 an RD using this interface. 842 Req: POST /rd/4521 844 Res: 2.04 Changed 846 The following example shows an endpoint updating its registration 847 with a new lifetime and context, changing an existing link, and 848 adding a new link using this interface. With the initial 849 registration the client set the following values: 851 o lifetime (lt)=500 853 o context (con)=coap://local-proxy-old.example.com:5683 855 o resource= ;ct=41;rt="foobar";if="sensor" 856 Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683" 857 Content-Format: 40 858 Payload: 859 ;ct=41;rt="temperature-f";if="sensor", 860 ;ct=41;rt="door";if="sensor" 862 Res: 2.04 Changed 864 6.5. Registration Removal 866 Although RD entries have soft state and will eventually timeout after 867 their lifetime, an endpoint SHOULD explicitly remove its entry from 868 the RD if it knows it will no longer be available (for example on 869 shut-down). This is accomplished using a removal interface on the RD 870 by performing a DELETE on the endpoint resource. 872 The removal request interface is specified as follows: 874 Interaction: EP -> RD 876 Method: DELETE 878 URI Template: /{+location} 880 URI Template Variables: 882 location := This is the Location path returned by the RD as a 883 result of a successful earlier registration. 885 The following responses codes are defined for this interface: 887 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 889 Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed 890 request. 892 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 893 exist (e.g. may have expired). 895 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 896 Service could not perform the operation. 898 HTTP support: YES 900 The following examples shows successful removal of the endpoint from 901 the RD. 903 Req: DELETE /rd/4521 905 Res: 2.02 Deleted 907 6.6. Read Endpoint Links 909 Some endpoints may wish to manage their links as a collection, and 910 may need to read the current set of links in order to determine link 911 maintenance operations. 913 One or more links MAY be selected by using query filtering as 914 specified in [RFC6690] Section 4.1 916 The read request interface is specified as follows: 918 Interaction: EP -> RD 920 Method: GET 922 URI Template: /{+location}{?href,rel,rt,if,ct} 924 URI Template Variables: 926 location := This is the Location path returned by the RD as a 927 result of a successful earlier registration. 929 href,rel,rt,if,ct := link relations and attributes specified in 930 the query in order to select particular links based on their 931 relations and attributes. "href" denotes the URI target of the 932 link. See [RFC6690] Sec. 4.1 934 The following responses codes are defined for this interface: 936 Success: 2.05 "Content" or 200 "OK" upon success with an 937 "application/link-format", "application/link-format+cbor", or 938 "application/link-format+json" payload. 940 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 941 request. 943 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 944 exist (e.g. may have expired). 946 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 947 Service could not perform the operation. 949 HTTP support: YES 950 The following examples show successful read of the endpoint links 951 from the RD. 953 Req: GET /rd/4521 955 Res: 2.01 Content 956 Payload: 957 ;ct=41;rt="temperature-c";if="sensor", 958 ;ct=41;rt="light-lux";if="sensor" 960 6.7. Update Endpoint Links 962 [This section will be removed before or as a result of a working- 963 group last-call if the PATCH methods do not achieve the same level of 964 consensus as the present document.] 966 A PATCH update adds, removes or changes links for the endpoint by 967 including link update information in the payload of the update as a 968 merge-patch+json format [RFC7396] document. 970 One or more links are selected for update by using query filtering as 971 specified in [RFC6690] Section 4.1 973 The query filter selects the links to be modified or deleted, by 974 matching the query parameter values to the values of the link 975 attributes. 977 When the query parameters are not present in the request, the payload 978 specifies links to be added to the target document. When the query 979 parameters are present, the attribute names and values in the query 980 parameters select one or more links on which to apply the PATCH 981 operation. 983 If an attribute name specified in the PATCH document exists in any 984 the set of selected links, all occurrences of the attribute value in 985 the target document MUST be updated using the value from the PATCH 986 payload. If the attribute name is not present in any selected links, 987 the attribute MUST be added to the links. 989 The update request interface is specified as follows: 991 Interaction: EP -> RD 993 Method: PATCH 995 URI Template: /{+location}{?href,rel,rt,if,ct} 997 URI Template Variables: 999 location := This is the Location path returned by the RD as a 1000 result of a successful earlier registration. 1002 href,rel,rt,if,ct := link relations and attributes specified in 1003 the query in order to select particular links based on their 1004 relations and attributes. "href" denotes the URI target of the 1005 link. See [RFC6690] Sec. 4.1 1007 Content-Format: application/merge-patch+json (mandatory) 1009 The following response codes are defined for this interface: 1011 Success: 2.04 "Changed" 0r 204 "No Content" in the update was 1012 successfully processed. 1014 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1015 request. 1017 Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource 1018 does not exist (e.g. may have expired). 1020 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1021 Service could not perform the operation. 1023 HTTP support: YES 1025 The following examples show an endpoint adding , 1026 modifying , and removing links in RD 1027 using the Update Endpoint Links function. 1029 The following example shows an EP adding the link ;ct=41;rt="humid-s";if="sensor" to the collection of links at 1031 the location /rd/4521. 1033 Req: PATCH /rd/4521 1035 Payload: 1036 [{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}] 1038 Content-Format: 1039 application/merge-patch+json 1041 Res: 2.04 Changed 1043 The following example shows an EP modifying all links at the location 1044 /rd/4521 which are identified by href="/sensors/temp", from the 1045 initial link-value of ;rt="temperature" to the new 1046 link-value ;rt="temperature-c";if="sensor" by changing 1047 the value of the link attribute "rt" and adding the link attribute 1048 if="sensor" using the PATCH operation with the supplied merge- 1049 patch+json document payload. 1051 Req: PATCH /rd/4521?href="/sensors/temp" 1053 Payload: 1054 {"rt": "temperature-c", "if": "sensor"}, 1056 Content-Format: 1057 application/merge-patch+json 1059 Res: 2.04 Changed 1061 This example shows an EP removing all links at the location /rd/4521 1062 which are identified by href="/sensors/light". 1064 Req: PATCH /rd/4521?href="/sensors/light" 1066 Payload: 1067 {null} 1069 Content-Format: 1070 application/merge-patch+json 1072 Res: 2.04 Changed 1074 7. Group Function Set 1076 This section defines a function set for the creation of groups of 1077 endpoints for the purpose of managing and looking up endpoints for 1078 group operations. The group function set is similar to the resource 1079 directory function set, in that a group may be created or removed. 1080 However unlike an endpoint entry, a group entry consists of a list of 1081 endpoints and does not have a lifetime associated with it. In order 1082 to make use of multicast requests with CoAP, a group MAY have a 1083 multicast address associated with it. 1085 7.1. Register a Group 1087 In order to create a group, a commissioning tool (CT) used to 1088 configure groups, makes a request to the RD indicating the name of 1089 the group to create (or update), optionally the domain the group 1090 belongs to, and optionally the multicast address of the group. The 1091 registration message includes the list of endpoints that belong to 1092 that group. 1094 All the endpoints in the group MUST be registered with the RD before 1095 registering a group. If an endpoint is not yet registered to the RD 1096 before registering the group, the registration message returns an 1097 error. The RD sends a blank target URI for every endpoint link when 1098 registering the group. 1100 Configuration of the endpoints themselves is out of scope of this 1101 specification. Such an interface for managing the group membership 1102 of an endpoint has been defined in [RFC7390]. 1104 The registration request interface is specified as follows: 1106 Interaction: CT -> RD 1108 Method: POST 1110 URI Template: /{+rd-group}{?gp,d,con} 1112 URI Template Variables: 1114 rd-group := RD Group Function Set path (mandatory). This is the 1115 path of the RD Group Function Set. An RD SHOULD use the value 1116 "rd-group" for this variable whenever possible. 1118 gp := Group Name (mandatory). The name of the group to be 1119 created or replaced, unique within that domain. The maximum 1120 length of this parameter is 63 bytes. 1122 d := Domain (optional). The domain to which this group belongs. 1123 The maximum length of this parameter is 63 bytes. Optional. 1124 When this parameter is elided, the RD MAY associate the 1125 endpoint with a configured default domain. The domain value is 1126 needed to export the endpoint to DNS-SD (see Section 10) 1128 con := Context (optional). This parameter is used to set the IP 1129 multicast address at which this server is available in the form 1130 scheme://multicast-address:port. Optional. In the absence of 1131 this parameter no multicast address is configured. This 1132 parameter is compulsory when the directory is filled by a 1133 commissioning tool. 1135 Content-Format: application/link-format 1137 Content-Format: application/link-format+json 1139 Content-Format: application/link-format+cbor 1141 The following response codes are defined for this interface: 1143 Success: 2.01 "Created" or 201 "Created". The Location header MUST 1144 be included with the new group entry. This Location MUST be a 1145 stable identifier generated by the RD as it is used for delete 1146 operations on this registration. 1148 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1149 request. 1151 Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not 1152 registered in the RD (e.g. may have expired). 1154 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1155 Service could not perform the operation. 1157 HTTP support: YES 1159 The following example shows an EP registering a group with the name 1160 "lights" which has two endpoints to an RD using this interface. The 1161 resulting location /rd-group/12 is just an example of an RD generated 1162 group location. 1164 Req: POST coap://rd.example.com/rd-group?gp=lights 1165 Content-Format: 40 1166 Payload: 1167 <>;ep="node1", 1168 <>;ep="node2" 1170 Res: 2.01 Created 1171 Location: /rd-group/12 1173 Req: POST /rd-group?gp=lights HTTP/1.1 1174 Host: example.com 1175 Content-Type: application/link-format 1176 Payload: 1177 <>;ep="node1", 1178 <>;ep="node2" 1180 Res: 201 Created 1181 Location: /rd-group/12 1183 7.2. Group Removal 1185 A group can be removed simply by sending a removal message to the 1186 location returned when registering the group. Removing a group MUST 1187 NOT remove the endpoints of the group from the RD. 1189 The removal request interface is specified as follows: 1191 Interaction: CT -> RD 1193 Method: DELETE 1195 URI Template: /{+location} 1197 URI Template Variables: 1199 location := This is the Location path returned by the RD as a 1200 result of a successful group registration. 1202 The following responses codes are defined for this interface: 1204 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1206 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1207 request. 1209 Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. 1211 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1212 Service could not perform the operation. 1214 HTTP support: YES 1216 The following examples shows successful removal of the group from the 1217 RD. 1219 Req: DELETE /rd-group/12 1221 Res: 2.02 Deleted 1223 8. RD Lookup Function Set 1225 In order for an RD to be used for discovering resources registered 1226 with it, a lookup interface can be provided using this function set. 1227 This lookup interface is defined as a default, and it is assumed that 1228 RDs may also support lookups to return resource descriptions in 1229 alternative formats (e.g. Atom or HTML Link) or using more advanced 1230 interfaces (e.g. supporting context or semantic based lookup). 1232 This function set allows lookups for domains, groups, endpoints and 1233 resources using attributes defined in the RD Function Set and for use 1234 with the CoRE Link Format. The result of a lookup request is the 1235 list of links (if any) corresponding to the type of lookup. Thus, a 1236 domain lookup MUST return a list of domains, a group lookup MUST 1237 return a list of groups, an endpoint lookup MUST return a list of 1238 endpoints and a resource lookup MUST return a list of links to 1239 resources. 1241 Each endpoint and resource lookup result returns respectively the 1242 scheme (IP address and port) followed by the path part of the URI of 1243 every endpoint and resource inside angle brackets ("<>") and followed 1244 by the other parameters. 1246 The target of these links SHOULD be the actual location of the 1247 domain, endpoint or resource, but MAY be an intermediate proxy e.g. 1248 in the case of an HTTP lookup interface for CoAP endpoints. 1250 The domain lookup returns every lookup domain with a "/rd" value 1251 encapsulated within angle brackets. 1253 In case that a group does not implement any multicast address, the 1254 group lookup returns every group lookup with a "/rd-group" value 1255 encapsulated within angle brackets. Otherwise, the group lookup 1256 returns the multicast address of the group inside angle brackets. 1258 Using the Accept Option, the requester can control whether this list 1259 is returned in CoRE Link Format ("application/link-format", default) 1260 or its alternate content-formats ("application/link-format+json" or 1261 "application/link-format+cbor"). 1263 The page and count parameters are used to obtain lookup results in 1264 specified increments using pagination, where count specifies how many 1265 links to return and page specifies which subset of links organized in 1266 sequential pages , each containing 'count' links, starting with link 1267 zero and page zero. Thus, specifying count of 10 and page of 0 will 1268 return the first 10 links in the result set (links 0-9). Count = 10 1269 and page = 1 will return the next 'page' containing links 10-19, and 1270 so on. 1272 Multiple query parameters MAY be included in a lookup, all included 1273 parameters MUST match for a resource to be returned. The 1274 character'*' MAY be included at the end of a parameter value as a 1275 wildcard operator. 1277 The rd-lookup interface MAY use any set of query parameters to match 1278 the registered attributes and relations. In addition, this interface 1279 MAY be used with queries that specify domains, endpoints, and groups. 1280 For example, a domain lookup filtering on groups would return a list 1281 of domains that contain the specified groups. An endpoint lookup 1282 filtering on groups would return a list of endpoints that are in the 1283 specified groups. 1285 The lookup interface is specified as follows: 1287 Interaction: Client -> RD 1289 Method: GET 1291 URI Template: /{+rd-lookup-base}/{lookup- 1292 type}{?d,ep,gp,et,rt,page,count,resource-param} 1294 URI Template Variables: 1296 rd-lookup-base := RD Lookup Function Set path (mandatory). This 1297 is the path of the RD Lookup Function Set. An RD SHOULD use the 1298 value "rd-lookup" for this variable whenever possible. 1300 lookup-type := ("d", "ep", "res", "gp") (mandatory) This variable 1301 is used to select the kind of lookup to perform (domain, 1302 endpoint, resource, or group). 1304 ep := Endpoint name (optional). Used for endpoint, group and 1305 resource lookups. 1307 d := Domain (optional). Used for domain, group, endpoint and 1308 resource lookups. 1310 res := resource (optional). Used for domain, group, endpoint and 1311 resource lookups. 1313 gp := Group name (optional). Used for endpoint, group and 1314 resource lookups. 1316 page := Page (optional). Parameter can not be used without the 1317 count parameter. Results are returned from result set in pages 1318 that contain 'count' links starting from index (page * count). 1319 Page numbering starts with zero. 1321 count := Count (optional). Number of results is limited to this 1322 parameter value. If the page parameter is also present, the 1323 response MUST only include 'count' links starting with the 1324 (page * count) link in the result set from the query. If the 1325 count parameter is not present, then the response MUST return 1326 all matching links in the result set. Link numbering starts 1327 with zero. 1329 rt := Resource type (optional). Used for group, endpoint and 1330 resource lookups. 1332 et := Endpoint type (optional). Used for group, endpoint and 1333 resource lookups. 1335 resource-param := Link attribute parameters (optional). Any link 1336 attribute as defined in Section 4.1 of [RFC6690], used for 1337 resource lookups. 1339 Content-Format: application/link-format (optional) 1341 Content-Format: application/link-format+json (optional) 1343 Content-Format: application/link-format+cbor (optional) 1345 The following responses codes are defined for this interface: 1347 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1348 format", "application/link-format+cbor", or "application/link- 1349 format+json" payload containing matching entries for the lookup. 1351 Failure: 4.04 "Not Found" or 404 "Not Found" in case no matching 1352 entry is found for a unicast request. 1354 Failure: No error response to a multicast request. 1356 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1357 request. 1359 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1360 Service could not perform the operation. 1362 HTTP support: YES 1364 The examples in this section assume a CoAP host with IP address 1365 FDFD::123 and a default CoAP port 61616. HTTP hosts are possible and 1366 do not change the nature of the examples.\ 1368 The following example shows a client performing a resource lookup: 1370 Req: GET /rd-lookup/res?rt=temperature 1372 Res: 2.05 Content 1373 ;rt="temperature" 1375 The following example shows a client performing an endpoint type 1376 lookup: 1378 Req: GET /rd-lookup/ep?et=power-node 1380 Res: 2.05 Content 1381 ;ep="node5", 1382 ;ep="node7" 1383 The following example shows a client performing a domain lookup: 1385 Req: GET /rd-lookup/d 1387 Res: 2.05 Content 1388 <>;d="domain1", 1389 <>;d="domain2" 1391 The following example shows a client performing a group lookup for 1392 all groups: 1394 Req: GET /rd-lookup/gp 1396 Res: 2.05 Content 1397 <>;gp="lights1";d="example.com" 1398 <>;gp="lights2";d="ecample.com" 1400 The following example shows a client performing a lookup for all 1401 endpoints in a particular group: 1403 Req: GET /rd-lookup/ep?gp=lights1 1405 Res: 2.05 Content 1406 ;ep="node1", 1407 ;ep="node2" 1409 The following example shows a client performing a lookup for all 1410 groups an endpoint belongs to: 1412 Req: GET /rd-lookup/gp?ep=node1 1414 Res: 2.05 Content 1415 <>;gp="lights1" 1417 The following example shows a client performing a paginated lookup 1418 Req: GET /rd-lookup/res?page=0&count=5 1420 Res: 2.05 Content 1421 ;rt=sensor;ct=60 1422 ;rt=sensor;ct=60 1423 ;rt=sensor;ct=60 1424 ;rt=sensor;ct=60 1425 ;rt=sensor;ct=60 1427 Req: GET /rd-lookup/res?page=1&count=5 1429 Res: 2.05 Content 1430 ;rt=sensor;ct=60 1431 ;rt=sensor;ct=60 1432 ;rt=sensor;ct=60 1433 ;rt=sensor;ct=60 1434 ;rt=sensor;ct=60 1436 9. New Link-Format Attributes 1438 When using the CoRE Link Format to describe resources being 1439 discovered by or posted to a resource directory service, additional 1440 information about those resources is useful. This specification 1441 defines the following new attributes for use in the CoRE Link Format 1442 [RFC6690]: 1444 link-extension = ( "ins" "=" quoted-string ) ; Max 63 bytes 1445 link-extension = ( "exp" ) 1447 9.1. Resource Instance attribute 'ins' 1449 The Resource Instance "ins" attribute is an identifier for this 1450 resource, which makes it possible to distinguish it from other 1451 similar resources. This attribute is similar in use to the 1452 portion of a DNS-SD record (see Section 10.1, and SHOULD 1453 be unique across resources with the same Resource Type attribute in 1454 the domain it is used. A Resource Instance might be a descriptive 1455 string like "Ceiling Light, Room 3", a short ID like "AF39" or a 1456 unique UUID or iNumber. This attribute is used by a Resource 1457 Directory to distinguish between multiple instances of the same 1458 resource type within the directory. 1460 This attribute MUST be no more than 63 bytes in length. The resource 1461 identifier attribute MUST NOT appear more than once in a link 1462 description. This attribute MAY be used as a query parameter in the 1463 RD Lookup Function Set defined in Section 7. 1465 9.2. Export attribute 'exp' 1467 The Export "exp" attribute is used as a flag to indicate that a link 1468 description MAY be exported by a resource directory to external 1469 directories. 1471 The CoRE Link Format is used for many purposes between CoAP 1472 endpoints. Some are useful mainly locally, for example checking the 1473 observability of a resource before accessing it, determining the size 1474 of a resource, or traversing dynamic resource structures. However, 1475 other links are very useful to be exported to other directories, for 1476 example the entry point resource to a functional service. This 1477 attribute MAY be used as a query parameter in the RD Lookup Function 1478 Set defined in Section 7. 1480 10. DNS-SD Mapping 1482 CoRE Resource Discovery is intended to support fine-grained discovery 1483 of hosted resources, their attributes, and possibly other resource 1484 relations [RFC6690]. In contrast, service discovery generally refers 1485 to a coarse-grained resolution of an endpoint's IP address, port 1486 number, and protocol. 1488 Resource and service discovery are complementary in the case of large 1489 networks, where the latter can facilitate scaling. This document 1490 defines a mapping between CoRE Link Format attributes and DNS-Based 1491 Service Discovery [RFC6763] fields that permits discovery of CoAP 1492 services by either method. 1494 10.1. DNS-based Service discovery 1496 DNS-Based Service Discovery (DNS-SD) defines a conventional method of 1497 configuring DNS PTR, SRV, and TXT resource records to facilitate 1498 discovery of services (such as CoAP servers in a subdomain) using the 1499 existing DNS infrastructure. This section gives a brief overview of 1500 DNS-SD; see [RFC6763] for a detailed specification. 1502 DNS-SD service names are limited to 255 octets and are of the form: 1504 Service Name = ... 1506 The service name is the label of SRV/TXT resource records. The SRV 1507 RR specifies the host and the port of the endpoint. The TXT RR 1508 provides additional information in the form of key/value pairs. 1510 The part of the service name is identical to the global (DNS 1511 subdomain) part of the authority in URIs that identify servers or 1512 groups of servers. 1514 The part is composed of at least two labels. The first 1515 label of the pair is the application protocol name [RFC6335] preceded 1516 by an underscore character. The second label indicates the transport 1517 and is always "_udp" for UDP-based CoAP services. In cases where 1518 narrowing the scope of the search may be useful, these labels may be 1519 optionally preceded by a subtype name followed by the "_sub" label. 1520 An example of this more specific is 1521 "light._sub._dali._udp". 1523 A default part of the service name may be set at the 1524 factory or during the commissioning process. It SHOULD uniquely 1525 identify an instance of within a . Taken 1526 together, these three elements comprise a unique name for an SRV/ TXT 1527 record pair within the DNS subdomain. 1529 The granularity of a service name MAY be that of a host or group, or 1530 it could represent a particular resource within a CoAP server. The 1531 SRV record contains the host name (AAAA record name) and port of the 1532 service while protocol is part of the service name. In the case 1533 where a service name identifies a particular resource, the path part 1534 of the URI must be carried in a corresponding TXT record. 1536 A DNS TXT record is in practice limited to a few hundred octets in 1537 length, which is indicated in the resource record header in the DNS 1538 response message. The data consists of one or more strings 1539 comprising a key=value pair. By convention, the first pair is 1540 txtver= (to support different versions of a service 1541 description). 1543 10.2. mapping ins to 1545 The Resource Instance "ins" attribute maps to the part of 1546 a DNS-SD service name. It is stored directly in the DNS as a single 1547 DNS label of canonical precomposed UTF-8 [RFC3629] "Net-Unicode" 1548 (Unicode Normalization Form C) [RFC5198] text. However, to the 1549 extent that the "ins" attribute may be chosen to match the DNS host 1550 name of a service, it SHOULD use the syntax defined in Section 3.5 of 1551 [RFC1034] and Section 2.1 of [RFC1123]. 1553 The part of the name of a service being offered on the 1554 network SHOULD be configurable by the user setting up the service, so 1555 that he or she may give it an informative name. However, the device 1556 or service SHOULD NOT require the user to configure a name before it 1557 can be used. A sensible choice of default name can allow the device 1558 or service to be accessed in many cases without any manual 1559 configuration at all. The default name should be short and 1560 descriptive, and MAY include a collision-resistant substring such as 1561 the lower bits of the device's MAC address, serial number, 1562 fingerprint, or other identifier in an attempt to make the name 1563 relatively unique. 1565 DNS labels are currently limited to 63 octets in length and the 1566 entire service name may not exceed 255 octets. 1568 10.3. Mapping rt to 1570 The resource type "rt" attribute is mapped into the 1571 part of a DNS-SD service name and SHOULD conform to the reg-rel-type 1572 production of the Link Format defined in Section 2 of [RFC6690]. The 1573 "rt" attribute MUST be composed of at least a single Net-Unicode text 1574 string, without underscore '_' or period '.' and limited to 15 octets 1575 in length, which represents the application protocol name. This 1576 string is mapped to the DNS-SD by prepending an 1577 underscore and appending a period followed by the "_udp" label. For 1578 example, rt="dali" is mapped into "_dali._udp". 1580 The application protocol name may be optionally followed by a period 1581 and a service subtype name consisting of a Net-Unicode text string, 1582 without underscore or period and limited to 63 octets. This string 1583 is mapped to the DNS-SD by appending a period followed 1584 by the "_sub" label and then appending a period followed by the 1585 service type label pair derived as in the previous paragraph. For 1586 example, rt="dali.light" is mapped into "light._sub._dali._udp". 1588 The resulting string is used to form labels for DNS-SD records which 1589 are stored directly in the DNS. 1591 10.4. Domain mapping 1593 DNS domains may be derived from the "d" attribute. The domain 1594 attribute may be suffixed with the zone name of the authoritative DNS 1595 server to generate the domain name. The "ep" attribute is prefixed 1596 to the domain name to generate the FQDN to be stored into DNS with an 1597 AAAA RR. 1599 10.5. TXT Record key=value strings 1601 A number of [RFC6763] key/value pairs are derived from link-format 1602 information, to be exported in the DNS-SD as key=value strings in a 1603 TXT record ([RFC6763], Section 6.3). 1605 The resource is exported as key/value pair "path=". 1607 The Interface Description "if" attribute is exported as key/value 1608 pair "if=". 1610 The DNS TXT record can be further populated by importing any other 1611 resource description attributes as they share the same key=value 1612 format specified in Section 6 of [RFC6763]. 1614 10.6. Importing resource links into DNS-SD 1616 Assuming the ability to query a Resource Directory or multicast a GET 1617 (?exp) over the local link, CoAP resource discovery may be used to 1618 populate the DNS-SD database in an automated fashion. CoAP resource 1619 descriptions (links) can be exported to DNS-SD for exposure to 1620 service discovery by using the Resource Instance attribute as the 1621 basis for a unique service name, composed with the Resource Type as 1622 the , and registered in the correct . The agent 1623 responsible for exporting records to the DNS zone file SHOULD be 1624 authenticated to the DNS server. The following example shows an 1625 agent discovering a resource to be exported: 1627 Req: GET /rd-lookup/res?exp 1629 Res: 2.05 Content 1630 ; 1631 exp;rt="dali.light";ins="Spot"; 1632 d="office";ep="node1" 1634 The agent subsequently registers the following DNS-SD RRs, assuming a 1635 zone name "example.com" prefixed with "office": 1637 node1.office.example.com. IN AAAA FDFD::1234 1638 _dali._udp.office.example.com IN PTR 1639 Spot._dali._udp.office.example.com 1640 light._sub._dali._udp.example.com IN PTR 1641 Spot._dali._udp.office.example.com 1642 Spot._dali._udp.office.example.com IN SRV 0 0 5683 1643 node1.office.example.com. 1644 Spot._dali._udp.office.example.com IN TXT 1645 txtver=1;path=/light/1 1647 In the above figure the Service Name is chosen as 1648 Spot._dali._udp.office.example.com without the light._sub service 1649 prefix. An alternative Service Name would be: 1650 Spot.light._sub._dali._udp.office.example.com. 1652 11. Security Considerations 1654 The security considerations as described in Section 7 of [RFC5988] 1655 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1656 may be protected e.g. using DTLS when hosted on a CoAP server as 1657 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1658 all resource directory interfaces defined in this document. 1660 11.1. Endpoint Identification and Authentication 1662 An Endpoint is determined to be unique by an RD by the Endpoint 1663 identifier parameter included during Registration, and any associated 1664 TLS or DTLS security bindings. An Endpoint MUST NOT be identified by 1665 its protocol, port or IP address as these may change over the 1666 lifetime of an Endpoint. 1668 Every operation performed by an Endpoint or Client on a resource 1669 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1670 Public Key or Certificate based security. Endpoints using a 1671 Certificate MUST include the Endpoint identifier as the Subject of 1672 the Certificate, and this identifier MUST be checked by a resource 1673 directory to match the Endpoint identifier included in the 1674 Registration message. 1676 11.2. Access Control 1678 Access control SHOULD be performed separately for the RD Function Set 1679 and the RD Lookup Function Set, as different endpoints may be 1680 authorized to register with an RD from those authorized to lookup 1681 endpoints from the RD. Such access control SHOULD be performed in as 1682 fine-grained a level as possible. For example access control for 1683 lookups could be performed either at the domain, endpoint or resource 1684 level. 1686 11.3. Denial of Service Attacks 1688 Services that run over UDP unprotected are vulnerable to unknowingly 1689 become part of a DDoS attack as UDP does not require return 1690 routability check. Therefore, an attacker can easily spoof the 1691 source IP of the target entity and send requests to such a service 1692 which would then respond to the target entity. This can be used for 1693 large-scale DDoS attacks on the target. Especially, if the service 1694 returns a response that is order of magnitudes larger than the 1695 request, the situation becomes even worse as now the attack can be 1696 amplified. DNS servers have been widely used for DDoS amplification 1697 attacks. There is also a danger that NTP Servers could become 1698 implicated in denial-of-service (DoS) attacks since they run on 1699 unprotected UDP, there is no return routability check, and they can 1700 have a large amplification factor. The responses from the NTP server 1701 were found to be 19 times larger than the request. A Resource 1702 Directory (RD) which responds to wild-card lookups is potentially 1703 vulnerable if run with CoAP over UDP. Since there is no return 1704 routability check and the responses can be significantly larger than 1705 requests, RDs can unknowingly become part of a DDoS amplification 1706 attack. Therefore, it is RECOMMENDED that implementations ensure 1707 return routability. This can be done, for example by responding to 1708 wild card lookups only over DTLS or TLS or TCP. 1710 12. IANA Considerations 1712 12.1. Resource Types 1714 "core.rd", "core.rd-group" and "core.rd-lookup" resource types need 1715 to be registered with the resource type registry defined by 1716 [RFC6690]. 1718 12.2. Link Extension 1720 The "exp" and "ins" attributes need to be registered when a future 1721 Web Linking link-extension registry is created (e.g. in RFC5988bis). 1723 12.3. IPv6 ND Resource Directory Address Option 1725 This document registers one new ND option type under the subregistry 1726 "IPv6 Neighbor Discovery Option Formats": 1728 o Resource Directory address Option (38) 1730 12.4. RD Parameter Registry 1732 This specification defines a new sub-registry for registration and 1733 lookup parameters called "RD Parameters" under "CoRE Parameters". 1734 Although this specification defines a basic set of parameters, it is 1735 expected that other standards that make use of this interface will 1736 define new ones. 1738 Each entry in the registry must include the human readable name of 1739 the parameter, the query parameter, validity requirements if any and 1740 a description. The query parameter MUST be a valid URI query key 1741 [RFC3986]. 1743 Initial entries in this sub-registry are as follows: 1745 +-----------+-------+---------------+-------------------------------+ 1746 | Name | Query | Validity | Description | 1747 +-----------+-------+---------------+-------------------------------+ 1748 | Endpoint | ep | | Name of the endpoint, max 63 | 1749 | Name | | | bytes | 1750 | Lifetime | lt | 60-4294967295 | Lifetime of the registration | 1751 | | | | in seconds | 1752 | Domain | d | | Domain to which this endpoint | 1753 | | | | belongs | 1754 | Endpoint | et | | Semantic name of the endpoint | 1755 | Type | | | | 1756 | Context | con | URI | The scheme, address and port | 1757 | | | | at which this server is | 1758 | | | | available | 1759 | Resource | res | | Name of the resource | 1760 | Name | | | | 1761 | Group | gp | | Name of a group in the RD | 1762 | Name | | | | 1763 | Page | page | Integer | Used for pagination | 1764 | Count | count | Integer | Used for pagination | 1765 | Resource | ins | | Instance Identifier | 1766 | Instance | | | | 1767 | Export | exp | | A link MAY be exported to | 1768 | | | | another Resource Directory | 1769 +-----------+-------+---------------+-------------------------------+ 1771 Table 1: RD Parameters 1773 The IANA policy for future additions to the sub-registry is "Expert 1774 Review" as described in [RFC5226]. 1776 13. Examples 1778 Examples are added here. 1780 13.1. Lighting Installation 1782 This example shows a simplified lighting installation which makes use 1783 of the Resource Directory (RD) with a CoAP interface to facilitate 1784 the installation and start up of the application code in the lights 1785 and sensors. In particular, the example leads to the definition of a 1786 group and the enabling of the corresponding multicast address. No 1787 conclusions must be drawn on the realization of actual installation 1788 or naming procedures, because the example only "emphasizes" some of 1789 the issues that may influence the use of the RD and does not pretend 1790 to be normative. 1792 13.1.1. Installation Characteristics 1794 The example assumes that the installation is managed. That means 1795 that a Commissioning Tool (CT) is used to authorize the addition of 1796 nodes, name them, and name their services. The CT can be connected 1797 to the installation in many ways: the CT can be part of the 1798 installation network, connected by WiFi to the installation network, 1799 or connected via GPRS link, or other method. 1801 It is assumed that there are two naming authorities for the 1802 installation: (1) the network manager that is responsible for the 1803 correct operation of the network and the connected interfaces, and 1804 (2) the lighting manager that is responsible for the correct 1805 functioning of networked lights and sensors. The result is the 1806 existence of two naming schemes coming from the two managing 1807 entities. 1809 The example installation consists of one presence sensor, and two 1810 luminaries, luminary1 and luminary2, each with their own wireless 1811 interface. Each luminary contains three lamps: left, right and 1812 middle. Each luminary is accessible through one endpoint. For each 1813 lamp a resource exists to modify the settings of a lamp in a 1814 luminary. The purpose of the installation is that the presence 1815 sensor notifies the presence of persons to a group of lamps. The 1816 group of lamps consists of: middle and left lamps of luminary1 and 1817 right lamp of luminary2. 1819 Before commissioning by the lighting manager, the network is 1820 installed and access to the interfaces is proven to work by the 1821 network manager. 1823 At the moment of installation, the network under installation is not 1824 necessarily connected to the DNS infra structure. Therefore, SLAAC 1825 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 1826 Table 2 below: 1828 +--------------------+--------------+ 1829 | Name | IPv6 address | 1830 +--------------------+--------------+ 1831 | luminary1 | FDFD::ABCD:1 | 1832 | luminary2 | FDFD::ABCD:2 | 1833 | Presence sensor | FDFD::ABCD:3 | 1834 | Resource directory | FDFD::ABCD:0 | 1835 +--------------------+--------------+ 1837 Table 2: interface SLAAC addresses 1839 In Section 13.1.2 the use of resource directory during installation 1840 is presented. In Section 13.1.3 the connection to DNS is discussed. 1842 13.1.2. RD entries 1844 It is assumed that access to the DNS infrastructure is not always 1845 possible during installation. Therefore, the SLAAC addresses are 1846 used in this section. 1848 For discovery, the resource types (rt) of the devices are important. 1849 The lamps in the luminaries have rt: light, and the presence sensor 1850 has rt: p-sensor. The endpoints have names which are relevant to the 1851 light installation manager. In this case luminary1, luminary2, and 1852 the presence sensor are located in room 2-4-015, where luminary1 is 1853 located at the window and luminary2 and the presence sensor are 1854 located at the door. The endpoint names reflect this physical 1855 location. The middle, left and right lamps are accessed via path 1856 /light/middle, /light/left, and /light/right respectively. The 1857 identifiers relevant to the Resource Directory are shown in Table 3 1858 below: 1860 +----------------+------------------+---------------+---------------+ 1861 | Name | endpoint | resource path | resource type | 1862 +----------------+------------------+---------------+---------------+ 1863 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 1864 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 1865 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 1866 | luminary2 | lm_R2-4-015_door | /light/left | light | 1867 | luminary2 | lm_R2-4-015_door | /light/middle | light | 1868 | luminary2 | lm_R2-4-015_door | /light/right | light | 1869 | Presence | ps_R2-4-015_door | /ps | p-sensor | 1870 | sensor | | | | 1871 +----------------+------------------+---------------+---------------+ 1873 Table 3: Resource Directory identifiers 1875 The CT inserts the endpoints of the luminaries and the sensor in the 1876 RD using the Context parameter (con) to specify the interface 1877 address: 1879 Req: POST coap://[FDFD::ABCD:0]/rd 1880 ?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1] 1881 Payload: 1882 ;rt="light"; d="R2-4-015", 1883 ;rt="light"; d="R2-4-015", 1884 ;rt="light";d="R2-4-015" 1886 Res: 2.01 Created 1887 Location: /rd/4521 1889 Req: POST coap://[FDFD::ABCD:0]/rd 1890 ?ep=lm_R2-4-015_door&con=coap://[FDFD::ABCD:2] 1891 Payload: 1892 ;rt="light"; d="R2-4-015", 1893 ;rt="light"; d="R2-4-015", 1894 ;rt="light"; d="R2-4-015" 1896 Res: 2.01 Created 1897 Location: /rd/4522 1899 Req: POST coap://[FDFD::ABCD:0]/rd 1900 ?ep=ps_R2-4-015_door&con=coap://[FDFD::ABCD:3] 1901 Payload: 1902 ;rt="p-sensor"; d="R2-4-015" 1904 Res: 2.01 Created 1905 Location: /rd/4523 1907 The domain name d="R2-4-015" has been added for an efficient lookup 1908 because filtering on "ep" name is more awkward. The same domain name 1909 is communicated to the two luminaries and the presence sensor by the 1910 CT. 1912 The group is specified in the RD. The Context parameter is set to 1913 the site-local multicast address allocated to the group. In the POST 1914 in the example below, these two endpoints and the endpoint of the 1915 presence sensor are registered as members of the group. 1917 Req: POST coap://[FDFD::ABCD:0]/rd-group 1918 ?gp=grp_R2-4-015;con="coap//[FF05::1]";exp;ins="grp1234" 1919 Payload: 1920 <>ep=lm_R2-4-015_wndw, 1921 <>ep=lm_R2-4-015_door, 1922 <>ep=ps_R2-4-015_door 1924 Res: 2.01 Created 1925 Location: /rd-group/501 1926 After the filling of the RD by the CT, the application in the 1927 luminaries can learn to which groups they belong, and enable their 1928 interface for the multicast address. 1930 The luminary, knowing its domain, queries the RD for the endpoint 1931 with rt=light and d=R2-4-015. The RD returns all endpoints in the 1932 domain. 1934 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep 1935 ?d=R2-4-015;rt=light 1937 Res: 2.05 Content 1938 ; 1939 ep="lm_R2-4-015_wndw", 1940 ; 1941 ep="lm_R2-4-015_door" 1943 Knowing its own IPv6 address, the luminary discovers its endpoint 1944 name. With the endpoint name the luminary queries the RD for all 1945 groups to which the endpoint belongs. 1947 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/gp 1948 ?ep=lm_R2-4-015_wndw 1950 Res: 2.05 Content 1951 ;gp="grp_R2-4-015" 1953 From the context parameter value, the luminary learns the multicast 1954 address of the multicast group. 1956 Alternatively, the CT can communicate the multicast address directly 1957 to the luminaries by using the "coap-group" resource specified in 1958 [RFC7390]. 1960 Req: POST //[FDFD::ABCD:1]/coap-group 1961 Content-Format: application/coap-group+json 1962 { "a": "[FF05::1]", 1963 "n": "grp_R2-4-015"} 1965 Res: 2.01 Created 1966 Location-Path: /coap-group/1 1968 Dependent on the situation only the address ,"a", or the name, "n", 1969 is specified in the coap-group resource. 1971 13.1.3. DNS entries 1973 It may be profitable to discover the light groups for applications, 1974 which are unaware ot the existence of the RD. An agent needs to 1975 query the RD to return all groups which are exported to be inserted 1976 into DNS. 1978 Req: GET /rd-lookup/gp?exp 1980 Res: 2.05 Content 1981 ;exp;gp="grp_R2-4-015;ins="grp1234"; 1982 ep="lm_R2-4-015_wndw"; 1983 ep="lm_R2-4-015_door 1985 The group with FQDN grp_R2-4-015.bc.example.com can be entered into 1986 the DNS by the agent. The accompanying instance name is grp1234. 1987 The is chosen to be _group._udp. The agent enters the 1988 following RRs into the DNS. 1990 grp_R2-4-015.bc.example.com. IN AAAA FF05::1 1991 _group._udp.bc.example.com IN PTR 1992 grp1234._group._udp.bc.example.com 1993 grp1234._group._udp.bc.example.com IN SRV 0 0 5683 1994 grp_R2-4-015_door.bc.example.com. 1995 grp1234._group._udp.bc.example.com IN TXT 1996 txtver=1;path=/light/grp1 1998 From then on applications, not familiar with the existence of the RD, 1999 can use DNS to access the lighting group. 2001 13.2. OMA Lightweight M2M (LWM2M) Example 2003 This example shows how the OMA LWM2M specification makes use of 2004 Resource Directory (RD). 2006 OMA LWM2M is a profile for device services based on CoAP(OMA Name 2007 Authority). LWM2M defines a simple object model and a number of 2008 abstract interfaces and operations for device management and device 2009 service enablement. 2011 An LWM2M server is an instance of an LWM2M middleware service layer, 2012 containing a Resource Directory along with other LWM2M interfaces 2013 defined by the LWM2M specification. 2015 CoRE Resource Directory (RD) is used to provide the LWM2M 2016 Registration interface. 2018 LWM2M does not provide for registration domains and does not 2019 currently use the rd-group or rd-lookup interfaces. 2021 The LWM2M specification describes a set of interfaces and a resource 2022 model used between a LWM2M device and an LWM2M server. Other 2023 interfaces, proxies, applications, and function sets are currently 2024 out of scope for LWM2M. 2026 The location of the LWM2M Server and RD Function Set is provided by 2027 the LWM2M Bootstrap process, so no dynamic discovery of the RD 2028 function set is used. LWM2M Servers and endpoints are not required 2029 to implement the ./well-known/core resource. 2031 13.2.1. The LWM2M Object Model 2033 The OMA LWM2M object model is based on a simple 2 level class 2034 hierarchy consisting of Objects and Resources. 2036 An LWM2M Resource is a REST endpoint, allowed to be a single value or 2037 an array of values of the same data type. 2039 An LWM2M Object is a resource template and container type that 2040 encapsulates a set of related resources. An LWM2M Object represents 2041 a specific type of information source; for example, there is a LWM2M 2042 Device Management object that represents a network connection, 2043 containing resources that represent individual properties like radio 2044 signal strength. 2046 Since there may potentially be more than one of a given type object, 2047 for example more than one network connection, LWM2M defines instances 2048 of objects that contain the resources that represent a specific 2049 physical thing. 2051 The URI template for LWM2M consists of a base URI followed by Object, 2052 Instance, and Resource IDs: 2054 {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- 2055 instance} 2057 The five variables given here are strings. base-uri can also have 2058 the special value "undefined" (sometimes called "null" in RFC 6570). 2059 Each of the variables object-instance, resource-id, and resource- 2060 instance can be the special value "undefined" only if the values 2061 behind it in this sequence also are "undefined". As a special case, 2062 object-instance can be "empty" (which is different from "undefined") 2063 if resource-id is not "undefined". [_TEMPLATE_TODO] 2064 base-uri := Base URI for LWM2M resources or "undefined" for default 2065 (empty) base URI 2067 object-id := OMNA (OMA Name Authority) registered object ID (0-65535) 2069 object-instance := Object instance identifier (0-65535) or 2070 "undefined"/"empty" (see above)) to refer to all instances of an 2071 object ID 2073 resource-id := OMNA (OMA Name Authority) registered resource ID 2074 (0-65535) or "undefined" to refer to all resources within an instance 2076 resource-instance := Resource instance identifier or "undefined" to 2077 refer to single instance of a resource 2079 LWM2M IDs are 16 bit unsigned integers represented in decimal (no 2080 leading zeroes except for the value 0) by URI format strings. For 2081 example, a LWM2M URI might be: 2083 /1/0/1 2085 The base uri is empty, the Object ID is 1, the instance ID is 0, the 2086 resource ID is 1, and the resource instance is "undefined". This 2087 example URI points to internal resource 1, which represents the 2088 registration lifetime configured, in instance 0 of a type 1 object 2089 (LWM2M Server Object). 2091 13.2.2. LWM2M Register Endpoint 2093 LWM2M defines a registration interface based on the Resource 2094 Directory Function Set, described in Section 6. The URI of the LWM2M 2095 Resource Directory function set is specified to be "/rd" as 2096 recommended in Section 6.3. 2098 LWM2M endpoints register object IDs, for example , to indicate 2099 that a particular object type is supported, and register object 2100 instances, for example , to indicate that a particular instance 2101 of that object type exists. 2103 Resources within the LWM2M object instance are not registered with 2104 the RD, but may be discovered by reading the resource links from the 2105 object instance using GET with a CoAP Content-Format of application/ 2106 link-format. Resources may also be read as a structured object by 2107 performing a GET to the object instance with a Content-Format of 2108 senml+json. 2110 When an LWM2M object or instance is registered, this indicates to the 2111 LWM2M server that the object and its resources are available for 2112 management and service enablement (REST API) operations. 2114 LWM2M endpoints may use the following RD registration parameters as 2115 defined in Table 1 : 2117 ep - Endpoint Name 2118 lt - registration lifetime 2120 Endpoint Name is mandatory, all other registration parameters are 2121 optional. 2123 Additional optional LWM2M registration parameters are defined: 2125 +------------+-------+-------------------------------+--------------+ 2126 | Name | Query | Validity | Description | 2127 +------------+-------+-------------------------------+--------------+ 2128 | Protocol | b | {"U",UQ","S","SQ","US","UQS"} | Available | 2129 | Binding | | | Protocols | 2130 | | | | | 2131 | LWM2M | ver | 1.0 | Spec Version | 2132 | Version | | | | 2133 | | | | | 2134 | SMS Number | sms | | MSISDN | 2135 +------------+-------+-------------------------------+--------------+ 2137 Table 4: LWM2M Additional Registration Parameters 2139 The following RD registration parameters are not currently specified 2140 for use in LWM2M: 2142 et - Endpoint Type 2143 con - Context 2145 The endpoint registration must include a payload containing links to 2146 all supported objects and existing object instances, optionally 2147 including the appropriate link-format relations. 2149 Here is an example LWM2M registration payload: 2151 ,,, 2153 This link format payload indicates that object ID 1 (LWM2M Server 2154 Object) is supported, with a single instance 0 existing, object ID 3 2155 (LWM2M Device object) is supported, with a single instance 0 2156 existing, and object 5 (LWM2M Firmware Object) is supported, with no 2157 existing instances. 2159 13.2.3. Alternate Base URI 2161 If the LWM2M endpoint exposes objects at a base URI other than the 2162 default empty base path, the endpoint must register the base URI 2163 using rt="oma.lwm2m". An example link payload using alternate base 2164 URI would be: 2166 ;rt="oma.lwm2m",,, 2168 This link payload indicates that the lwm2m objects will be placed 2169 under the base URI "/my_lwm2m" and that object ID 1 (server) is 2170 supported, with a single instance 0 existing, and object 5 (firmware 2171 update) is supported. 2173 13.2.4. LWM2M Update Endpoint Registration 2175 An LWM2M Registration update proceeds as described in Section 6.4, 2176 and adds some optional parameter updates: 2178 lt - Registration Lifetime 2179 b - Protocol Binding 2180 sms - MSISDN 2181 link payload - new or modified links 2183 A Registration update is also specified to be used to update the 2184 LWM2M server whenever the endpoint's UDP port or IP address are 2185 changed. 2187 13.2.5. LWM2M De-Register Endpoint 2189 LWM2M allows for de-registration using the delete method on the 2190 returned location from the initial registration operation. LWM2M de- 2191 registration proceeds as described in Section 6.5. 2193 14. Acknowledgments 2195 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2196 Brandt, Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have 2197 provided helpful comments, discussions and ideas to improve and shape 2198 this document. Section 9 is based on an earlier draft by Kerry Lynn. 2199 Zach would also like to thank his colleagues from the EU FP7 SENSEI 2200 project, where many of the resource directory concepts were 2201 originally developed. 2203 15. Changelog 2205 changes from -07 to -08 2207 o removed link target value returned from domain and group lookup 2208 types 2210 o Maximum length of domain parameter 63 bytes for consistency with 2211 group 2213 o removed option for simple POST of link data, don't require a 2214 .well-known/core resource to accept POST data and handle it in a 2215 special way; we already have /rd for that 2217 o add IPv6 ND Option for discovery of an RD 2219 o clarify group configuration section 6.1 that endpoints must be 2220 registered before including them in a group 2222 o removed all superfluous client-server diagrams 2224 o simplified lighting example 2226 o introduced Commissioning Tool 2228 o RD-Look-up text is extended. 2230 changes from -06 to -07 2232 o added text in the discovery section to allow content format hints 2233 to be exposed in the discovery link attributes 2235 o editorial updates to section 9 2237 o update author information 2239 o minor text corrections 2241 Changes from -05 to -06 2243 o added note that the PATCH section is contingent on the progress of 2244 the PATCH method 2246 changes from -04 to -05 2248 o added Update Endpoint Links using PATCH 2250 o http access made explicit in interface specification 2251 o Added http examples 2253 Changes from -03 to -04: 2255 o Added http response codes 2257 o Clarified endpoint name usage 2259 o Add application/link-format+cbor content-format 2261 Changes from -02 to -03: 2263 o Added an example for lighting and DNS integration 2265 o Added an example for RD use in OMA LWM2M 2267 o Added Read Links operation for link inspection by endpoints 2269 o Expanded DNS-SD section 2271 o Added draft authors Peter van der Stok and Michael Koster 2273 Changes from -01 to -02: 2275 o Added a catalogue use case. 2277 o Changed the registration update to a POST with optional link 2278 format payload. Removed the endpoint type update from the update. 2280 o Additional examples section added for more complex use cases. 2282 o New DNS-SD mapping section. 2284 o Added text on endpoint identification and authentication. 2286 o Error code 4.04 added to Registration Update and Delete requests. 2288 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 2289 resource type parameters. 2291 Changes from -00 to -01: 2293 o Removed the ETag validation feature. 2295 o Place holder for the DNS-SD mapping section. 2297 o Explicitly disabled GET or POST on returned Location. 2299 o New registry for RD parameters. 2301 o Added support for the JSON Link Format. 2303 o Added reference to the Groupcomm WG draft. 2305 Changes from -05 to WG Document -00: 2307 o Updated the version and date. 2309 Changes from -04 to -05: 2311 o Restricted Update to parameter updates. 2313 o Added pagination support for the Lookup interface. 2315 o Minor editing, bug fixes and reference updates. 2317 o Added group support. 2319 o Changed rt to et for the registration and update interface. 2321 Changes from -03 to -04: 2323 o Added the ins= parameter back for the DNS-SD mapping. 2325 o Integrated the Simple Directory Discovery from Carsten. 2327 o Editorial improvements. 2329 o Fixed the use of ETags. 2331 o Fixed tickets 383 and 372 2333 Changes from -02 to -03: 2335 o Changed the endpoint name back to a single registration parameter 2336 ep= and removed the h= and ins= parameters. 2338 o Updated REST interface descriptions to use RFC6570 URI Template 2339 format. 2341 o Introduced an improved RD Lookup design as its own function set. 2343 o Improved the security considerations section. 2345 o Made the POST registration interface idempotent by requiring the 2346 ep= parameter to be present. 2348 Changes from -01 to -02: 2350 o Added a terminology section. 2352 o Changed the inclusion of an ETag in registration or update to a 2353 MAY. 2355 o Added the concept of an RD Domain and a registration parameter for 2356 it. 2358 o Recommended the Location returned from a registration to be 2359 stable, allowing for endpoint and Domain information to be changed 2360 during updates. 2362 o Changed the lookup interface to accept endpoint and Domain as 2363 query string parameters to control the scope of a lookup. 2365 16. References 2367 16.1. Normative References 2369 [I-D.ietf-core-links-json] 2370 Li, K., Rahman, A., and D. Bormann, "Representing CoRE 2371 Formats in JSON and CBOR", draft-ietf-core-links-json-05 2372 (work in progress), April 2016. 2374 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2375 Requirement Levels", BCP 14, RFC 2119, 2376 DOI 10.17487/RFC2119, March 1997, 2377 . 2379 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2380 Resource Identifier (URI): Generic Syntax", STD 66, 2381 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2382 . 2384 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2385 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2386 DOI 10.17487/RFC5226, May 2008, 2387 . 2389 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2390 DOI 10.17487/RFC5988, October 2010, 2391 . 2393 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2394 Cheshire, "Internet Assigned Numbers Authority (IANA) 2395 Procedures for the Management of the Service Name and 2396 Transport Protocol Port Number Registry", BCP 165, 2397 RFC 6335, DOI 10.17487/RFC6335, August 2011, 2398 . 2400 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2401 and D. Orchard, "URI Template", RFC 6570, 2402 DOI 10.17487/RFC6570, March 2012, 2403 . 2405 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2406 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2407 . 2409 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2410 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2411 . 2413 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 2414 DOI 10.17487/RFC7396, October 2014, 2415 . 2417 16.2. Informative References 2419 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2420 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 2421 . 2423 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2424 Application and Support", STD 3, RFC 1123, 2425 DOI 10.17487/RFC1123, October 1989, 2426 . 2428 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2429 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2430 2003, . 2432 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 2433 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 2434 . 2436 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 2437 Bormann, "Neighbor Discovery Optimization for IPv6 over 2438 Low-Power Wireless Personal Area Networks (6LoWPANs)", 2439 RFC 6775, DOI 10.17487/RFC6775, November 2012, 2440 . 2442 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2443 Protocol (HTTP/1.1): Message Syntax and Routing", 2444 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2445 . 2447 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2448 Application Protocol (CoAP)", RFC 7252, 2449 DOI 10.17487/RFC7252, June 2014, 2450 . 2452 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2453 the Constrained Application Protocol (CoAP)", RFC 7390, 2454 DOI 10.17487/RFC7390, October 2014, 2455 . 2457 Editorial Comments 2459 [_TEMPLATE_TODO] This text needs some help from an RFC 6570 expert. 2461 Authors' Addresses 2463 Zach Shelby 2464 ARM 2465 150 Rose Orchard 2466 San Jose 95134 2467 USA 2469 Phone: +1-408-203-9434 2470 Email: zach.shelby@arm.com 2472 Michael Koster 2473 SmartThings 2474 665 Clyde Avenue 2475 Mountain View 94043 2476 USA 2478 Phone: +1-707-502-5136 2479 Email: Michael.Koster@smartthings.com 2480 Carsten Bormann 2481 Universitaet Bremen TZI 2482 Postfach 330440 2483 Bremen D-28359 2484 Germany 2486 Phone: +49-421-218-63921 2487 Email: cabo@tzi.org 2489 Peter van der Stok 2490 consultant 2492 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2493 Email: consultancy@vanderstok.org 2494 URI: www.vanderstok.org