idnits 2.17.1 draft-ietf-core-resource-directory-09.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 (October 31, 2016) is 2728 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-06 ** 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: May 4, 2017 SmartThings 6 C. Bormann 7 Universitaet Bremen TZI 8 P. van der Stok 9 consultant 10 October 31, 2016 12 CoRE Resource Directory 13 draft-ietf-core-resource-directory-09 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 resource 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 May 4, 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 . . . . . . . . . . . . . . . . . . . 37 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 196 Commissioning Tool (CT) is a device that assists during the 197 installation of the network by assigning values to parameters, 198 naming endpoints and groups, or adapting the installation to the 199 needs of the applications. 201 RDAO 202 Resource Directory Address Option. 204 3. Architecture and Use Cases 206 The resource directory architecture is illustrated in Figure 1. A 207 Resource Directory (RD) is used as a repository for Web Links 208 [RFC5988] about resources hosted on other web servers, which are 209 called endpoints (EP). An endpoint is a web server associated with a 210 scheme, IP address and port (called Context), thus a physical node 211 may host one or more endpoints. The RD implements a set of REST 212 interfaces for endpoints to register and maintain sets of Web Links 213 (called resource directory entries), and for clients to lookup 214 resources from the RD or maintain groups. Endpoints themselves can 215 also act as clients. An RD can be logically segmented by the use of 216 Domains. The domain an endpoint is associated with can be defined by 217 the RD or configured by an outside entity. This information 218 hierarchy is shown in Figure 2. 220 Endpoints are assumed to proactively register and maintain resource 221 directory entries on the RD, which are soft state and need to be 222 periodically refreshed. An endpoint is provided with interfaces to 223 register, update and remove a resource directory entry. Furthermore, 224 a mechanism to discover an RD using the CoRE Link Format [RFC6690] is 225 defined. It is also possible for an RD to proactively discover Web 226 Links from endpoints and add them as resource directory entries. A 227 lookup interface for discovering any of the Web Links held in the RD 228 is provided using the CoRE Link Format. 230 Registration Lookup, Group 231 Interface Interfaces 232 +----+ | | 233 | EP |---- | | 234 +----+ ---- | | 235 --|- +------+ | 236 +----+ | ----| | | +--------+ 237 | EP | ---------|-----| RD |----|-----| Client | 238 +----+ | ----| | | +--------+ 239 --|- +------+ | 240 +----+ ---- | | 241 | EP |---- | | 242 +----+ 244 Figure 1: The resource directory architecture. 246 +------------+ 247 | Domain | <-- Name 248 +------------+ 249 | | 250 | +------------+ 251 | | Group | <-- Name, Scheme, IP, Port 252 | +------------+ 253 | | 254 +------------+ 255 | Endpoint | <-- Name, Scheme, IP, Port 256 +------------+ 257 | 258 | 259 +------------+ 260 | Resource | <-- Target, Parameters 261 +------------+ 263 Figure 2: The resource directory information hierarchy. 265 3.1. Use Case: Cellular M2M 267 Over the last few years, mobile operators around the world have 268 focused on development of M2M solutions in order to expand the 269 business to the new type of users: machines. The machines are 270 connected directly to a mobile network using an appropriate embedded 271 air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short 272 and wide range wireless interfaces. From the system design point of 273 view, the ambition is to design horizontal solutions that can enable 274 utilization of machines in different applications depending on their 275 current availability and capabilities as well as application 276 requirements, thus avoiding silo like solutions. One of the crucial 277 enablers of such design is the ability to discover resources 278 (machines -- endpoints) capable of providing required information at 279 a given time or acting on instructions from the end users. 281 In a typical scenario, during a boot-up procedure (and periodically 282 afterwards), the machines (endpoints) register with a Resource 283 Directory (for example EPs installed on vehicles enabling tracking of 284 their position for fleet management purposes and monitoring 285 environment parameters) hosted by the mobile operator or somewhere 286 else in the network, periodically a description of its own 287 capabilities. Due to the usual network configuration of mobile 288 networks, the EPs attached to the mobile network may not always be 289 efficiently reachable. Therefore, a remote server is usually used to 290 provide proxy access to the EPs. The address of each (proxy) 291 endpoint on this server is included in the resource description 292 stored in the RD. The users, for example mobile applications for 293 environment monitoring, contact the RD, look up the endpoints capable 294 of providing information about the environment using appropriate set 295 of link parameters, obtain information on how to contact them (URLs 296 of the proxy server) and then initiate interaction to obtain 297 information that is finally processed, displayed on the screen and 298 usually stored in a database. Similarly, fleet management systems 299 provide the appropriate link parameters to the RD to look up for EPs 300 deployed on the vehicles the application is responsible for. 302 3.2. Use Case: Home and Building Automation 304 Home and commercial building automation systems can benefit from the 305 use of M2M web services. The discovery requirements of these 306 applications are demanding. Home automation usually relies on run- 307 time discovery to commission the system, whereas in building 308 automation a combination of professional commissioning and run-time 309 discovery is used. Both home and building automation involve peer- 310 to-peer interactions between endpoints, and involve battery-powered 311 sleeping devices. 313 The exporting of resource information to other discovery systems is 314 also important in these automation applications. In home automation 315 there is a need to interact with other consumer electronics, which 316 may already support DNS-SD, and in building automation DNS-SD in 317 combination with resource directories can cover multiple buildings. 319 3.3. Use Case: Link Catalogues 321 Resources may be shared through data brokers that have no knowledge 322 beforehand of who is going to consume the data. Resource Directory 323 can be used to hold links about resources and services hosted 324 anywhere to make them discoverable by a general class of 325 applications. 327 For example, environmental and weather sensors that generate data for 328 public consumption may provide the data to an intermediary server, or 329 broker. Sensor data are published to the intermediary upon changes 330 or at regular intervals. Descriptions of the sensors that resolve to 331 links to sensor data may be published to a Resource Directory. 332 Applications wishing to consume the data can use the Resource 333 Directory lookup function set to discover and resolve links to the 334 desired resources and endpoints. The Resource Directory service need 335 not be coupled with the data intermediary service. Mapping of 336 Resource Directories to data intermediaries may be many-to-many. 338 Metadata in web-link compatible representations are supplied by 339 Resource Directories, which may be internally stored as triples, or 340 relation/attribute pairs providing metadata about resource links. 341 External catalogs that are represented in other formats may be 342 converted to common web linking formats for storage and access by 343 Resource Directories. Since it is common practice for these to be 344 URN encoded, simple and lossless structural transforms should 345 generally be sufficient to store external metadata in Resource 346 Directories. 348 The additional features of Resource Directory allow domains to be 349 defined to enable access to a particular set of resources from 350 particular applications. This provides isolation and protection of 351 sensitive data when needed. Resource groups may defined to allow 352 batched reads from multiple resources. 354 4. Finding a Directory Server 356 Endpoints that want to contact a directory server can obtain 357 candidate IP addresses for such servers in a number of ways. 359 In a 6LoWPAN, good candidates can be taken from: 361 o specific static configuration (e.g., anycast addresses), if any, 363 o the ABRO option of 6LoWPAN-ND [RFC6775], 365 o other ND options that happen to point to servers (such as RDNSS), 367 o DHCPv6 options that might be defined later. 369 o The IPv6 Neighbor Discovery Resource Directory Address Option 370 described in Section 4.1 372 In networks with more inexpensive use of multicast, the candidate IP 373 address may be a well-known multicast address, i.e. directory servers 374 are found by simply sending GET requests to that well-known multicast 375 address (see Section 6.2). 377 As some of these sources are just (more or less educated) guesses, 378 endpoints MUST make use of any error messages to very strictly rate- 379 limit requests to candidate IP addresses that don't work out. For 380 example, an ICMP Destination Unreachable message (and, in particular, 381 the port unreachable code for this message) may indicate the lack of 382 a CoAP server on the candidate host, or a CoAP error response code 383 such as 4.05 "Method Not Allowed" may indicate unwillingness of a 384 CoAP server to act as a directory server. 386 4.1. Resource Directory Address Option (RDAO) 388 The Resource Directory Option (RDAO) using IPv6 neighbor Discovery 389 (ND) carries information about the address of the Resource Directory 390 (RD). This information is needed when endpoints cannot discover the 391 Resource Directory with link-local multicast address because the 392 endpoint and the RD are separated by a border Router (6LBR). In many 393 circumstances the availability of DHCP cannot be guaranteed either 394 during commissioning of the network. The presence and the use of the 395 RD is essential during commissioning. 397 It is possible to send multiple RDAO options in one message, 398 indicating as many resource directory addresses. 400 The lifetime 0x0 means that the RD address is invalid and to be 401 removed. 403 The RDAO format is: 405 0 1 2 3 406 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 407 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 408 | Type | Length = 3 | Valid Lifetime | 409 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 410 | Reserved | 411 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 412 | | 413 + + 414 | | 415 + RD Address + 416 | | 417 + + 418 | | 419 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 421 Fields: 423 Type: 38 425 Length: 8-bit unsigned integer. The length of 426 the option in units of 8 bytes. 427 Always 3. 429 Valid Lifetime: 16-bit unsigned integer. The length of 430 time in units of 60 seconds (relative to 431 the time the packet is received) that 432 this set of border router information is 433 valid. A value of all zero bits (0x0) 434 assumes a default value of 10,000 435 (~one week). 437 Reserved: This field is unused. It MUST be 438 initialized to zero by the sender and 439 MUST be ignored by the receiver. 441 RD Address: IPv6 address of the RD. 443 Figure 3: Resource Directory Address Option 445 5. Simple Registration 447 Not all endpoints hosting resources are expected to know how to 448 implement the Resource Directory Function Set (see Section 6) hence 449 cannot register with a Resource Directory. Instead, simple endpoints 450 can implement the generic Simple Directory Discovery approach 451 described in this section. An RD implementing this specification 452 MUST implement Simple Directory Discovery. However, there may be 453 security reasons why this form of directory discovery would be 454 disabled. 456 This approach requires that the endpoint makes available the hosted 457 resources that it wants to be discovered, as links on its "/.well- 458 known/core" interface as specified in [RFC6690]. 460 The endpoint then finds one or more addresses of the directory server 461 as described in Section 4. 463 An endpoint can send (a selection of) hosted resources to a directory 464 server for publication as described in Section 5.1. 466 The directory server integrates the information it received this way 467 into its resource directory. It MAY make the information available 468 to further directories, if it can ensure that a loop does not form. 469 The protocol used between directories to ensure loop-free operation 470 is outside the scope of this document. 472 5.1. Simple publishing to Resource Directory Server 474 An endpoint that wants to make itself discoverable occasionally sends 475 a POST request to the "/.well-known/core" URI of any candidate 476 directory server that it finds. The body of the POST request is 477 empty, which triggers the resource directory server to perform GET 478 requests at the requesting server's default discovery URI to obtain 479 the link-format payload to register. 481 The endpoint MAY include registration parameters in the POST request 482 as per Section 6.3. 484 The following example shows an endpoint using simple publishing, by 485 simply sending an empty POST to a resource directory. 487 Req:(to RD server from [ff02::1]) 488 POST coap://rd.example.com/.well-known/core?lt=6000 490 Content-Format: 40 492 payload: 494 (empty payload) 496 Res: 2.04 Changed 498 (later) 500 Req: (from RD server to [ff02::1]) 501 GET coap://[ff02::1]/.well-known/core 503 Accept: 40 505 Res: 2.05 Content 507 payload: 509 511 5.2. Third-party registration 513 For some applications, even Simple Directory Discovery may be too 514 taxing for certain very constrained devices, in particular if the 515 security requirements become too onerous. 517 In a controlled environment (e.g. building control), the Resource 518 Directory can be filled by a third device, called a commissioning 519 tool. The commissioning tool can fill the Resource Directory from a 520 database or other means. For that purpose the scheme, IP address and 521 port of the registered device is indicated in the Context parameter 522 of the registration described in Section 6.3. 524 6. Resource Directory Function Set 526 This section defines the REST interfaces between an RD and endpoints, 527 which is called the Resource Directory Function Set. Although the 528 examples throughout this section assume the use of CoAP [RFC7252], 529 these REST interfaces can also be realized using HTTP [RFC7230]. In 530 all definitions in this section, both CoAP response codes (with dot 531 notation) and HTTP response codes (without dot notation) are shown. 532 An RD implementing this specification MUST support the discovery, 533 registration, update, lookup, and removal interfaces defined in this 534 section. 536 Resource directory entries are designed to be easily exported to 537 other discovery mechanisms such as DNS-SD. For that reason, 538 parameters that would meaningfully be mapped to DNS SHOULD be limited 539 to a maximum length of 63 bytes. 541 6.1. Content Formats 543 Resource Directory implementations using this specification MUST 544 support the application/link-format content format (ct=40). 546 Resource Directories implementing this specification MAY support 547 additional content formats. 549 Any additional content format supported by a Resource Directory 550 implementing this specification MUST have an equivalent serialization 551 in the application/link-format content format. 553 6.2. Discovery 555 Before an endpoint can make use of an RD, it must first know the RD's 556 address and port, and the path of its RD Function Set. There can be 557 several mechanisms for discovering the RD including assuming a 558 default location (e.g. on an Edge Router in a LoWPAN), by assigning 559 an anycast address to the RD, using DHCP, or by discovering the RD 560 using the CoRE Link Format (see also Section 4). This section 561 defines discovery of the RD using the well-known interface of the 562 CoRE Link Format [RFC6690] as the required mechanism. It is however 563 expected that RDs will also be discoverable via other methods 564 depending on the deployment. 566 Discovery of the RD function set is performed by sending either a 567 multicast or unicast GET request to "/.well-known/core" and including 568 a Resource Type (rt) parameter [RFC6690] with the value "core.rd" in 569 the query string. Likewise, a Resource Type parameter value of 570 "core.rd-lookup" is used to discover the RD Lookup Function Set. 571 Upon success, the response will contain a payload with a link format 572 entry for each RD discovered, with the URL indicating the root 573 resource of the RD. When performing multicast discovery, the 574 multicast IP address used will depend on the scope required and the 575 multicast capabilities of the network. 577 A Resource Directory MAY provide hints about the content-formats it 578 supports in the links it exposes or registers, using the "ct" link 579 attribute, as shown in the example below. Clients MAY use these 580 hints to select alternate content-formats for interaction with the 581 Resource Directory. 583 HTTP does not support multicast and consequently only unicast 584 discovery can be supported using HTTP. Links to Resource Directories 585 MAY be registered in other Resource Directories, and well-known entry 586 points SHOULD be provided to enable the bootstrapping of unicast 587 discovery. 589 An RD implementation of this specification MUST support query 590 filtering for the rt parameter as defined in [RFC6690]. 592 The discovery request interface is specified as follows: 594 Interaction: EP -> RD 596 Method: GET 598 URI Template: /.well-known/core{?rt} 600 URI Template Variables: 602 rt := Resource Type (optional). MAY contain one or more of the 603 values "core.rd", "core.rd-lookup", "core.rd-group" or 604 "core.rd*" 606 Content-Format: application/link-format (if any) 608 Content-Format: application/link-format+json (if any) 610 Content-Format: application/link-format+cbor (if any) 612 The following response codes are defined for this interface: 614 Success: 2.05 "Content" with an application/link-format, 615 application/link-format+json, or application/link-format+cbor 616 payload containing one or more matching entries for the RD 617 resource. 619 Failure: 4.04 "Not Found" is returned in case no matching entry is 620 found for a unicast request. 622 Failure: 4.00 "Bad Request" is returned in case of a malformed 623 request for a unicast request. 625 Failure: No error response to a multicast request. 627 HTTP support : YES (Unicast only) 629 The following example shows an endpoint discovering an RD using this 630 interface, thus learning that the base RD resource is, in this 631 example, at /rd and that the content_format delivered by the server 632 hosting the resource is application.xml (ct=40). Note that it is up 633 to the RD to choose its base RD resource, although diagnostics and 634 debugging is facilitated by using the base paths specified here where 635 possible. 637 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 639 Res: 2.05 Content 640 ;rt="core.rd";ct=40, 641 ;rt="core.rd-lookup";ct=40, 642 ;rt="core.rd-group";ct=40 644 The following example shows the way of indicating that a client may 645 request alternate content-formats. The Content-Format code attribute 646 "ct" MAY include a space-separated sequence of Content-Format codes 647 as specified in Section 7.2.1 of [RFC7252], indicating that multiple 648 content-formats are available. The example below shows the required 649 Content-Format 40 (application/link-format) indicated as well as a 650 more application-specific content format (picked as 65225 in this 651 example; this is in the experimental space, not an assigned value). 652 The base RD resource values /rd, /rd-lookup, and /rd-group are 653 example values. 655 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 657 Res: 2.05 Content 658 ;rt="core.rd";ct="40 65225", 659 ;rt="core.rd-lookup";ct="40 65225", 660 ;rt="core.rd-group";ct="40 65225" 662 6.3. Registration 664 After discovering the location of an RD Function Set, an endpoint MAY 665 register its resources using the registration interface. This 666 interface accepts a POST from an endpoint containing the list of 667 resources to be added to the directory as the message payload in the 668 CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link- 669 format+json), or CBOR CoRE Link Format (application/link-format+cbor) 670 [I-D.ietf-core-links-json], along with query string parameters 671 indicating the name of the endpoint, its domain and the lifetime of 672 the registration. All parameters except the endpoint name are 673 optional. It is expected that other specifications will define 674 further parameters (see Section 12.4). The RD then creates a new 675 resource or updates an existing resource in the RD and returns its 676 location. An endpoint MUST use that location when refreshing 677 registrations using this interface. Endpoint resources in the RD are 678 kept active for the period indicated by the lifetime parameter. The 679 endpoint is responsible for refreshing the entry within this period 680 using either the registration or update interface. The registration 681 interface MUST be implemented to be idempotent, so that registering 682 twice with the same endpoint parameter does not create multiple RD 683 entries. A new registration may be created at any time to supersede 684 an existing registration, replacing the registration parameters and 685 links. 687 The registration request interface is specified as follows: 689 Interaction: EP -> RD 691 Method: POST 693 URI Template: /{+rd}{?ep,d,et,lt,con} 695 URI Template Variables: 697 rd := RD Function Set path (mandatory). This is the path of the 698 RD Function Set, as obtained from discovery. The value "rd" is 699 recommended for this variable. 701 ep := Endpoint name (mandatory). The endpoint name is an 702 identifier that MUST be unique within a domain. The maximum 703 length of this parameter is 63 bytes. 705 d := Domain (optional). The domain to which this endpoint 706 belongs. The maximum length of this parameter is 63 bytes. 707 When this parameter is elided, the RD MAY associate the 708 endpoint with a configured default domain. The domain value is 709 needed to export the endpoint to DNS-SD (see Section 10). 711 et := Endpoint Type (optional). The semantic type of the 712 endpoint. This parameter SHOULD be less than 63 bytes. 714 lt := Lifetime (optional). Lifetime of the registration in 715 seconds. Range of 60-4294967295. If no lifetime is included, 716 a default value of 86400 (24 hours) SHOULD be assumed. 718 con := Context (optional). This parameter sets the scheme, 719 address and port at which this server is available in the form 720 scheme://host:port. In the absence of this parameter the 721 scheme of the protocol, source IP address and source port of 722 the register request are assumed. This parameter is mandatory 723 when the directory is filled by a third party such as an 724 commissioning tool. 726 Content-Format: application/link-format 727 Content-Format: application/link-format+json 729 Content-Format: application/link-format+cbor 731 The following response codes are defined for this interface: 733 Success: 2.01 "Created" or 201 "Created". The Location header MUST 734 be included with the new resource entry for the endpoint. This 735 Location MUST be a stable identifier generated by the RD as it is 736 used for all subsequent operations on this registration. The 737 resource returned in the Location is for the purpose of updating 738 the lifetime of the registration and for maintaining the content 739 of the registered links, including updating and deleting links. 741 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 742 request. 744 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 745 Service could not perform the operation. 747 HTTP support: YES 749 The following example shows an endpoint with the name "node1" 750 registering two resources to an RD using this interface. The 751 location "/rd" is an example value of an RD base location. 753 Req: POST coap://rd.example.com/rd?ep=node1 754 Content-Format: 40 755 Payload: 756 ;ct=41;rt="temperature-c";if="sensor", 757 ;ct=41;rt="light-lux";if="sensor" 759 Res: 2.01 Created 760 Location: /rd/4521 762 Req: POST /rd?ep=node1 HTTP/1.1 763 Host : example.com 764 Content-Type: application/link-format 765 Payload: 766 ;ct=41;rt="temperature-c";if="sensor", 767 ;ct=41;rt="light-lux";if="sensor" 769 Res: 201 Created 770 Location: /rd/4521 772 6.4. Registration Update 774 The update interface is used by an endpoint to refresh or update its 775 registration with an RD. To use the interface, the endpoint sends a 776 POST request to the resource returned in the Location option in the 777 response to the first registration. 779 An update MAY update the lifetime or context registration parameters 780 "lt", "con" as in Section 6.3 ) if they have changed since the last 781 registration or update. Parameters that have not changed SHOULD NOT 782 be included in an update. Adding parameters that have not changed 783 increases the size of the message but does not have any other 784 implications. Parameters MUST be included as query parameters in an 785 update operation as in Section 6.3. 787 Upon receiving an update request, an RD MUST reset the timeout for 788 that endpoint and update the scheme, IP address and port of the 789 endpoint, using the source address of the update, or the context 790 ("con") parameter if present. If the lifetime parameter "lt" is 791 included in the received update request, the RD MUST update the 792 lifetime of the registration and set the timeout equal to the new 793 lifetime. 795 An update MAY optionally add or replace links for the endpoint by 796 including those links in the payload of the update as a CoRE Link 797 Format document. A link is replaced only if both the target URI and 798 relation type match. 800 In addition to the use of POST, as described in this section, there 801 is an alternate way to add, replace, and delete links using PATCH as 802 described in Section 6.7. 804 The update registration request interface is specified as follows: 806 Interaction: EP -> RD 808 Method: POST 810 URI Template: /{+location}{?lt,con} 812 URI Template Variables: 814 location := This is the Location path returned by the RD as a 815 result of a successful earlier registration. 817 lt := Lifetime (optional). Lifetime of the registration in 818 seconds. Range of 60-4294967295. If no lifetime is included, 819 a default value of 86400 (24 hours) SHOULD be assumed. 821 con := Context (optional). This parameter sets the scheme, 822 address and port at which this server is available in the form 823 scheme://host:port. Optional. In the absence of this 824 parameter the scheme of the protocol, source IP address and 825 source port used to register are assumed. This parameter is 826 compulsory when the directory is filled by a third party such 827 as a commissioning tool. 829 Content-Format: application/link-format (mandatory) 831 Content-Format: application/link-format+json (optional) 833 Content-Format: application/link-format+cbor (optional) 835 The following response codes are defined for this interface: 837 Success: 2.04 "Changed" or 204 "No Content" if the update was 838 successfully processed. 840 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 841 request. 843 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 844 exist (e.g. may have expired). 846 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 847 Service could not perform the operation. 849 HTTP support: YES 851 The following example shows an endpoint updating its registration at 852 an RD using this interface with the example location value: /rd/4521. 854 Req: POST /rd/4521 856 Res: 2.04 Changed 858 The following example shows an endpoint updating its registration 859 with a new lifetime and context, changing an existing link, and 860 adding a new link using this interface with the example location 861 value /rd/4521. With the initial registration the client set the 862 following values: 864 o lifetime (lt)=500 866 o context (con)=coap://local-proxy-old.example.com:5683 868 o resource= ;ct=41;rt="foobar";if="sensor" 869 Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683" 870 Content-Format: 40 871 Payload: 872 ;ct=41;rt="temperature-f";if="sensor", 873 ;ct=41;rt="door";if="sensor" 875 Res: 2.04 Changed 877 6.5. Registration Removal 879 Although RD entries have soft state and will eventually timeout after 880 their lifetime, an endpoint SHOULD explicitly remove its entry from 881 the RD if it knows it will no longer be available (for example on 882 shut-down). This is accomplished using a removal interface on the RD 883 by performing a DELETE on the endpoint resource. 885 The removal request interface is specified as follows: 887 Interaction: EP -> RD 889 Method: DELETE 891 URI Template: /{+location} 893 URI Template Variables: 895 location := This is the Location path returned by the RD as a 896 result of a successful earlier registration. 898 The following responses codes are defined for this interface: 900 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 902 Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed 903 request. 905 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 906 exist (e.g. may have expired). 908 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 909 Service could not perform the operation. 911 HTTP support: YES 913 The following examples shows successful removal of the endpoint from 914 the RD with example location value /rd/4521. 916 Req: DELETE /rd/4521 918 Res: 2.02 Deleted 920 6.6. Read Endpoint Links 922 Some endpoints may wish to manage their links as a collection, and 923 may need to read the current set of links in order to determine link 924 maintenance operations. 926 One or more links MAY be selected by using query filtering as 927 specified in [RFC6690] Section 4.1 929 The read request interface is specified as follows: 931 Interaction: EP -> RD 933 Method: GET 935 URI Template: /{+location}{?href,rel,rt,if,ct} 937 URI Template Variables: 939 location := This is the Location path returned by the RD as a 940 result of a successful earlier registration. 942 href,rel,rt,if,ct := link relations and attributes specified in 943 the query in order to select particular links based on their 944 relations and attributes. "href" denotes the URI target of the 945 link. See [RFC6690] Sec. 4.1 947 The following responses codes are defined for this interface: 949 Success: 2.05 "Content" or 200 "OK" upon success with an 950 "application/link-format", "application/link-format+cbor", or 951 "application/link-format+json" payload. 953 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 954 request. 956 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 957 exist (e.g. may have expired). 959 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 960 Service could not perform the operation. 962 HTTP support: YES 963 The following examples show successful read of the endpoint links 964 from the RD, with example location value /rd/4521. 966 Req: GET /rd/4521 968 Res: 2.01 Content 969 Payload: 970 ;ct=41;rt="temperature-c";if="sensor", 971 ;ct=41;rt="light-lux";if="sensor" 973 6.7. Update Endpoint Links 975 [This section will be removed before or as a result of a working- 976 group last-call if the PATCH methods do not achieve the same level of 977 consensus as the present document.] 979 A PATCH update adds, removes or changes links for the endpoint by 980 including link update information in the payload of the update as a 981 merge-patch+json format [RFC7396] document. 983 One or more links are selected for update by using query filtering as 984 specified in [RFC6690] Section 4.1 986 The query filter selects the links to be modified or deleted, by 987 matching the query parameter values to the values of the link 988 attributes. 990 When the query parameters are not present in the request, the payload 991 specifies links to be added to the target document. When the query 992 parameters are present, the attribute names and values in the query 993 parameters select one or more links on which to apply the PATCH 994 operation. 996 If an attribute name specified in the PATCH document exists in any 997 the set of selected links, all occurrences of the attribute value in 998 the target document MUST be updated using the value from the PATCH 999 payload. If the attribute name is not present in any selected links, 1000 the attribute MUST be added to the links. 1002 The update request interface is specified as follows: 1004 Interaction: EP -> RD 1006 Method: PATCH 1008 URI Template: /{+location}{?href,rel,rt,if,ct} 1010 URI Template Variables: 1012 location := This is the Location path returned by the RD as a 1013 result of a successful earlier registration. 1015 href,rel,rt,if,ct := link relations and attributes specified in 1016 the query in order to select particular links based on their 1017 relations and attributes. "href" denotes the URI target of the 1018 link. See [RFC6690] Sec. 4.1 1020 Content-Format: application/merge-patch+json (mandatory) 1022 The following response codes are defined for this interface: 1024 Success: 2.04 "Changed" 0r 204 "No Content" in the update was 1025 successfully processed. 1027 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1028 request. 1030 Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource 1031 does not exist (e.g. may have expired). 1033 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1034 Service could not perform the operation. 1036 HTTP support: YES 1038 The following examples show an endpoint adding , 1039 modifying , and removing links in RD 1040 using the Update Endpoint Links function with the example location 1041 value /rd/4521. 1043 The following example shows an EP adding the link ;ct=41;rt="humid-s";if="sensor" to the collection of links at 1045 the location /rd/4521. 1047 Req: PATCH /rd/4521 1049 Payload: 1050 [{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}] 1052 Content-Format: 1053 application/merge-patch+json 1055 Res: 2.04 Changed 1057 The following example shows an EP modifying all links at the example 1058 location /rd/4521 which are identified by href="/sensors/temp", from 1059 the initial link-value of ;rt="temperature" to the new 1060 link-value ;rt="temperature-c";if="sensor" by changing 1061 the value of the link attribute "rt" and adding the link attribute 1062 if="sensor" using the PATCH operation with the supplied merge- 1063 patch+json document payload. 1065 Req: PATCH /rd/4521?href="/sensors/temp" 1067 Payload: 1068 {"rt": "temperature-c", "if": "sensor"}, 1070 Content-Format: 1071 application/merge-patch+json 1073 Res: 2.04 Changed 1075 This example shows an EP removing all links at the example location 1076 /rd/4521 which are identified by href="/sensors/light". 1078 Req: PATCH /rd/4521?href="/sensors/light" 1080 Payload: 1081 {null} 1083 Content-Format: 1084 application/merge-patch+json 1086 Res: 2.04 Changed 1088 7. Group Function Set 1090 This section defines a function set for the creation of groups of 1091 endpoints for the purpose of managing and looking up endpoints for 1092 group operations. The group function set is similar to the resource 1093 directory function set, in that a group may be created or removed. 1094 However unlike an endpoint entry, a group entry consists of a list of 1095 endpoints and does not have a lifetime associated with it. In order 1096 to make use of multicast requests with CoAP, a group MAY have a 1097 multicast address associated with it. 1099 7.1. Register a Group 1101 In order to create a group, a commissioning tool (CT) used to 1102 configure groups, makes a request to the RD indicating the name of 1103 the group to create (or update), optionally the domain the group 1104 belongs to, and optionally the multicast address of the group. The 1105 registration message includes the list of endpoints that belong to 1106 that group. 1108 All the endpoints in the group MUST be registered with the RD before 1109 registering a group. If an endpoint is not yet registered to the RD 1110 before registering the group, the registration message returns an 1111 error. The RD sends a blank target URI for every endpoint link when 1112 registering the group. 1114 Configuration of the endpoints themselves is out of scope of this 1115 specification. Such an interface for managing the group membership 1116 of an endpoint has been defined in [RFC7390]. 1118 The registration request interface is specified as follows: 1120 Interaction: CT -> RD 1122 Method: POST 1124 URI Template: /{+rd-group}{?gp,d,con} 1126 URI Template Variables: 1128 rd-group := RD Group Function Set path (mandatory). This is the 1129 path of the RD Group Function Set. The value "rd-group" is 1130 recommended for this variable. 1132 gp := Group Name (mandatory). The name of the group to be 1133 created or replaced, unique within that domain. The maximum 1134 length of this parameter is 63 bytes. 1136 d := Domain (optional). The domain to which this group belongs. 1137 The maximum length of this parameter is 63 bytes. Optional. 1138 When this parameter is elided, the RD MAY associate the 1139 endpoint with a configured default domain. The domain value is 1140 needed to export the endpoint to DNS-SD (see Section 10) 1142 con := Context (optional). This parameter is used to set the IP 1143 multicast address at which this server is available in the form 1144 scheme://multicast-address:port. Optional. In the absence of 1145 this parameter no multicast address is configured. This 1146 parameter is compulsory when the directory is filled by a 1147 commissioning tool. 1149 Content-Format: application/link-format 1151 Content-Format: application/link-format+json 1153 Content-Format: application/link-format+cbor 1155 The following response codes are defined for this interface: 1157 Success: 2.01 "Created" or 201 "Created". The Location header MUST 1158 be included with the new group entry. This Location MUST be a 1159 stable identifier generated by the RD as it is used for delete 1160 operations on this registration. 1162 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1163 request. 1165 Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not 1166 registered in the RD (e.g. may have expired). 1168 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1169 Service could not perform the operation. 1171 HTTP support: YES 1173 The following example shows an EP registering a group with the name 1174 "lights" which has two endpoints to an RD using this interface. The 1175 base location value /rd-group is an example of an RD base location. 1177 Req: POST coap://rd.example.com/rd-group?gp=lights 1178 Content-Format: 40 1179 Payload: 1180 <>;ep="node1", 1181 <>;ep="node2" 1183 Res: 2.01 Created 1184 Location: /rd-group/12 1186 Req: POST /rd-group?gp=lights HTTP/1.1 1187 Host: example.com 1188 Content-Type: application/link-format 1189 Payload: 1190 <>;ep="node1", 1191 <>;ep="node2" 1193 Res: 201 Created 1194 Location: /rd-group/12 1196 7.2. Group Removal 1198 A group can be removed simply by sending a removal message to the 1199 location returned when registering the group. Removing a group MUST 1200 NOT remove the endpoints of the group from the RD. 1202 The removal request interface is specified as follows: 1204 Interaction: CT -> RD 1205 Method: DELETE 1207 URI Template: /{+location} 1209 URI Template Variables: 1211 location := This is the Location path returned by the RD as a 1212 result of a successful group registration. 1214 The following responses codes are defined for this interface: 1216 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1218 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1219 request. 1221 Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. 1223 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1224 Service could not perform the operation. 1226 HTTP support: YES 1228 The following examples shows successful removal of the group from the 1229 RD with the example location value /rd-group/12. 1231 Req: DELETE /rd-group/12 1233 Res: 2.02 Deleted 1235 8. RD Lookup Function Set 1237 In order for an RD to be used for discovering resources registered 1238 with it, a lookup interface can be provided using this function set. 1239 This lookup interface is defined as a default, and it is assumed that 1240 RDs may also support lookups to return resource descriptions in 1241 alternative formats (e.g. Atom or HTML Link) or using more advanced 1242 interfaces (e.g. supporting context or semantic based lookup). 1244 This function set allows lookups for domains, groups, endpoints and 1245 resources using attributes defined in the RD Function Set and for use 1246 with the CoRE Link Format. The result of a lookup request is the 1247 list of links (if any) corresponding to the type of lookup. Thus, a 1248 domain lookup MUST return a list of domains, a group lookup MUST 1249 return a list of groups, an endpoint lookup MUST return a list of 1250 endpoints and a resource lookup MUST return a list of links to 1251 resources. 1253 Each endpoint and resource lookup result returns respectively the 1254 scheme (IP address and port) followed by the path part of the URI of 1255 every endpoint and resource inside angle brackets ("<>") and followed 1256 by the other parameters. 1258 The target of these links SHOULD be the actual location of the 1259 domain, endpoint or resource, but MAY be an intermediate proxy e.g. 1260 in the case of an HTTP lookup interface for CoAP endpoints. 1262 The domain lookup returns every lookup domain with a base RD resource 1263 value (e.g. "/rd") encapsulated within angle brackets. 1265 In case that a group does not implement any multicast address, the 1266 group lookup returns every group lookup with a group base resource 1267 value encapsulated within angle brackets (e.g. "/rd/look-up"). 1268 Otherwise, the group lookup returns the multicast address of the 1269 group inside angle brackets. 1271 Using the Accept Option, the requester can control whether this list 1272 is returned in CoRE Link Format ("application/link-format", default) 1273 or its alternate content-formats ("application/link-format+json" or 1274 "application/link-format+cbor"). 1276 The page and count parameters are used to obtain lookup results in 1277 specified increments using pagination, where count specifies how many 1278 links to return and page specifies which subset of links organized in 1279 sequential pages, each containing 'count' links, starting with link 1280 zero and page zero. Thus, specifying count of 10 and page of 0 will 1281 return the first 10 links in the result set (links 0-9). Count = 10 1282 and page = 1 will return the next 'page' containing links 10-19, and 1283 so on. 1285 Multiple query parameters MAY be included in a lookup, all included 1286 parameters MUST match for a resource to be returned. The 1287 character'*' MAY be included at the end of a parameter value as a 1288 wildcard operator. 1290 The rd-lookup interface MAY use any set of query parameters to match 1291 the registered attributes and relations. In addition, this interface 1292 MAY be used with queries that specify domains, endpoints, and groups. 1293 For example, a domain lookup filtering on groups would return a list 1294 of domains that contain the specified groups. An endpoint lookup 1295 filtering on groups would return a list of endpoints that are in the 1296 specified groups. 1298 The lookup interface is specified as follows: 1300 Interaction: Client -> RD 1301 Method: GET 1303 URI Template: /{+rd-lookup-base}/{lookup- 1304 type}{?d,ep,gp,et,rt,page,count,resource-param} 1306 URI Template Variables: 1308 rd-lookup-base := RD Lookup Function Set path (mandatory). This 1309 is the path of the RD Lookup Function Set. The recommended 1310 value for this variable is: "rd-lookup". 1312 lookup-type := ("d", "ep", "res", "gp") (mandatory) This variable 1313 is used to select the kind of lookup to perform (domain, 1314 endpoint, resource, or group). 1316 ep := Endpoint name (optional). Used for endpoint, group and 1317 resource lookups. 1319 d := Domain (optional). Used for domain, group, endpoint and 1320 resource lookups. 1322 res := resource (optional). Used for domain, group, endpoint and 1323 resource lookups. 1325 gp := Group name (optional). Used for endpoint, group and 1326 resource lookups. 1328 page := Page (optional). Parameter can not be used without the 1329 count parameter. Results are returned from result set in pages 1330 that contain 'count' links starting from index (page * count). 1331 Page numbering starts with zero. 1333 count := Count (optional). Number of results is limited to this 1334 parameter value. If the page parameter is also present, the 1335 response MUST only include 'count' links starting with the 1336 (page * count) link in the result set from the query. If the 1337 count parameter is not present, then the response MUST return 1338 all matching links in the result set. Link numbering starts 1339 with zero. 1341 rt := Resource type (optional). Used for group, endpoint and 1342 resource lookups. 1344 et := Endpoint type (optional). Used for group, endpoint and 1345 resource lookups. 1347 resource-param := Link attribute parameters (optional). Any link 1348 attribute as defined in Section 4.1 of [RFC6690], used for 1349 resource lookups. 1351 Content-Format: application/link-format (optional) 1353 Content-Format: application/link-format+json (optional) 1355 Content-Format: application/link-format+cbor (optional) 1357 The following responses codes are defined for this interface: 1359 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1360 format", "application/link-format+cbor", or "application/link- 1361 format+json" payload containing matching entries for the lookup. 1363 Failure: 4.04 "Not Found" or 404 "Not Found" in case no matching 1364 entry is found for a unicast request. 1366 Failure: No error response to a multicast request. 1368 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1369 request. 1371 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1372 Service could not perform the operation. 1374 HTTP support: YES 1376 The examples in this section assume a CoAP host with IP address 1377 FDFD::123 and a default CoAP port 61616. HTTP hosts are possible and 1378 do not change the nature of the examples.\ 1380 The following example shows a client performing a resource lookup 1381 with the example look-up location /rd-lookup/: 1383 Req: GET /rd-lookup/res?rt=temperature 1385 Res: 2.05 Content 1386 ;rt="temperature" 1388 The following example shows a client performing an endpoint type 1389 lookup: 1391 Req: GET /rd-lookup/ep?et=power-node 1393 Res: 2.05 Content 1394 ;ep="node5", 1395 ;ep="node7" 1397 The following example shows a client performing a domain lookup: 1399 Req: GET /rd-lookup/d 1401 Res: 2.05 Content 1402 <>;d="domain1", 1403 <>;d="domain2" 1405 The following example shows a client performing a group lookup for 1406 all groups: 1408 Req: GET /rd-lookup/gp 1410 Res: 2.05 Content 1411 <>;gp="lights1";d="example.com" 1412 <>;gp="lights2";d="ecample.com" 1414 The following example shows a client performing a lookup for all 1415 endpoints in a particular group: 1417 Req: GET /rd-lookup/ep?gp=lights1 1419 Res: 2.05 Content 1420 ;ep="node1", 1421 ;ep="node2" 1423 The following example shows a client performing a lookup for all 1424 groups an endpoint belongs to: 1426 Req: GET /rd-lookup/gp?ep=node1 1428 Res: 2.05 Content 1429 <>;gp="lights1" 1431 The following example shows a client performing a paginated lookup 1432 Req: GET /rd-lookup/res?page=0&count=5 1434 Res: 2.05 Content 1435 ;rt=sensor;ct=60 1436 ;rt=sensor;ct=60 1437 ;rt=sensor;ct=60 1438 ;rt=sensor;ct=60 1439 ;rt=sensor;ct=60 1441 Req: GET /rd-lookup/res?page=1&count=5 1443 Res: 2.05 Content 1444 ;rt=sensor;ct=60 1445 ;rt=sensor;ct=60 1446 ;rt=sensor;ct=60 1447 ;rt=sensor;ct=60 1448 ;rt=sensor;ct=60 1450 9. New Link-Format Attributes 1452 When using the CoRE Link Format to describe resources being 1453 discovered by or posted to a resource directory service, additional 1454 information about those resources is useful. This specification 1455 defines the following new attributes for use in the CoRE Link Format 1456 [RFC6690]: 1458 link-extension = ( "ins" "=" (ptoken | quoted-string) ) 1459 ; The token or string is max 63 bytes 1460 link-extension = ( "exp" ) 1462 9.1. Resource Instance attribute 'ins' 1464 The Resource Instance "ins" attribute is an identifier for this 1465 resource, which makes it possible to distinguish it from other 1466 similar resources. This attribute is similar in use to the 1467 portion of a DNS-SD record (see Section 10.1, and SHOULD 1468 be unique across resources with the same Resource Type attribute in 1469 the domain it is used. A Resource Instance might be a descriptive 1470 string like "Ceiling Light, Room 3", a short ID like "AF39" or a 1471 unique UUID or iNumber. This attribute is used by a Resource 1472 Directory to distinguish between multiple instances of the same 1473 resource type within the directory. 1475 This attribute MUST be no more than 63 bytes in length. The resource 1476 identifier attribute MUST NOT appear more than once in a link 1477 description. This attribute MAY be used as a query parameter in the 1478 RD Lookup Function Set defined in Section 7. 1480 9.2. Export attribute 'exp' 1482 The Export "exp" attribute is used as a flag to indicate that a link 1483 description MAY be exported by a resource directory to external 1484 directories. 1486 The CoRE Link Format is used for many purposes between CoAP 1487 endpoints. Some are useful mainly locally, for example checking the 1488 observability of a resource before accessing it, determining the size 1489 of a resource, or traversing dynamic resource structures. However, 1490 other links are very useful to be exported to other directories, for 1491 example the entry point resource to a functional service. This 1492 attribute MAY be used as a query parameter in the RD Lookup Function 1493 Set defined in Section 7. 1495 10. DNS-SD Mapping 1497 CoRE Resource Discovery is intended to support fine-grained discovery 1498 of hosted resources, their attributes, and possibly other resource 1499 relations [RFC6690]. In contrast, service discovery generally refers 1500 to a coarse-grained resolution of an endpoint's IP address, port 1501 number, and protocol. 1503 Resource and service discovery are complementary in the case of large 1504 networks, where the latter can facilitate scaling. This document 1505 defines a mapping between CoRE Link Format attributes and DNS-Based 1506 Service Discovery [RFC6763] fields that permits discovery of CoAP 1507 services by either method. 1509 10.1. DNS-based Service discovery 1511 DNS-Based Service Discovery (DNS-SD) defines a conventional method of 1512 configuring DNS PTR, SRV, and TXT resource records to facilitate 1513 discovery of services (such as CoAP servers in a subdomain) using the 1514 existing DNS infrastructure. This section gives a brief overview of 1515 DNS-SD; see [RFC6763] for a detailed specification. 1517 DNS-SD service names are limited to 255 octets and are of the form: 1519 Service Name = ... 1521 The service name is the label of SRV/TXT resource records. The SRV 1522 RR specifies the host and the port of the endpoint. The TXT RR 1523 provides additional information in the form of key/value pairs. 1525 The part of the service name is identical to the global (DNS 1526 subdomain) part of the authority in URIs that identify servers or 1527 groups of servers. 1529 The part is composed of at least two labels. The first 1530 label of the pair is the application protocol name [RFC6335] preceded 1531 by an underscore character. The second label indicates the transport 1532 and is always "_udp" for UDP-based CoAP services. In cases where 1533 narrowing the scope of the search may be useful, these labels may be 1534 optionally preceded by a subtype name followed by the "_sub" label. 1535 An example of this more specific is 1536 "light._sub._dali._udp". 1538 A default part of the service name may be set at the 1539 factory or during the commissioning process. It SHOULD uniquely 1540 identify an instance of within a . Taken 1541 together, these three elements comprise a unique name for an SRV/ TXT 1542 record pair within the DNS subdomain. 1544 The granularity of a service name MAY be that of a host or group, or 1545 it could represent a particular resource within a CoAP server. The 1546 SRV record contains the host name (AAAA record name) and port of the 1547 service while protocol is part of the service name. In the case 1548 where a service name identifies a particular resource, the path part 1549 of the URI must be carried in a corresponding TXT record. 1551 A DNS TXT record is in practice limited to a few hundred octets in 1552 length, which is indicated in the resource record header in the DNS 1553 response message. The data consists of one or more strings 1554 comprising a key=value pair. By convention, the first pair is 1555 txtver= (to support different versions of a service 1556 description). 1558 10.2. mapping ins to 1560 The Resource Instance "ins" attribute maps to the part of 1561 a DNS-SD service name. It is stored directly in the DNS as a single 1562 DNS label of canonical precomposed UTF-8 [RFC3629] "Net-Unicode" 1563 (Unicode Normalization Form C) [RFC5198] text. However, to the 1564 extent that the "ins" attribute may be chosen to match the DNS host 1565 name of a service, it SHOULD use the syntax defined in Section 3.5 of 1566 [RFC1034] and Section 2.1 of [RFC1123]. 1568 The part of the name of a service being offered on the 1569 network SHOULD be configurable by the user setting up the service, so 1570 that he or she may give it an informative name. However, the device 1571 or service SHOULD NOT require the user to configure a name before it 1572 can be used. A sensible choice of default name can allow the device 1573 or service to be accessed in many cases without any manual 1574 configuration at all. The default name should be short and 1575 descriptive, and MAY include a collision-resistant substring such as 1576 the lower bits of the device's MAC address, serial number, 1577 fingerprint, or other identifier in an attempt to make the name 1578 relatively unique. 1580 DNS labels are currently limited to 63 octets in length and the 1581 entire service name may not exceed 255 octets. 1583 10.3. Mapping rt to 1585 The resource type "rt" attribute is mapped into the 1586 part of a DNS-SD service name and SHOULD conform to the reg-rel-type 1587 production of the Link Format defined in Section 2 of [RFC6690]. The 1588 "rt" attribute MUST be composed of at least a single Net-Unicode text 1589 string, without underscore '_' or period '.' and limited to 15 octets 1590 in length, which represents the application protocol name. This 1591 string is mapped to the DNS-SD by prepending an 1592 underscore and appending a period followed by the "_udp" label. For 1593 example, rt="dali" is mapped into "_dali._udp". 1595 The application protocol name may be optionally followed by a period 1596 and a service subtype name consisting of a Net-Unicode text string, 1597 without underscore or period and limited to 63 octets. This string 1598 is mapped to the DNS-SD by appending a period followed 1599 by the "_sub" label and then appending a period followed by the 1600 service type label pair derived as in the previous paragraph. For 1601 example, rt="dali.light" is mapped into "light._sub._dali._udp". 1603 The resulting string is used to form labels for DNS-SD records which 1604 are stored directly in the DNS. 1606 10.4. Domain mapping 1608 DNS domains may be derived from the "d" attribute. The domain 1609 attribute may be suffixed with the zone name of the authoritative DNS 1610 server to generate the domain name. The "ep" attribute is prefixed 1611 to the domain name to generate the FQDN to be stored into DNS with an 1612 AAAA RR. 1614 10.5. TXT Record key=value strings 1616 A number of [RFC6763] key/value pairs are derived from link-format 1617 information, to be exported in the DNS-SD as key=value strings in a 1618 TXT record ([RFC6763], Section 6.3). 1620 The resource is exported as key/value pair "path=". 1622 The Interface Description "if" attribute is exported as key/value 1623 pair "if=". 1625 The DNS TXT record can be further populated by importing any other 1626 resource description attributes as they share the same key=value 1627 format specified in Section 6 of [RFC6763]. 1629 10.6. Importing resource links into DNS-SD 1631 Assuming the ability to query a Resource Directory or multicast a GET 1632 (?exp) over the local link, CoAP resource discovery may be used to 1633 populate the DNS-SD database in an automated fashion. CoAP resource 1634 descriptions (links) can be exported to DNS-SD for exposure to 1635 service discovery by using the Resource Instance attribute as the 1636 basis for a unique service name, composed with the Resource Type as 1637 the , and registered in the correct . The agent 1638 responsible for exporting records to the DNS zone file SHOULD be 1639 authenticated to the DNS server. The following example, using the 1640 example lookup location /rd-lookup, shows an agent discovering a 1641 resource to be exported: 1643 Req: GET /rd-lookup/res?exp 1645 Res: 2.05 Content 1646 ; 1647 exp;rt="dali.light";ins="Spot"; 1648 d="office";ep="node1" 1650 The agent subsequently registers the following DNS-SD RRs, assuming a 1651 zone name "example.com" prefixed with "office": 1653 node1.office.example.com. IN AAAA FDFD::1234 1654 _dali._udp.office.example.com IN PTR 1655 Spot._dali._udp.office.example.com 1656 light._sub._dali._udp.example.com IN PTR 1657 Spot._dali._udp.office.example.com 1658 Spot._dali._udp.office.example.com IN SRV 0 0 5683 1659 node1.office.example.com. 1660 Spot._dali._udp.office.example.com IN TXT 1661 txtver=1;path=/light/1 1663 In the above figure the Service Name is chosen as 1664 Spot._dali._udp.office.example.com without the light._sub service 1665 prefix. An alternative Service Name would be: 1666 Spot.light._sub._dali._udp.office.example.com. 1668 11. Security Considerations 1670 The security considerations as described in Section 7 of [RFC5988] 1671 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1672 may be protected e.g. using DTLS when hosted on a CoAP server as 1673 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1674 all resource directory interfaces defined in this document. 1676 11.1. Endpoint Identification and Authentication 1678 An Endpoint is determined to be unique by an RD by the Endpoint 1679 identifier parameter included during Registration, and any associated 1680 TLS or DTLS security bindings. An Endpoint MUST NOT be identified by 1681 its protocol, port or IP address as these may change over the 1682 lifetime of an Endpoint. 1684 Every operation performed by an Endpoint or Client on a resource 1685 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1686 Public Key or Certificate based security. Endpoints using a 1687 Certificate MUST include the Endpoint identifier as the Subject of 1688 the Certificate, and this identifier MUST be checked by a resource 1689 directory to match the Endpoint identifier included in the 1690 Registration message. 1692 11.2. Access Control 1694 Access control SHOULD be performed separately for the RD Function Set 1695 and the RD Lookup Function Set, as different endpoints may be 1696 authorized to register with an RD from those authorized to lookup 1697 endpoints from the RD. Such access control SHOULD be performed in as 1698 fine-grained a level as possible. For example access control for 1699 lookups could be performed either at the domain, endpoint or resource 1700 level. 1702 11.3. Denial of Service Attacks 1704 Services that run over UDP unprotected are vulnerable to unknowingly 1705 become part of a DDoS attack as UDP does not require return 1706 routability check. Therefore, an attacker can easily spoof the 1707 source IP of the target entity and send requests to such a service 1708 which would then respond to the target entity. This can be used for 1709 large-scale DDoS attacks on the target. Especially, if the service 1710 returns a response that is order of magnitudes larger than the 1711 request, the situation becomes even worse as now the attack can be 1712 amplified. DNS servers have been widely used for DDoS amplification 1713 attacks. There is also a danger that NTP Servers could become 1714 implicated in denial-of-service (DoS) attacks since they run on 1715 unprotected UDP, there is no return routability check, and they can 1716 have a large amplification factor. The responses from the NTP server 1717 were found to be 19 times larger than the request. A Resource 1718 Directory (RD) which responds to wild-card lookups is potentially 1719 vulnerable if run with CoAP over UDP. Since there is no return 1720 routability check and the responses can be significantly larger than 1721 requests, RDs can unknowingly become part of a DDoS amplification 1722 attack. Therefore, it is RECOMMENDED that implementations ensure 1723 return routability. This can be done, for example by responding to 1724 wild card lookups only over DTLS or TLS or TCP. 1726 12. IANA Considerations 1728 12.1. Resource Types 1730 "core.rd", "core.rd-group" and "core.rd-lookup" resource types need 1731 to be registered with the resource type registry defined by 1732 [RFC6690]. 1734 12.2. Link Extension 1736 The "exp" and "ins" attributes need to be registered when a future 1737 Web Linking link-extension registry is created (e.g. in RFC5988bis). 1739 12.3. IPv6 ND Resource Directory Address Option 1741 This document registers one new ND option type under the subregistry 1742 "IPv6 Neighbor Discovery Option Formats": 1744 o Resource Directory address Option (38) 1746 12.4. RD Parameter Registry 1748 This specification defines a new sub-registry for registration and 1749 lookup parameters called "RD Parameters" under "CoRE Parameters". 1750 Although this specification defines a basic set of parameters, it is 1751 expected that other standards that make use of this interface will 1752 define new ones. 1754 Each entry in the registry must include the human readable name of 1755 the parameter, the query parameter, validity requirements if any and 1756 a description. The query parameter MUST be a valid URI query key 1757 [RFC3986]. 1759 Initial entries in this sub-registry are as follows: 1761 +-----------+-------+---------------+-------------------------------+ 1762 | Name | Query | Validity | Description | 1763 +-----------+-------+---------------+-------------------------------+ 1764 | Endpoint | ep | | Name of the endpoint, max 63 | 1765 | Name | | | bytes | 1766 | Lifetime | lt | 60-4294967295 | Lifetime of the registration | 1767 | | | | in seconds | 1768 | Domain | d | | Domain to which this endpoint | 1769 | | | | belongs | 1770 | Endpoint | et | | Semantic name of the endpoint | 1771 | Type | | | | 1772 | Context | con | URI | The scheme, address and port | 1773 | | | | at which this server is | 1774 | | | | available | 1775 | Resource | res | | Name of the resource | 1776 | Name | | | | 1777 | Group | gp | | Name of a group in the RD | 1778 | Name | | | | 1779 | Page | page | Integer | Used for pagination | 1780 | Count | count | Integer | Used for pagination | 1781 | Resource | ins | | Instance Identifier | 1782 | Instance | | | | 1783 | Export | exp | | A link MAY be exported to | 1784 | | | | another Resource Directory | 1785 +-----------+-------+---------------+-------------------------------+ 1787 Table 1: RD Parameters 1789 The IANA policy for future additions to the sub-registry is "Expert 1790 Review" as described in [RFC5226]. 1792 13. Examples 1794 13.1. Lighting Installation 1796 This example shows a simplified lighting installation which makes use 1797 of the Resource Directory (RD) with a CoAP interface to facilitate 1798 the installation and start up of the application code in the lights 1799 and sensors. In particular, the example leads to the definition of a 1800 group and the enabling of the corresponding multicast address. No 1801 conclusions must be drawn on the realization of actual installation 1802 or naming procedures, because the example only "emphasizes" some of 1803 the issues that may influence the use of the RD and does not pretend 1804 to be normative. The example uses the recommended values for the 1805 base resources: "/rd", "/rd-lookup", and "/rd-group". 1807 13.1.1. Installation Characteristics 1809 The example assumes that the installation is managed. That means 1810 that a Commissioning Tool (CT) is used to authorize the addition of 1811 nodes, name them, and name their services. The CT can be connected 1812 to the installation in many ways: the CT can be part of the 1813 installation network, connected by WiFi to the installation network, 1814 or connected via GPRS link, or other method. 1816 It is assumed that there are two naming authorities for the 1817 installation: (1) the network manager that is responsible for the 1818 correct operation of the network and the connected interfaces, and 1819 (2) the lighting manager that is responsible for the correct 1820 functioning of networked lights and sensors. The result is the 1821 existence of two naming schemes coming from the two managing 1822 entities. 1824 The example installation consists of one presence sensor, and two 1825 luminaries, luminary1 and luminary2, each with their own wireless 1826 interface. Each luminary contains three lamps: left, right and 1827 middle. Each luminary is accessible through one endpoint. For each 1828 lamp a resource exists to modify the settings of a lamp in a 1829 luminary. The purpose of the installation is that the presence 1830 sensor notifies the presence of persons to a group of lamps. The 1831 group of lamps consists of: middle and left lamps of luminary1 and 1832 right lamp of luminary2. 1834 Before commissioning by the lighting manager, the network is 1835 installed and access to the interfaces is proven to work by the 1836 network manager. 1838 At the moment of installation, the network under installation is not 1839 necessarily connected to the DNS infra structure. Therefore, SLAAC 1840 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 1841 Table 2 below: 1843 +--------------------+--------------+ 1844 | Name | IPv6 address | 1845 +--------------------+--------------+ 1846 | luminary1 | FDFD::ABCD:1 | 1847 | luminary2 | FDFD::ABCD:2 | 1848 | Presence sensor | FDFD::ABCD:3 | 1849 | Resource directory | FDFD::ABCD:0 | 1850 +--------------------+--------------+ 1852 Table 2: interface SLAAC addresses 1854 In Section 13.1.2 the use of resource directory during installation 1855 is presented. In Section 13.1.3 the connection to DNS is discussed. 1857 13.1.2. RD entries 1859 It is assumed that access to the DNS infrastructure is not always 1860 possible during installation. Therefore, the SLAAC addresses are 1861 used in this section. 1863 For discovery, the resource types (rt) of the devices are important. 1864 The lamps in the luminaries have rt: light, and the presence sensor 1865 has rt: p-sensor. The endpoints have names which are relevant to the 1866 light installation manager. In this case luminary1, luminary2, and 1867 the presence sensor are located in room 2-4-015, where luminary1 is 1868 located at the window and luminary2 and the presence sensor are 1869 located at the door. The endpoint names reflect this physical 1870 location. The middle, left and right lamps are accessed via path 1871 /light/middle, /light/left, and /light/right respectively. The 1872 identifiers relevant to the Resource Directory are shown in Table 3 1873 below: 1875 +----------------+------------------+---------------+---------------+ 1876 | Name | endpoint | resource path | resource type | 1877 +----------------+------------------+---------------+---------------+ 1878 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 1879 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 1880 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 1881 | luminary2 | lm_R2-4-015_door | /light/left | light | 1882 | luminary2 | lm_R2-4-015_door | /light/middle | light | 1883 | luminary2 | lm_R2-4-015_door | /light/right | light | 1884 | Presence | ps_R2-4-015_door | /ps | p-sensor | 1885 | sensor | | | | 1886 +----------------+------------------+---------------+---------------+ 1888 Table 3: Resource Directory identifiers 1890 The CT inserts the endpoints of the luminaries and the sensor in the 1891 RD using the Context parameter (con) to specify the interface 1892 address: 1894 Req: POST coap://[FDFD::ABCD:0]/rd 1895 ?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1] 1896 Payload: 1897 ;rt="light"; d="R2-4-015", 1898 ;rt="light"; d="R2-4-015", 1899 ;rt="light";d="R2-4-015" 1901 Res: 2.01 Created 1902 Location: /rd/4521 1904 Req: POST coap://[FDFD::ABCD:0]/rd 1905 ?ep=lm_R2-4-015_door&con=coap://[FDFD::ABCD:2] 1906 Payload: 1907 ;rt="light"; d="R2-4-015", 1908 ;rt="light"; d="R2-4-015", 1909 ;rt="light"; d="R2-4-015" 1911 Res: 2.01 Created 1912 Location: /rd/4522 1914 Req: POST coap://[FDFD::ABCD:0]/rd 1915 ?ep=ps_R2-4-015_door&con=coap://[FDFD::ABCD:3] 1916 Payload: 1917 ;rt="p-sensor"; d="R2-4-015" 1919 Res: 2.01 Created 1920 Location: /rd/4523 1922 The domain name d="R2-4-015" has been added for an efficient lookup 1923 because filtering on "ep" name is more awkward. The same domain name 1924 is communicated to the two luminaries and the presence sensor by the 1925 CT. 1927 The group is specified in the RD. The Context parameter is set to 1928 the site-local multicast address allocated to the group. In the POST 1929 in the example below, these two endpoints and the endpoint of the 1930 presence sensor are registered as members of the group. 1932 Req: POST coap://[FDFD::ABCD:0]/rd-group 1933 ?gp=grp_R2-4-015;con="coap//[FF05::1]";exp;ins="grp1234" 1934 Payload: 1935 <>ep=lm_R2-4-015_wndw, 1936 <>ep=lm_R2-4-015_door, 1937 <>ep=ps_R2-4-015_door 1939 Res: 2.01 Created 1940 Location: /rd-group/501 1941 After the filling of the RD by the CT, the application in the 1942 luminaries can learn to which groups they belong, and enable their 1943 interface for the multicast address. 1945 The luminary, knowing its domain, queries the RD for the endpoint 1946 with rt=light and d=R2-4-015. The RD returns all endpoints in the 1947 domain. 1949 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep 1950 ?d=R2-4-015;rt=light 1952 Res: 2.05 Content 1953 ; 1954 ep="lm_R2-4-015_wndw", 1955 ; 1956 ep="lm_R2-4-015_door" 1958 Knowing its own IPv6 address, the luminary discovers its endpoint 1959 name. With the endpoint name the luminary queries the RD for all 1960 groups to which the endpoint belongs. 1962 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/gp 1963 ?ep=lm_R2-4-015_wndw 1965 Res: 2.05 Content 1966 ;gp="grp_R2-4-015" 1968 From the context parameter value, the luminary learns the multicast 1969 address of the multicast group. 1971 Alternatively, the CT can communicate the multicast address directly 1972 to the luminaries by using the "coap-group" resource specified in 1973 [RFC7390]. 1975 Req: POST //[FDFD::ABCD:1]/coap-group 1976 Content-Format: application/coap-group+json 1977 { "a": "[FF05::1]", 1978 "n": "grp_R2-4-015"} 1980 Res: 2.01 Created 1981 Location-Path: /coap-group/1 1983 Dependent on the situation, only the address, "a", or the name, "n", 1984 is specified in the coap-group resource. 1986 13.1.3. DNS entries 1988 It may be profitable to discover the light groups for applications, 1989 which are unaware ot the existence of the RD. An agent needs to 1990 query the RD to return all groups which are exported to be inserted 1991 into DNS. 1993 Req: GET /rd-lookup/gp?exp 1995 Res: 2.05 Content 1996 ;exp;gp="grp_R2-4-015;ins="grp1234"; 1997 ep="lm_R2-4-015_wndw"; 1998 ep="lm_R2-4-015_door 2000 The group with FQDN grp_R2-4-015.bc.example.com can be entered into 2001 the DNS by the agent. The accompanying instance name is grp1234. 2002 The is chosen to be _group._udp. The agent enters the 2003 following RRs into the DNS. 2005 grp_R2-4-015.bc.example.com. IN AAAA FF05::1 2006 _group._udp.bc.example.com IN PTR 2007 grp1234._group._udp.bc.example.com 2008 grp1234._group._udp.bc.example.com IN SRV 0 0 5683 2009 grp_R2-4-015_door.bc.example.com. 2010 grp1234._group._udp.bc.example.com IN TXT 2011 txtver=1;path=/light/grp1 2013 From then on applications, not familiar with the existence of the RD, 2014 can use DNS to access the lighting group. 2016 13.2. OMA Lightweight M2M (LWM2M) Example 2018 This example shows how the OMA LWM2M specification makes use of 2019 Resource Directory (RD). 2021 OMA LWM2M is a profile for device services based on CoAP(OMA Name 2022 Authority). LWM2M defines a simple object model and a number of 2023 abstract interfaces and operations for device management and device 2024 service enablement. 2026 An LWM2M server is an instance of an LWM2M middleware service layer, 2027 containing a Resource Directory along with other LWM2M interfaces 2028 defined by the LWM2M specification. 2030 CoRE Resource Directory (RD) is used to provide the LWM2M 2031 Registration interface. 2033 LWM2M does not provide for registration domains and does not 2034 currently use the rd-group or rd-lookup interfaces. 2036 The LWM2M specification describes a set of interfaces and a resource 2037 model used between a LWM2M device and an LWM2M server. Other 2038 interfaces, proxies, applications, and function sets are currently 2039 out of scope for LWM2M. 2041 The location of the LWM2M Server and RD Function Set is provided by 2042 the LWM2M Bootstrap process, so no dynamic discovery of the RD 2043 function set is used. LWM2M Servers and endpoints are not required 2044 to implement the ./well-known/core resource. 2046 13.2.1. The LWM2M Object Model 2048 The OMA LWM2M object model is based on a simple 2 level class 2049 hierarchy consisting of Objects and Resources. 2051 An LWM2M Resource is a REST endpoint, allowed to be a single value or 2052 an array of values of the same data type. 2054 An LWM2M Object is a resource template and container type that 2055 encapsulates a set of related resources. An LWM2M Object represents 2056 a specific type of information source; for example, there is a LWM2M 2057 Device Management object that represents a network connection, 2058 containing resources that represent individual properties like radio 2059 signal strength. 2061 Since there may potentially be more than one of a given type object, 2062 for example more than one network connection, LWM2M defines instances 2063 of objects that contain the resources that represent a specific 2064 physical thing. 2066 The URI template for LWM2M consists of a base URI followed by Object, 2067 Instance, and Resource IDs: 2069 {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- 2070 instance} 2072 The five variables given here are strings. base-uri can also have 2073 the special value "undefined" (sometimes called "null" in RFC 6570). 2074 Each of the variables object-instance, resource-id, and resource- 2075 instance can be the special value "undefined" only if the values 2076 behind it in this sequence also are "undefined". As a special case, 2077 object-instance can be "empty" (which is different from "undefined") 2078 if resource-id is not "undefined". [_TEMPLATE_TODO] 2079 base-uri := Base URI for LWM2M resources or "undefined" for default 2080 (empty) base URI 2082 object-id := OMNA (OMA Name Authority) registered object ID (0-65535) 2084 object-instance := Object instance identifier (0-65535) or 2085 "undefined"/"empty" (see above)) to refer to all instances of an 2086 object ID 2088 resource-id := OMNA (OMA Name Authority) registered resource ID 2089 (0-65535) or "undefined" to refer to all resources within an instance 2091 resource-instance := Resource instance identifier or "undefined" to 2092 refer to single instance of a resource 2094 LWM2M IDs are 16 bit unsigned integers represented in decimal (no 2095 leading zeroes except for the value 0) by URI format strings. For 2096 example, a LWM2M URI might be: 2098 /1/0/1 2100 The base uri is empty, the Object ID is 1, the instance ID is 0, the 2101 resource ID is 1, and the resource instance is "undefined". This 2102 example URI points to internal resource 1, which represents the 2103 registration lifetime configured, in instance 0 of a type 1 object 2104 (LWM2M Server Object). 2106 13.2.2. LWM2M Register Endpoint 2108 LWM2M defines a registration interface based on the Resource 2109 Directory Function Set, described in Section 6. The URI of the LWM2M 2110 Resource Directory function set is specified to be "/rd" as 2111 recommended in Section 6.3. 2113 LWM2M endpoints register object IDs, for example , to indicate 2114 that a particular object type is supported, and register object 2115 instances, for example , to indicate that a particular instance 2116 of that object type exists. 2118 Resources within the LWM2M object instance are not registered with 2119 the RD, but may be discovered by reading the resource links from the 2120 object instance using GET with a CoAP Content-Format of application/ 2121 link-format. Resources may also be read as a structured object by 2122 performing a GET to the object instance with a Content-Format of 2123 senml+json. 2125 When an LWM2M object or instance is registered, this indicates to the 2126 LWM2M server that the object and its resources are available for 2127 management and service enablement (REST API) operations. 2129 LWM2M endpoints may use the following RD registration parameters as 2130 defined in Table 1 : 2132 ep - Endpoint Name 2133 lt - registration lifetime 2135 Endpoint Name is mandatory, all other registration parameters are 2136 optional. 2138 Additional optional LWM2M registration parameters are defined: 2140 +------------+-------+-------------------------------+--------------+ 2141 | Name | Query | Validity | Description | 2142 +------------+-------+-------------------------------+--------------+ 2143 | Protocol | b | {"U",UQ","S","SQ","US","UQS"} | Available | 2144 | Binding | | | Protocols | 2145 | | | | | 2146 | LWM2M | ver | 1.0 | Spec Version | 2147 | Version | | | | 2148 | | | | | 2149 | SMS Number | sms | | MSISDN | 2150 +------------+-------+-------------------------------+--------------+ 2152 Table 4: LWM2M Additional Registration Parameters 2154 The following RD registration parameters are not currently specified 2155 for use in LWM2M: 2157 et - Endpoint Type 2158 con - Context 2160 The endpoint registration must include a payload containing links to 2161 all supported objects and existing object instances, optionally 2162 including the appropriate link-format relations. 2164 Here is an example LWM2M registration payload: 2166 ,,, 2168 This link format payload indicates that object ID 1 (LWM2M Server 2169 Object) is supported, with a single instance 0 existing, object ID 3 2170 (LWM2M Device object) is supported, with a single instance 0 2171 existing, and object 5 (LWM2M Firmware Object) is supported, with no 2172 existing instances. 2174 13.2.3. Alternate Base URI 2176 If the LWM2M endpoint exposes objects at a base URI other than the 2177 default empty base path, the endpoint must register the base URI 2178 using rt="oma.lwm2m". An example link payload using alternate base 2179 URI would be: 2181 ;rt="oma.lwm2m",,, 2183 This link payload indicates that the lwm2m objects will be placed 2184 under the base URI "/my_lwm2m" and that object ID 1 (server) is 2185 supported, with a single instance 0 existing, and object 5 (firmware 2186 update) is supported. 2188 13.2.4. LWM2M Update Endpoint Registration 2190 An LWM2M Registration update proceeds as described in Section 6.4, 2191 and adds some optional parameter updates: 2193 lt - Registration Lifetime 2194 b - Protocol Binding 2195 sms - MSISDN 2196 link payload - new or modified links 2198 A Registration update is also specified to be used to update the 2199 LWM2M server whenever the endpoint's UDP port or IP address are 2200 changed. 2202 13.2.5. LWM2M De-Register Endpoint 2204 LWM2M allows for de-registration using the delete method on the 2205 returned location from the initial registration operation. LWM2M de- 2206 registration proceeds as described in Section 6.5. 2208 14. Acknowledgments 2210 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2211 Brandt, Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have 2212 provided helpful comments, discussions and ideas to improve and shape 2213 this document. Section 9 is based on an earlier draft by Kerry Lynn. 2214 Zach would also like to thank his colleagues from the EU FP7 SENSEI 2215 project, where many of the resource directory concepts were 2216 originally developed. 2218 15. Changelog 2220 changes from -08 to -09 2222 o clarified the "example use" of the base RD resource values /rd, 2223 /rd-lookup, and /rd-group. 2225 o changed "ins" ABNF notation. 2227 o various editorial improvements, including in examples 2229 o clarifications for RDAO 2231 changes from -07 to -08 2233 o removed link target value returned from domain and group lookup 2234 types 2236 o Maximum length of domain parameter 63 bytes for consistency with 2237 group 2239 o removed option for simple POST of link data, don't require a 2240 .well-known/core resource to accept POST data and handle it in a 2241 special way; we already have /rd for that 2243 o add IPv6 ND Option for discovery of an RD 2245 o clarify group configuration section 6.1 that endpoints must be 2246 registered before including them in a group 2248 o removed all superfluous client-server diagrams 2250 o simplified lighting example 2252 o introduced Commissioning Tool 2254 o RD-Look-up text is extended. 2256 changes from -06 to -07 2258 o added text in the discovery section to allow content format hints 2259 to be exposed in the discovery link attributes 2261 o editorial updates to section 9 2263 o update author information 2265 o minor text corrections 2266 Changes from -05 to -06 2268 o added note that the PATCH section is contingent on the progress of 2269 the PATCH method 2271 changes from -04 to -05 2273 o added Update Endpoint Links using PATCH 2275 o http access made explicit in interface specification 2277 o Added http examples 2279 Changes from -03 to -04: 2281 o Added http response codes 2283 o Clarified endpoint name usage 2285 o Add application/link-format+cbor content-format 2287 Changes from -02 to -03: 2289 o Added an example for lighting and DNS integration 2291 o Added an example for RD use in OMA LWM2M 2293 o Added Read Links operation for link inspection by endpoints 2295 o Expanded DNS-SD section 2297 o Added draft authors Peter van der Stok and Michael Koster 2299 Changes from -01 to -02: 2301 o Added a catalogue use case. 2303 o Changed the registration update to a POST with optional link 2304 format payload. Removed the endpoint type update from the update. 2306 o Additional examples section added for more complex use cases. 2308 o New DNS-SD mapping section. 2310 o Added text on endpoint identification and authentication. 2312 o Error code 4.04 added to Registration Update and Delete requests. 2314 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 2315 resource type parameters. 2317 Changes from -00 to -01: 2319 o Removed the ETag validation feature. 2321 o Place holder for the DNS-SD mapping section. 2323 o Explicitly disabled GET or POST on returned Location. 2325 o New registry for RD parameters. 2327 o Added support for the JSON Link Format. 2329 o Added reference to the Groupcomm WG draft. 2331 Changes from -05 to WG Document -00: 2333 o Updated the version and date. 2335 Changes from -04 to -05: 2337 o Restricted Update to parameter updates. 2339 o Added pagination support for the Lookup interface. 2341 o Minor editing, bug fixes and reference updates. 2343 o Added group support. 2345 o Changed rt to et for the registration and update interface. 2347 Changes from -03 to -04: 2349 o Added the ins= parameter back for the DNS-SD mapping. 2351 o Integrated the Simple Directory Discovery from Carsten. 2353 o Editorial improvements. 2355 o Fixed the use of ETags. 2357 o Fixed tickets 383 and 372 2359 Changes from -02 to -03: 2361 o Changed the endpoint name back to a single registration parameter 2362 ep= and removed the h= and ins= parameters. 2364 o Updated REST interface descriptions to use RFC6570 URI Template 2365 format. 2367 o Introduced an improved RD Lookup design as its own function set. 2369 o Improved the security considerations section. 2371 o Made the POST registration interface idempotent by requiring the 2372 ep= parameter to be present. 2374 Changes from -01 to -02: 2376 o Added a terminology section. 2378 o Changed the inclusion of an ETag in registration or update to a 2379 MAY. 2381 o Added the concept of an RD Domain and a registration parameter for 2382 it. 2384 o Recommended the Location returned from a registration to be 2385 stable, allowing for endpoint and Domain information to be changed 2386 during updates. 2388 o Changed the lookup interface to accept endpoint and Domain as 2389 query string parameters to control the scope of a lookup. 2391 16. References 2393 16.1. Normative References 2395 [I-D.ietf-core-links-json] 2396 Li, K., Rahman, A., and C. Bormann, "Representing CoRE 2397 Formats in JSON and CBOR", draft-ietf-core-links-json-06 2398 (work in progress), July 2016. 2400 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2401 Requirement Levels", BCP 14, RFC 2119, 2402 DOI 10.17487/RFC2119, March 1997, 2403 . 2405 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2406 Resource Identifier (URI): Generic Syntax", STD 66, 2407 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2408 . 2410 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2411 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2412 DOI 10.17487/RFC5226, May 2008, 2413 . 2415 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2416 DOI 10.17487/RFC5988, October 2010, 2417 . 2419 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2420 Cheshire, "Internet Assigned Numbers Authority (IANA) 2421 Procedures for the Management of the Service Name and 2422 Transport Protocol Port Number Registry", BCP 165, 2423 RFC 6335, DOI 10.17487/RFC6335, August 2011, 2424 . 2426 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2427 and D. Orchard, "URI Template", RFC 6570, 2428 DOI 10.17487/RFC6570, March 2012, 2429 . 2431 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2432 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2433 . 2435 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2436 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2437 . 2439 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 2440 DOI 10.17487/RFC7396, October 2014, 2441 . 2443 16.2. Informative References 2445 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2446 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 2447 . 2449 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2450 Application and Support", STD 3, RFC 1123, 2451 DOI 10.17487/RFC1123, October 1989, 2452 . 2454 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2455 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2456 2003, . 2458 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 2459 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 2460 . 2462 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 2463 Bormann, "Neighbor Discovery Optimization for IPv6 over 2464 Low-Power Wireless Personal Area Networks (6LoWPANs)", 2465 RFC 6775, DOI 10.17487/RFC6775, November 2012, 2466 . 2468 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2469 Protocol (HTTP/1.1): Message Syntax and Routing", 2470 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2471 . 2473 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2474 Application Protocol (CoAP)", RFC 7252, 2475 DOI 10.17487/RFC7252, June 2014, 2476 . 2478 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2479 the Constrained Application Protocol (CoAP)", RFC 7390, 2480 DOI 10.17487/RFC7390, October 2014, 2481 . 2483 Editorial Comments 2485 [_TEMPLATE_TODO] This text needs some help from an RFC 6570 expert. 2487 Authors' Addresses 2489 Zach Shelby 2490 ARM 2491 150 Rose Orchard 2492 San Jose 95134 2493 USA 2495 Phone: +1-408-203-9434 2496 Email: zach.shelby@arm.com 2497 Michael Koster 2498 SmartThings 2499 665 Clyde Avenue 2500 Mountain View 94043 2501 USA 2503 Phone: +1-707-502-5136 2504 Email: Michael.Koster@smartthings.com 2506 Carsten Bormann 2507 Universitaet Bremen TZI 2508 Postfach 330440 2509 Bremen D-28359 2510 Germany 2512 Phone: +49-421-218-63921 2513 Email: cabo@tzi.org 2515 Peter van der Stok 2516 consultant 2518 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2519 Email: consultancy@vanderstok.org 2520 URI: www.vanderstok.org