idnits 2.17.1 draft-ietf-core-resource-directory-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 03, 2017) is 2488 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) == Unused Reference: 'RFC2616' is defined on line 2371, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-08 ** 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 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft ARM 4 Intended status: Standards Track M. Koster 5 Expires: January 4, 2018 SmartThings 6 C. Bormann 7 Universitaet Bremen TZI 8 P. van der Stok 9 consultant 10 C. Amsuess, Ed. 11 Energy Harvesting Solutions 12 July 03, 2017 14 CoRE Resource Directory 15 draft-ietf-core-resource-directory-11 17 Abstract 19 In many M2M applications, direct discovery of resources is not 20 practical due to sleeping nodes, disperse networks, or networks where 21 multicast traffic is inefficient. These problems can be solved by 22 employing an entity called a Resource Directory (RD), which hosts 23 descriptions of resources held on other servers, allowing lookups to 24 be performed for those resources. This document specifies the web 25 interfaces that a Resource Directory supports in order for web 26 servers to discover the RD and to register, maintain, lookup and 27 remove resource descriptions. Furthermore, new link attributes 28 useful in conjunction with an RD are defined. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on January 4, 2018. 47 Copyright Notice 49 Copyright (c) 2017 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 67 3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 5 68 3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 5 69 3.3. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 7 70 3.4. Use Case: Home and Building Automation . . . . . . . . . 8 71 3.5. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 8 72 4. Finding a Resource Directory . . . . . . . . . . . . . . . . 9 73 4.1. Resource Directory Address Option (RDAO) . . . . . . . . 10 74 5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 11 75 5.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 12 76 5.2. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 12 77 5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 14 78 5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 17 79 5.3.2. Simple publishing to Resource Directory Server . . . 18 80 5.3.3. Third-party registration . . . . . . . . . . . . . . 18 81 5.3.4. Plurality of link references in a Registration . . . 19 82 5.4. Operations on the Registration Resource . . . . . . . . . 19 83 5.4.1. Registration Update . . . . . . . . . . . . . . . . . 20 84 5.4.2. Registration Removal . . . . . . . . . . . . . . . . 22 85 5.4.3. Read Endpoint Links . . . . . . . . . . . . . . . . . 23 86 5.4.4. Update Endpoint Links . . . . . . . . . . . . . . . . 24 87 6. RD Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 28 88 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 28 89 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 30 90 7. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 31 91 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36 92 8.1. Endpoint Identification and Authentication . . . . . . . 36 93 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 36 94 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 37 96 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 97 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 37 98 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 37 99 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 37 100 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 38 101 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 38 102 10.1.1. Installation Characteristics . . . . . . . . . . . . 39 103 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 40 104 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 43 105 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 43 106 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 45 107 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 46 108 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 47 109 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 110 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 47 111 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 112 13.1. Normative References . . . . . . . . . . . . . . . . . . 51 113 13.2. Informative References . . . . . . . . . . . . . . . . . 52 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 116 1. Introduction 118 The work on Constrained RESTful Environments (CoRE) aims at realizing 119 the REST architecture in a suitable form for the most constrained 120 nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and 121 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 122 applications such as smart energy and building automation. 124 The discovery of resources offered by a constrained server is very 125 important in machine-to-machine applications where there are no 126 humans in the loop and static interfaces result in fragility. The 127 discovery of resources provided by an HTTP Web Server is typically 128 called Web Linking [RFC5988]. The use of Web Linking for the 129 description and discovery of resources hosted by constrained web 130 servers is specified by the CoRE Link Format [RFC6690]. However, 131 [RFC6690] only describes how to discover resources from the web 132 server that hosts them by requesting "/.well-known/core". In many 133 M2M scenarios, direct discovery of resources is not practical due to 134 sleeping nodes, disperse networks, or networks where multicast 135 traffic is inefficient. These problems can be solved by employing an 136 entity called a Resource Directory (RD), which hosts descriptions of 137 resources held on other servers, allowing lookups to be performed for 138 those resources. 140 This document specifies the web interfaces that a Resource Directory 141 supports in order for web servers to discover the RD and to register, 142 maintain, lookup and remove resource descriptions. Furthermore, new 143 link attributes useful in conjunction with a Resource Directory are 144 defined. Although the examples in this document show the use of 145 these interfaces with CoAP [RFC7252], they can be applied in an 146 equivalent manner to HTTP [RFC7230]. 148 2. Terminology 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 152 "OPTIONAL" in this document are to be interpreted as described in 153 [RFC2119]. The term "byte" is used in its now customary sense as a 154 synonym for "octet". 156 This specification requires readers to be familiar with all the terms 157 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 158 should also be familiar with the terms and concepts discussed in 159 [RFC7252]. To describe the REST interfaces defined in this 160 specification, the URI Template format is used [RFC6570]. 162 This specification makes use of the following additional terminology: 164 Resource Directory 165 A web entity that stores information about web resources and 166 implements the REST interfaces defined in this specification for 167 registration and lookup of those resources. 169 Domain 170 In the context of a Resource Directory, a domain is a logical 171 grouping of endpoints. This specification assumes that the list 172 of Domains supported by an RD is pre-configured by that RD. When 173 a domain is exported to DNS, the domain value equates to the DNS 174 domain name. 176 Group 177 In the context of a Resource Directory, a group is a logical 178 grouping of endpoints for the purpose of group communications. 179 All groups within a domain are unique. 181 Endpoint 182 Endpoint (EP) is a term used to describe a web server or client in 183 [RFC7252]. In the context of this specification an endpoint is 184 used to describe a web server that registers resources to the 185 Resource Directory. An endpoint is identified by its endpoint 186 name, which is included during registration, and is unique within 187 the associated domain of the registration. 189 Context 190 When registering links to a Resource Directory, the Context refers 191 to the scheme, address, port, and base path for all the links 192 registered on behalf of an endpoint, of the general form 193 scheme://host:port/path/ where the client may explicitly set the 194 scheme and host, and may supply the port and path as optional 195 parameters. When the context of a registration is explicitly set, 196 the URI resolution rules in [RFC3986] MUST be applied. 198 Commissioning Tool 199 Commissioning Tool (CT) is a device that assists during the 200 installation of the network by assigning values to parameters, 201 naming endpoints and groups, or adapting the installation to the 202 needs of the applications. 204 RDAO 205 Resource Directory Address Option. 207 3. Architecture and Use Cases 209 3.1. Principles 211 The Resource Directory is primarily a tool to make discovery 212 operations more efficient than querying /.well-known/core on all 213 connected device, or across boundaries that would be limiting those 214 operations. 216 It provides a cache (in the high-level sense, not as defined in 217 [RFC7252]/[RFC2616]) of data that could otherwise only be obtained by 218 directly querying the /.well-known/core resource on the target 219 device, or by accessing those resources with a multicast request. 221 From that, it follows that no information should be stored in the 222 resource directory that cannot be discovered from querying the 223 described device's /.well-known/core resource directly. 225 It also follows that data in the resource directory can only be 226 provided by the device whose descriptions are cached or a dedicated 227 Commissioning Tool (CT). These CTs are thought to act on behalf 228 agents too constrained, or generally unable, to present that 229 information themselves. No other client can modify data in the 230 resource directory or even expect those changes to propagate back to 231 its source. 233 3.2. Architecture 235 The resource directory architecture is illustrated in Figure 1. A 236 Resource Directory (RD) is used as a repository for Web Links 237 [RFC5988] about resources hosted on other web servers, which are 238 called endpoints (EP). An endpoint is a web server associated with a 239 scheme, IP address and port (called Context), thus a physical node 240 may host one or more endpoints. The RD implements a set of REST 241 interfaces for endpoints to register and maintain sets of Web Links 242 (called resource directory registration entries), and for clients to 243 lookup resources from the RD or maintain groups. Endpoints 244 themselves can also act as clients. An RD can be logically segmented 245 by the use of Domains. The domain an endpoint is associated with can 246 be defined by the RD or configured by an outside entity. This 247 information hierarchy is shown in Figure 2. 249 A mechanism to discover an RD using CoRE Link Format [RFC6690] is 250 defined. 252 Endpoints proactively register and maintain resource directory 253 registration entries on the RD, which are soft state and need to be 254 periodically refreshed. 256 An endpoint is provided with interfaces to register, update and 257 remove a resource directory registration entry. It is also possible 258 for an RD to fetch Web Links from endpoints and add them as resource 259 directory entries. 261 At the first registration of a set of entries, a "registration 262 resource" is created, the location of which is returned to the 263 registering endpoint. The registering endpoint uses this 264 registration resource to manage the contents of the registration 265 entry. 267 A lookup interface for discovering any of the Web Links held in the 268 RD is provided using the CoRE Link Format. 270 Registration Lookup, Group 271 Interface Interfaces 272 +----+ | | 273 | EP |---- | | 274 +----+ ---- | | 275 --|- +------+ | 276 +----+ | ----| | | +--------+ 277 | EP | ---------|-----| RD |----|-----| Client | 278 +----+ | ----| | | +--------+ 279 --|- +------+ | 280 +----+ ---- | | 281 | EP |---- | | 282 +----+ 284 Figure 1: The resource directory architecture. 286 +------------+ 287 | Domain | <-- Name 288 +------------+ 289 | | 290 | +------------+ 291 | | Group | <-- Name, Scheme, IP, Port 292 | +------------+ 293 | | 294 +------------+ 295 | Endpoint | <-- Name, Scheme, IP, Port 296 +------------+ 297 | 298 | 299 +------------+ 300 | Resource | <-- Target, Parameters 301 +------------+ 303 Figure 2: The resource directory information hierarchy. 305 3.3. Use Case: Cellular M2M 307 Over the last few years, mobile operators around the world have 308 focused on development of M2M solutions in order to expand the 309 business to the new type of users: machines. The machines are 310 connected directly to a mobile network using an appropriate embedded 311 air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short 312 and wide range wireless interfaces. From the system design point of 313 view, the ambition is to design horizontal solutions that can enable 314 utilization of machines in different applications depending on their 315 current availability and capabilities as well as application 316 requirements, thus avoiding silo like solutions. One of the crucial 317 enablers of such design is the ability to discover resources 318 (machines -- endpoints) capable of providing required information at 319 a given time or acting on instructions from the end users. 321 In a typical scenario, during a boot-up procedure (and periodically 322 afterwards), the machines (endpoints) register with a Resource 323 Directory (for example EPs installed on vehicles enabling tracking of 324 their position for fleet management purposes and monitoring 325 environment parameters) hosted by the mobile operator or somewhere 326 else in the network, periodically a description of its own 327 capabilities. Due to the usual network configuration of mobile 328 networks, the EPs attached to the mobile network may not always be 329 efficiently reachable. Therefore, a remote server is usually used to 330 provide proxy access to the EPs. The address of each (proxy) 331 endpoint on this server is included in the resource description 332 stored in the RD. The users, for example mobile applications for 333 environment monitoring, contact the RD, look up the endpoints capable 334 of providing information about the environment using appropriate set 335 of link parameters, obtain information on how to contact them (URLs 336 of the proxy server) and then initiate interaction to obtain 337 information that is finally processed, displayed on the screen and 338 usually stored in a database. Similarly, fleet management systems 339 provide the appropriate link parameters to the RD to look up for EPs 340 deployed on the vehicles the application is responsible for. 342 3.4. Use Case: Home and Building Automation 344 Home and commercial building automation systems can benefit from the 345 use of M2M web services. The discovery requirements of these 346 applications are demanding. Home automation usually relies on run- 347 time discovery to commission the system, whereas in building 348 automation a combination of professional commissioning and run-time 349 discovery is used. Both home and building automation involve peer- 350 to-peer interactions between endpoints, and involve battery-powered 351 sleeping devices. 353 3.5. Use Case: Link Catalogues 355 Resources may be shared through data brokers that have no knowledge 356 beforehand of who is going to consume the data. Resource Directory 357 can be used to hold links about resources and services hosted 358 anywhere to make them discoverable by a general class of 359 applications. 361 For example, environmental and weather sensors that generate data for 362 public consumption may provide the data to an intermediary server, or 363 broker. Sensor data are published to the intermediary upon changes 364 or at regular intervals. Descriptions of the sensors that resolve to 365 links to sensor data may be published to a Resource Directory. 366 Applications wishing to consume the data can use RD Lookup to 367 discover and resolve links to the desired resources and endpoints. 368 The Resource Directory service need not be coupled with the data 369 intermediary service. Mapping of Resource Directories to data 370 intermediaries may be many-to-many. 372 Metadata in web link formats like [RFC6690] are supplied by Resource 373 Directories, which may be internally stored as triples, or relation/ 374 attribute pairs providing metadata about resource links. External 375 catalogs that are represented in other formats may be converted to 376 common web linking formats for storage and access by Resource 377 Directories. Since it is common practice for these to be URN 378 encoded, simple and lossless structural transforms should generally 379 be sufficient to store external metadata in Resource Directories. 381 The additional features of Resource Directory allow domains to be 382 defined to enable access to a particular set of resources from 383 particular applications. This provides isolation and protection of 384 sensitive data when needed. Resource groups may defined to allow 385 batched reads from multiple resources. 387 4. Finding a Resource Directory 389 Several mechanisms can be employed for discovering the RD, including 390 assuming a default location (e.g. on an Edge Router in a LoWPAN), 391 assigning an anycast address to the RD, using DHCP, or discovering 392 the RD using .well-known/core and hyperlinks as specified in CoRE 393 Link Format [RFC6690]. Endpoints that want to contact a Resource 394 Directory can obtain candidate IP addresses for such servers in a 395 number of ways. 397 In a 6LoWPAN, good candidates can be taken from: 399 o specific static configuration (e.g., anycast addresses), if any, 401 o the ABRO option of 6LoWPAN-ND [RFC6775], 403 o other ND options that happen to point to servers (such as RDNSS), 405 o DHCPv6 options that might be defined later. 407 o The IPv6 Neighbor Discovery Resource Directory Address Option 408 described in Section 4.1 410 In networks with more inexpensive use of multicast, the candidate IP 411 address may be a well-known multicast address, i.e. directory servers 412 are found by simply sending GET requests to that well-known multicast 413 address (see Section 5.2). 415 Constrained nodes configured in large batches may be configured for 416 an anycast address for the RD. Each target network environment in 417 which some of these preconfigured nodes are to be brought up is then 418 configured with a route for this anycast address that leads to an RD 419 that is appropriate for the environment. 421 As some of these sources are just (more or less educated) guesses, 422 endpoints MUST make use of any error messages to very strictly rate- 423 limit requests to candidate IP addresses that don't work out. For 424 example, an ICMP Destination Unreachable message (and, in particular, 425 the port unreachable code for this message) may indicate the lack of 426 a CoAP server on the candidate host, or a CoAP error response code 427 such as 4.05 "Method Not Allowed" may indicate unwillingness of a 428 CoAP server to act as a directory server. 430 4.1. Resource Directory Address Option (RDAO) 432 The Resource Directory Option (RDAO) using IPv6 neighbor Discovery 433 (ND) carries information about the address of the Resource Directory 434 (RD). This information is needed when endpoints cannot discover the 435 Resource Directory with link-local multicast address because the 436 endpoint and the RD are separated by a border Router (6LBR). In many 437 circumstances the availability of DHCP cannot be guaranteed either 438 during commissioning of the network. The presence and the use of the 439 RD is essential during commissioning. 441 It is possible to send multiple RDAO options in one message, 442 indicating as many resource directory addresses. 444 The lifetime 0x0 means that the RD address is invalid and to be 445 removed. 447 The RDAO format is: 449 0 1 2 3 450 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 451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 452 | Type | Length = 3 | Valid Lifetime | 453 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 454 | Reserved | 455 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 456 | | 457 + + 458 | | 459 + RD Address + 460 | | 461 + + 462 | | 463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 465 Fields: 467 Type: 38 469 Length: 8-bit unsigned integer. The length of 470 the option in units of 8 bytes. 471 Always 3. 473 Valid Lifetime: 16-bit unsigned integer. The length of 474 time in units of 60 seconds (relative to 475 the time the packet is received) that 476 this Resource Directory address is valid. 477 A value of all zero bits (0x0) indicates 478 that this Resource Directory address 479 is not valid anymore. 481 Reserved: This field is unused. It MUST be 482 initialized to zero by the sender and 483 MUST be ignored by the receiver. 485 RD Address: IPv6 address of the RD. 487 Figure 3: Resource Directory Address Option 489 5. Resource Directory 491 This section defines the required set of REST interfaces between a 492 Resource Directory (RD) and endpoints. Although the examples 493 throughout this section assume the use of CoAP [RFC7252], these REST 494 interfaces can also be realized using HTTP [RFC7230]. In all 495 definitions in this section, both CoAP response codes (with dot 496 notation) and HTTP response codes (without dot notation) are shown. 498 An RD implementing this specification MUST support the discovery, 499 registration, update, lookup, and removal interfaces defined in this 500 section. 502 5.1. Content Formats 504 Resource Directory implementations using this specification MUST 505 support the application/link-format content format (ct=40). 507 Resource Directories implementing this specification MAY support 508 additional content formats. 510 Any additional content format supported by a Resource Directory 511 implementing this specification MUST have an equivalent serialization 512 in the application/link-format content format. 514 5.2. URI Discovery 516 Before an endpoint can make use of an RD, it must first know the RD's 517 address and port, and the URI path information for its REST APIs. 518 This section defines discovery of the RD and its URIs using the well- 519 known interface of the CoRE Link Format [RFC6690]. It is however 520 expected that RDs will also be discoverable via other methods 521 depending on the deployment. 523 Discovery of the RD registration URI path is performed by sending 524 either a multicast or unicast GET request to "/.well-known/core" and 525 including a Resource Type (rt) parameter [RFC6690] with the value 526 "core.rd" in the query string. Likewise, a Resource Type parameter 527 value of "core.rd-lookup*" is used to discover the URIs for RD Lookup 528 operations, and "core.gp" is used to discover the URI path for RD 529 Group operations. Upon success, the response will contain a payload 530 with a link format entry for each RD function discovered, indicating 531 the URI path of the RD function returned and the corresponding 532 Resource Type. When performing multicast discovery, the multicast IP 533 address used will depend on the scope required and the multicast 534 capabilities of the network. 536 A Resource Directory MAY provide hints about the content-formats it 537 supports in the links it exposes or registers, using the "ct" link 538 attribute, as shown in the example below. Clients MAY use these 539 hints to select alternate content-formats for interaction with the 540 Resource Directory. 542 HTTP does not support multicast and consequently only unicast 543 discovery can be supported using HTTP. Links to Resource Directories 544 MAY be registered in other Resource Directories, and well-known entry 545 points SHOULD be provided to enable the bootstrapping of unicast 546 discovery. 548 An RD implementation of this specification MUST support query 549 filtering for the rt parameter as defined in [RFC6690]. 551 The discovery request interface is specified as follows: 553 Interaction: EP -> RD 555 Method: GET 557 URI Template: /.well-known/core{?rt} 559 URI Template Variables: 561 rt := Resource Type (optional). MAY contain one of the values 562 "core.rd", "core.rd-lookup*", "core.rd-lookup-d", "core.rd- 563 lookup-res", "core.rd-lookup-ep", "core.rd-lookup-gp", 564 "core.rd-group" or "core.rd*" 566 Content-Format: application/link-format (if any) 568 Content-Format: application/link-format+json (if any) 570 Content-Format: application/link-format+cbor (if any) 572 The following response codes are defined for this interface: 574 Success: 2.05 "Content" or 200 "OK" with an application/link-format, 575 application/link-format+json, or application/link-format+cbor 576 payload containing one or more matching entries for the RD 577 resource. 579 Failure: 4.04 "Not Found" or 404 "Not Found" is returned in case no 580 matching entry is found for a unicast request. 582 Failure: 4.00 "Bad Request" or 400 "Bad Request" is returned in case 583 of a malformed request for a unicast request. 585 Failure: No error response to a multicast request. 587 HTTP support : YES (Unicast only) 589 The following example shows an endpoint discovering an RD using this 590 interface, thus learning that the RD registration resource is, in 591 this example, at /rd, and that the content-format delivered by the 592 server hosting the resource is application/link-format (ct=40). Note 593 that it is up to the RD to choose its RD resource paths. 595 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 597 Res: 2.05 Content 598 ;rt="core.rd";ct=40, 599 ;rt="core.rd-lookup-ep";ct=40, 600 ;rt="core.rd-lookup-res";ct=40, 601 ;rt="core.rd-lookup-gp";ct=40, 602 ;rt="core.rd-lookup-d";ct=40, 603 ;rt="core.rd-group";ct=40 605 Figure 4: Example discovery exchange 607 The following example shows the way of indicating that a client may 608 request alternate content-formats. The Content-Format code attribute 609 "ct" MAY include a space-separated sequence of Content-Format codes 610 as specified in Section 7.2.1 of [RFC7252], indicating that multiple 611 content-formats are available. The example below shows the required 612 Content-Format 40 (application/link-format) indicated as well as a 613 more application-specific content format (picked as 65225 in this 614 example; this is in the experimental space, not an assigned value). 615 The RD resource paths /rd, /rd-lookup, and /rd-group are example 616 values. This server only implements some of the interfaces described 617 in this document. 619 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 621 Res: 2.05 Content 622 ;rt="core.rd";ct="40 65225", 623 ;rt="core.rd-lookup-res";ct="40 65225", 624 ;rt="core.rd-lookup-ep";ct="40 65225", 625 ;rt="core.rd-group";ct="40 65225" 627 5.3. Registration 629 After discovering the location of an RD, an endpoint MAY register its 630 resources using the registration interface. This interface accepts a 631 POST from an endpoint containing the list of resources to be added to 632 the directory as the message payload in the CoRE Link Format 633 [RFC6690], JSON CoRE Link Format (application/link-format+json), or 634 CBOR CoRE Link Format (application/link-format+cbor) 635 [I-D.ietf-core-links-json], along with query parameters indicating 636 the name of the endpoint, and optionally its domain and the lifetime 637 of the registration. It is expected that other specifications will 638 define further parameters (see Section 9.3). The RD then creates a 639 new registration resource in the RD and returns its location. An 640 endpoint MUST use that location when refreshing registrations using 641 this interface. Endpoint resources in the RD are kept active for the 642 period indicated by the lifetime parameter. The endpoint is 643 responsible for refreshing the entry within this period using either 644 the registration or update interface. The registration interface 645 MUST be implemented to be idempotent, so that registering twice with 646 the same endpoint parameters ep and d does not create multiple RD 647 entries. A new registration may be created at any time to supersede 648 an existing registration, replacing the registration parameters and 649 links. 651 The registration request interface is specified as follows: 653 Interaction: EP -> RD 655 Method: POST 657 URI Template: {+rd}{?ep,d,et,lt,con} 659 URI Template Variables: 661 rd := RD registration URI (mandatory). This is the location of 662 the RD, as obtained from discovery. 664 ep := Endpoint name (mandatory). The endpoint name is an 665 identifier that MUST be unique within a domain. The maximum 666 length of this parameter is 63 bytes. 668 d := Domain (optional). The domain to which this endpoint 669 belongs. The maximum length of this parameter is 63 bytes. 670 When this parameter is elided, the RD MAY associate the 671 endpoint with a configured default domain. 673 et := Endpoint Type (optional). The semantic type of the 674 endpoint. This parameter SHOULD be less than 63 bytes. 676 lt := Lifetime (optional). Lifetime of the registration in 677 seconds. Range of 60-4294967295. If no lifetime is included 678 in the initial registration, a default value of 86400 (24 679 hours) SHOULD be assumed. If the lt parameter is not included 680 in a registration refresh or update operation, the most 681 recently supplied value SHALL be re-used. 683 con := Context (optional). This parameter sets the scheme, 684 address, port and path at which this server is available in the 685 form scheme://host:port/path. In the absence of this parameter 686 the scheme of the protocol, source address and source port of 687 the register request are assumed. This parameter is mandatory 688 when the directory is filled by a third party such as an 689 commissioning tool. When con is used, scheme and host are 690 mandatory and port and path parameters are optional. If the 691 endpoint uses an ephemeral port to register with, it MUST 692 include the con: parameter in the registration to provide a 693 valid network path. If the endpoint which is located behind a 694 NAT gateway is registering with a Resource Directory which is 695 on the network service side of the NAT gateway, the endpoint 696 MUST use a persistent port for the outgoing registration in 697 order to provide the NAT gateway with a valid network address 698 for replies and incoming requests. 700 Content-Format: application/link-format 702 Content-Format: application/link-format+json 704 Content-Format: application/link-format+cbor 706 The following response codes are defined for this interface: 708 Success: 2.01 "Created" or 201 "Created". The Location header 709 option MUST be included in the response when a new registration 710 resource is created. This Location MUST be a stable identifier 711 generated by the RD as it is used for all subsequent operations on 712 this registration resource. The registration resource location 713 thus returned is for the purpose of updating the lifetime of the 714 registration and for maintaining the content of the registered 715 links, including updating and deleting links. 717 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 718 request. 720 Failure: 4.09 "Conflict" or 409 "Conflict". Attempt to update the 721 registration content with links resulting in plurality of 722 references; see Section 5.3.4. 724 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 725 Service could not perform the operation. 727 HTTP support: YES 729 The following example shows an endpoint with the name "node1" 730 registering two resources to an RD using this interface. The 731 location "/rd" is an example RD location discovered in a request 732 similar to Figure 4. 734 Req: POST coap://rd.example.com/rd?ep=node1 735 Content-Format: 40 736 Payload: 737 ;ct=41;rt="temperature-c";if="sensor", 738 ;ct=41;rt="light-lux";if="sensor" 740 Res: 2.01 Created 741 Location: /rd/4521 743 A Resource Directory may optionally support HTTP. Here is an example 744 of the same registration operation above, when done using HTTP. 746 Req: POST /rd?ep=node1&con=http://[2001:db8::1:1] HTTP/1.1 747 Host : example.com 748 Content-Type: application/link-format 749 Payload: 750 ;ct=41;rt="temperature-c";if="sensor", 751 ;ct=41;rt="light-lux";if="sensor" 753 Res: 201 Created 754 Location: /rd/4521 756 5.3.1. Simple Registration 758 Not all endpoints hosting resources are expected to know how to 759 upload links to a RD as described in Section 5.3. Instead, simple 760 endpoints can implement the Simple Registration approach described in 761 this section. An RD implementing this specification MUST implement 762 Simple Registration. However, there may be security reasons why this 763 form of directory discovery would be disabled. 765 This approach requires that the endpoint makes available the hosted 766 resources that it wants to be discovered, as links on its "/.well- 767 known/core" interface as specified in [RFC6690]. 769 The endpoint then finds one or more addresses of the directory server 770 as described in Section 4. 772 An endpoint can send (a selection of) hosted resources to a directory 773 server for publication as described in Section 5.3.2. 775 The directory server integrates the information it received this way 776 into its resource directory. It MAY make the information available 777 to further directories, if it can ensure that a loop does not form. 778 The protocol used between directories to ensure loop-free operation 779 is outside the scope of this document. 781 5.3.2. Simple publishing to Resource Directory Server 783 An endpoint that wants to make itself discoverable occasionally sends 784 a POST request to the "/.well-known/core" URI of any candidate 785 directory server that it finds. The body of the POST request is 786 empty, which triggers the resource directory server to perform GET 787 requests at the requesting server's default discovery URI to obtain 788 the link-format payload to register. 790 The endpoint MUST include the endpoint name and MAY include the 791 registration parameters d, lt, and et, in the POST request as per 792 Section 5.3. 794 The following example shows an endpoint using simple publishing, by 795 simply sending an empty POST to a resource directory. 797 Req:(to RD server from [ff02::1]) 798 POST coap://rd.example.com/.well-known/core?lt=6000;ep=node1 800 Content-Format: 40 802 payload: 804 (empty payload) 806 Res: 2.04 Changed 808 (later) 810 Req: (from RD server to [ff02::1]) 811 GET coap://[ff02::1]/.well-known/core 813 Accept: 40 815 Res: 2.05 Content 817 payload: 819 821 5.3.3. Third-party registration 823 For some applications, even Simple Registration may be too taxing for 824 certain very constrained devices, in particular if the security 825 requirements become too onerous. 827 In a controlled environment (e.g. building control), the Resource 828 Directory can be filled by a third device, called a commissioning 829 tool. The commissioning tool can fill the Resource Directory from a 830 database or other means. For that purpose the scheme, IP address and 831 port of the registered device is indicated in the Context parameter 832 of the registration described in Section 5.3. 834 5.3.4. Plurality of link references in a Registration 836 Plurality of link references within a Registration (registration 837 resource) is an indication of some error condition and should not be 838 allowed. 840 Plurality of link references exists if, and only if, two or more 841 links in a Registration contain identical context, target, and 842 relation values. This condition would be likely to arise if there 843 were multiple co-ordinators or configuration tools, each with a 844 different set of configuration values for the same resource. 846 A Resource Directory SHOULD reject a registration, or an operation on 847 a registration, which would result in a plurality of link references 848 within the the context of the registration. There is no requirement 849 in this document for a resource directory to check for plurality of 850 reference between different registrations. Resource Directory 851 operations which are rejected due to reference plurality SHOULD be 852 returned the "Conflict" code, indicating that there is someting wrong 853 with the request. 855 5.4. Operations on the Registration Resource 857 After the initial registration, an endpoint should retain the 858 returned location of the Registration Resource for further 859 operations, including refreshing the registration in order to extend 860 the lifetime and "keep-alive" the registration. If the lifetime of 861 the registration expires, the RD SHOULD NOT respond to discovery 862 queries with information from the endpoint. The RD SHOULD continue 863 to provide access to the Registration Resource after a registration 864 time-out occurs in order to enable the registering endpoint to 865 eventually refresh the registration. The RD MAY eventually remove 866 the registration resource for the purpose of resource recovery and 867 garbage collection. If the Registration Resource is removed, the 868 endpoint will need to re-register. 870 The Registration Resource may also be used to inspect the 871 registration resource using GET, update the registration link 872 contents using PATCH (as introduced in [RFC8132]), or cancel the 873 registration using DELETE. 875 These operations are described in this section. 877 In accordance with Section 5.3.4, operations which would result in 878 plural link references within the context of a registration resource 879 SHOULD be rejected using the "Conflict" result code. 881 5.4.1. Registration Update 883 The update interface is used by an endpoint to refresh or update its 884 registration with an RD. To use the interface, the endpoint sends a 885 POST request to the registration resource returned in the Location 886 header option in the response returned from the intial registration 887 operation. 889 An update MAY update the lifetime or context registration parameters 890 "lt", "con" as in Section 5.3 ) if the previous settings are to be 891 retained. Parameters that are not being changed changed SHOULD NOT 892 be included in an update. Adding parameters that have not changed 893 increases the size of the message but does not have any other 894 implications. Parameters MUST be included as query parameters in an 895 update operation as in Section 5.3. 897 Upon receiving an update request, an RD MUST reset the timeout for 898 that endpoint and update the scheme, IP address and port of the 899 endpoint, using the source address of the update, or the context 900 ("con") parameter if present. If the lifetime parameter "lt" is 901 included in the received update request, the RD MUST update the 902 lifetime of the registration and set the timeout equal to the new 903 lifetime. If the lifetime parameter is not included in the 904 registration update, the most recent setting is re-used for the next 905 registration time-out period. 907 An update MAY optionally add or replace links for the endpoint by 908 including those links in the payload of the update as a CoRE Link 909 Format document. A link is replaced only if all of the target URI 910 and relation type (if present) and anchor value (if present) match. 912 If the link payload is included, it SHOULD be checked for reference 913 plurality as described in Section 5.3.4 and rejected with a 914 "Conflict" result if there are plural link references detected. 916 In addition to the use of POST, as described in this section, there 917 is an alternate way to add, replace, and delete links using PATCH as 918 described in Section 5.4.4. 920 The update registration request interface is specified as follows: 922 Interaction: EP -> RD 924 Method: POST 925 URI Template: {+location}{?lt,con} 927 URI Template Variables: 929 location := This is the Location returned by the RD as a result 930 of a successful earlier registration. 932 lt := Lifetime (optional). Lifetime of the registration in 933 seconds. Range of 60-4294967295. If no lifetime is included, 934 the previous last lifetime set on a previous update or the 935 original registration (falling back to 86400) SHOULD be used. 937 con := Context (optional). This parameter sets the scheme, 938 address and port at which this server is available in the form 939 scheme://host:port/path. In the absence of this parameter the 940 scheme of the protocol, source address and source port of the 941 register request are assumed. This parameter is mandatory when 942 the directory is filled by a third party such as an 943 commissioning tool. When con is used, scheme and host are 944 mandatory and port and path parameters are optional. 946 Content-Format: application/link-format (mandatory) 948 Content-Format: application/link-format+json (optional) 950 Content-Format: application/link-format+cbor (optional) 952 The following response codes are defined for this interface: 954 Success: 2.04 "Changed" or 204 "No Content" if the update was 955 successfully processed. 957 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 958 request. 960 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 961 exist (e.g. may have expired). 963 Failure: 4.09 "Conflict" or 409 "Conflict". Attempt to update the 964 registration content with links resulting in plurality of 965 references; see Section 5.3.4. 967 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 968 Service could not perform the operation. 970 HTTP support: YES 971 The following example shows an endpoint updating its registration at 972 an RD using this interface with the example location value: /rd/4521. 974 Req: POST /rd/4521 976 Res: 2.04 Changed 978 The following example shows an endpoint updating its registration 979 with a new lifetime and context, changing an existing link, and 980 adding a new link using this interface with the example location 981 value /rd/4521. With the initial registration the client set the 982 following values: 984 o lifetime (lt)=500 986 o context (con)=coap://local-proxy-old.example.com:5683 988 o resource= ;ct=41;rt="foobar";if="sensor" 990 Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683" 991 Content-Format: 40 992 Payload: 993 ;ct=41;rt="temperature-f";if="sensor", 994 ;ct=41;rt="door";if="sensor" 996 Res: 2.04 Changed 998 5.4.2. Registration Removal 1000 Although RD entries have soft state and will eventually timeout after 1001 their lifetime, an endpoint SHOULD explicitly remove its entry from 1002 the RD if it knows it will no longer be available (for example on 1003 shut-down). This is accomplished using a removal interface on the RD 1004 by performing a DELETE on the endpoint resource. 1006 The removal request interface is specified as follows: 1008 Interaction: EP -> RD 1010 Method: DELETE 1012 URI Template: {+location} 1014 URI Template Variables: 1016 location := This is the Location returned by the RD as a result 1017 of a successful earlier registration. 1019 The following responses codes are defined for this interface: 1021 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1023 Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed 1024 request. 1026 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1027 exist (e.g. may have expired). 1029 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1030 Service could not perform the operation. 1032 HTTP support: YES 1034 The following examples shows successful removal of the endpoint from 1035 the RD with example location value /rd/4521. 1037 Req: DELETE /rd/4521 1039 Res: 2.02 Deleted 1041 5.4.3. Read Endpoint Links 1043 Some endpoints may wish to manage their links as a collection, and 1044 may need to read the current set of links stored in the registration 1045 resource, in order to determine link maintenance operations. 1047 One or more links MAY be selected by using query filtering as 1048 specified in [RFC6690] Section 4.1 1050 If no links are selected, the Resource Directory SHOULD return an 1051 empty payload. 1053 The read request interface is specified as follows: 1055 Interaction: EP -> RD 1057 Method: GET 1059 URI Template: {+location}{?href,rel,rt,if,ct} 1061 URI Template Variables: 1063 location := This is the Location returned by the RD as a result 1064 of a successful earlier registration. 1066 href,rel,rt,if,ct := link relations and attributes specified in 1067 the query in order to select particular links based on their 1068 relations and attributes. "href" denotes the URI target of the 1069 link. See [RFC6690] Sec. 4.1 1071 The following responses codes are defined for this interface: 1073 Success: 2.05 "Content" or 200 "OK" upon success with an 1074 "application/link-format", "application/link-format+cbor", or 1075 "application/link-format+json" payload. 1077 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1078 request. 1080 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1081 exist (e.g. may have expired). 1083 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1084 Service could not perform the operation. 1086 HTTP support: YES 1088 The following examples show successful read of the endpoint links 1089 from the RD, with example location value /rd/4521. 1091 Req: GET /rd/4521 1093 Res: 2.01 Content 1094 Payload: 1095 ;ct=41;rt="temperature-c";if="sensor", 1096 ;ct=41;rt="light-lux";if="sensor" 1098 5.4.4. Update Endpoint Links 1100 A PATCH update adds, removes or changes links for the endpoint by 1101 including link update information in the payload of the update as a 1102 merge-patch+json format [RFC7396] document. 1104 Other PATCH document formats may be used as appropriate for patching 1105 the array of objects format of a Registration Resource. In 1106 particular, a select-merge patch document format could combine the 1107 function of link selection query and link attribute replacement 1108 values. 1110 One or more links are selected for update by using query filtering as 1111 specified in [RFC6690] Section 4.1 1112 The query filter selects the links to be modified or deleted, by 1113 matching the query parameter values to the values of the link 1114 attributes. 1116 When the query parameters are not present in the request, the payload 1117 specifies links to be added to the target document. When the query 1118 parameters are present, the attribute names and values in the query 1119 parameters select one or more links on which to apply the PATCH 1120 operation. 1122 If no links are selected by the query parameters, the PATCH operation 1123 SHOULD NOT update the state of any resource, and SHOULD return a 1124 reply of "Changed". 1126 If an attribute name specified in the PATCH document exists in any 1127 the set of selected links, all occurrences of the attribute value in 1128 the target document MUST be updated using the value from the PATCH 1129 payload. If the attribute name is not present in any selected links, 1130 the attribute MUST be added to the links. 1132 If the PATCH payload contains plural link references, or processing 1133 the PATCH payload would result in plural link references, the request 1134 SHOULD be rejected with a "Conflict" result. 1136 If the PATCH payload results in the modification of link target, 1137 context, or relation values, that is "href", "rel", or "anchor", the 1138 request SHOULD be rejected with a "Conflict" result code. 1140 The update request interface is specified as follows: 1142 Interaction: EP -> RD 1144 Method: PATCH 1146 URI Template: {+location}{?href,rel,rt,if,ct} 1148 URI Template Variables: 1150 location := This is the Location returned by the RD as a result 1151 of a successful earlier registration. 1153 href,rel,rt,if,ct := link relations and attributes specified in 1154 the query in order to select particular links based on their 1155 relations and attributes. "href" denotes the URI target of the 1156 link. See [RFC6690] Sec. 4.1 1158 Content-Format: application/merge-patch+json (mandatory) 1159 The following response codes are defined for this interface: 1161 Success: 2.04 "Changed" 0r 204 "No Content" in the update was 1162 successfully processed. 1164 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1165 request. 1167 Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource 1168 does not exist (e.g. may have expired). 1170 Failure: 4.09 "Conflict" or 409 "Conflict". Attempt to update the 1171 registration content with links resulting in plurality of 1172 references; see Section 5.3.4. 1174 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1175 Service could not perform the operation. 1177 HTTP support: YES 1179 The following examples show an endpoint adding , 1180 modifying , and removing links in RD 1181 using the Update Endpoint Links function with the example location 1182 value /rd/4521. 1184 The Registration Resource initial state is: 1186 Req: GET /rd/4521 1188 Res: 2.01 Content 1189 Payload: 1190 ;ct=41;rt="temperature", 1191 ;ct=41;rt="light-lux";if="sensor" 1193 The following example shows an EP adding the link ;ct=41;rt="humid-s";if="sensor" to the collection of links at 1195 the location /rd/4521. 1197 Req: PATCH /rd/4521 1199 Payload: 1200 [{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}] 1202 Content-Format: 1203 application/merge-patch+json 1205 Res: 2.04 Changed 1206 Req: GET /rd/4521 1208 Res: 2.01 Content 1209 Payload: 1210 ;ct=41;rt="temperature", 1211 ;ct=41;rt="light-lux";if="sensor", 1212 ;ct=41;rt="humid-s";if="sensor" 1214 The following example shows an EP modifying all links at the example 1215 location /rd/4521 which are identified by href="/sensors/temp", from 1216 the initial link-value of ;rt="temperature" to the new 1217 link-value ;rt="temperature-c";if="sensor" by changing 1218 the value of the link attribute "rt" and adding the link attribute 1219 if="sensor" using the PATCH operation with the supplied merge- 1220 patch+json document payload. 1222 Req: PATCH /rd/4521?href=/sensors/temp 1224 Payload: 1225 {"rt": "temperature-c", "if": "sensor"}, 1227 Content-Format: 1228 application/merge-patch+json 1230 Res: 2.04 Changed 1232 Req: GET /rd/4521 1234 Res: 2.01 Content 1235 Payload: 1236 ;ct=41;rt="temperature-c";if="sensor", 1237 ;ct=41;rt="light-lux";if="sensor", 1238 ;ct=41;rt="humid-s";if="sensor" 1240 This example shows an EP removing all links at the example location 1241 /rd/4521 which are identified by href="/sensors/light". 1243 Req: PATCH /rd/4521?href=/sensors/light 1245 Payload: 1246 {} 1248 Content-Format: 1249 application/merge-patch+json 1251 Res: 2.04 Changed 1252 Req: GET /rd/4521 1254 Res: 2.01 Content 1255 Payload: 1256 ;ct=41;rt="temperature-c";if="sensor", 1257 ;ct=41;rt="humid-s";if="sensor" 1259 6. RD Groups 1261 This section defines the REST API for the creation, management, and 1262 lookup of endpoints for group operations. Similar to endpoint 1263 registration entries in the RD, groups may be created or removed. 1264 However unlike an endpoint entry, a group entry consists of a list of 1265 endpoints and does not have a lifetime associated with it. In order 1266 to make use of multicast requests with CoAP, a group MAY have a 1267 multicast address associated with it. 1269 6.1. Register a Group 1271 In order to create a group, a commissioning tool (CT) used to 1272 configure groups, makes a request to the RD indicating the name of 1273 the group to create (or update), optionally the domain the group 1274 belongs to, and optionally the multicast address of the group. The 1275 registration message includes the list of endpoints that belong to 1276 that group. 1278 All the endpoints in the group MUST be registered with the RD before 1279 registering a group. If an endpoint is not yet registered to the RD 1280 before registering the group, the registration message returns an 1281 error. The RD sends a blank target URI for every endpoint link when 1282 registering the group. 1284 Configuration of the endpoints themselves is out of scope of this 1285 specification. Such an interface for managing the group membership 1286 of an endpoint has been defined in [RFC7390]. 1288 The registration request interface is specified as follows: 1290 Interaction: CT -> RD 1292 Method: POST 1294 URI Template: {+rd-group}{?gp,d,con} 1296 URI Template Variables: 1298 rd-group := RD Group URI (mandatory). This is the location of 1299 the RD Group REST API. 1301 gp := Group Name (mandatory). The name of the group to be 1302 created or replaced, unique within that domain. The maximum 1303 length of this parameter is 63 bytes. 1305 d := Domain (optional). The domain to which this group belongs. 1306 The maximum length of this parameter is 63 bytes. Optional. 1307 When this parameter is elided, the RD MAY associate the 1308 endpoint with a configured default domain. 1310 con := Context (optional). This parameter sets the scheme, 1311 address and port at which this server is available in the form 1312 scheme://host:port/path. In the absence of this parameter the 1313 scheme of the protocol, source address and source port of the 1314 register request are assumed. This parameter is mandatory when 1315 the directory is filled by a third party such as an 1316 commissioning tool. When con is used, scheme and host are 1317 mandatory and port and path parameters are optional. 1319 Content-Format: application/link-format 1321 Content-Format: application/link-format+json 1323 Content-Format: application/link-format+cbor 1325 The following response codes are defined for this interface: 1327 Success: 2.01 "Created" or 201 "Created". The Location header 1328 option MUST be returned in response to a successful group CREATE 1329 operation. This Location MUST be a stable identifier generated by 1330 the RD as it is used for delete operations of the group 1331 registration resource. 1333 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1334 request. 1336 Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not 1337 registered in the RD (e.g. may have expired). 1339 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1340 Service could not perform the operation. 1342 HTTP support: YES 1344 The following example shows an EP registering a group with the name 1345 "lights" which has two endpoints to an RD using this interface. The 1346 RD group path /rd-group is an example RD location discovered in a 1347 request similar to Figure 4. 1349 Req: POST coap://rd.example.com/rd-group?gp=lights 1350 Content-Format: 40 1351 Payload: 1352 <>;ep="node1", 1353 <>;ep="node2" 1355 Res: 2.01 Created 1356 Location: /rd-group/12 1358 6.2. Group Removal 1360 A group can be removed simply by sending a removal message to the 1361 location of the group registration resource which was returned when 1362 intially registering the group. Removing a group MUST NOT remove the 1363 endpoints of the group from the RD. 1365 The removal request interface is specified as follows: 1367 Interaction: CT -> RD 1369 Method: DELETE 1371 URI Template: {+location} 1373 URI Template Variables: 1375 location := This is the Location returned by the RD as a result 1376 of a successful group registration. 1378 The following responses codes are defined for this interface: 1380 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1382 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1383 request. 1385 Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. 1387 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1388 Service could not perform the operation. 1390 HTTP support: YES 1392 The following examples shows successful removal of the group from the 1393 RD with the example location value /rd-group/12. 1395 Req: DELETE /rd-group/12 1397 Res: 2.02 Deleted 1399 7. RD Lookup 1401 In order for an RD to be used for discovering resources registered 1402 with it, an optional lookup interface may be provided. This lookup 1403 interface is defined as a default, and it is assumed that RDs may 1404 also support lookups to return resource descriptions in alternative 1405 formats (e.g. Atom or HTML Link) or using more advanced interfaces 1406 (e.g. supporting context or semantic based lookup). 1408 RD Lookup allows lookups for domains, groups, endpoints and resources 1409 using attributes defined in this document and for use with the CoRE 1410 Link Format. The result of a lookup request is the list of links (if 1411 any) corresponding to the type of lookup. Thus, a domain lookup MUST 1412 return a list of domains, a group lookup MUST return a list of 1413 groups, an endpoint lookup MUST return a list of endpoints and a 1414 resource lookup MUST return a list of links to resources. 1416 RD Lookup does not expose registration resources directly, but 1417 returns link content from registration resource entries which satisfy 1418 RD Lookup queries. 1420 The lookup type is selected by a URI endpoint, which is indicated by 1421 a Resource Type as per Table 1 below: 1423 +-------------+--------------------+-----------+ 1424 | Lookup Type | Resource Type | Mandatory | 1425 +-------------+--------------------+-----------+ 1426 | Resource | core.rd-lookup-res | Mandatory | 1427 | Endpoint | core.rd-lookup-ep | Mandatory | 1428 | Domain | core.rd-lookup-d | Optional | 1429 | Group | core.rd-lookup-gp | Optional | 1430 +-------------+--------------------+-----------+ 1432 Table 1: Lookup Types 1434 Each endpoint and resource lookup result returns respectively the 1435 scheme (IP address and port) followed by the path part of the URI of 1436 every endpoint and resource inside angle brackets ("<>") and followed 1437 by the other parameters. 1439 The target of these links SHOULD be the actual location of the 1440 domain, endpoint or resource, but MAY be an intermediate proxy e.g. 1441 in the case of an HTTP lookup interface for CoAP endpoints. 1443 The domain lookup returns every lookup domain with a base RD resource 1444 value (e.g. "/rd") encapsulated within angle brackets. 1446 In case that a group does not implement any multicast address, the 1447 group lookup returns every group lookup with a group base resource 1448 value encapsulated within angle brackets (e.g. "/rd/look-up"). 1449 Otherwise, the group lookup returns the multicast address of the 1450 group inside angle brackets. 1452 Using the Accept Option, the requester can control whether this list 1453 is returned in CoRE Link Format ("application/link-format", default) 1454 or its alternate content-formats ("application/link-format+json" or 1455 "application/link-format+cbor"). 1457 The page and count parameters are used to obtain lookup results in 1458 specified increments using pagination, where count specifies how many 1459 links to return and page specifies which subset of links organized in 1460 sequential pages, each containing 'count' links, starting with link 1461 zero and page zero. Thus, specifying count of 10 and page of 0 will 1462 return the first 10 links in the result set (links 0-9). Count = 10 1463 and page = 1 will return the next 'page' containing links 10-19, and 1464 so on. 1466 Multiple query parameters MAY be included in a lookup, all included 1467 parameters MUST match for a resource to be returned. The 1468 character'*' MAY be included at the end of a parameter value as a 1469 wildcard operator. 1471 RD Lookup requests MAY use any set of query parameters to match the 1472 registered attributes and relations. In addition, this interface MAY 1473 be used with queries that specify domains, endpoints, and groups. 1474 For example, a domain lookup filtering on groups would return a list 1475 of domains that contain the specified groups. An endpoint lookup 1476 filtering on groups would return a list of endpoints that are in the 1477 specified groups. 1479 Clients that are interested in a lookup result repeatedly or 1480 continuously can use mechanisms like ETag caching, resource 1481 observation ([RFC7641]), or any future mechanism that might allow 1482 more efficient observations of collections. These are advertised, 1483 detected and used according to their own specifications and can be 1484 used with the lookup interface as with any other resource. 1486 The lookup interface is specified as follows: 1488 Interaction: Client -> RD 1490 Method: GET 1491 URI Template: {+type-lookup- 1492 location}{?d,res,ep,gp,et,rt,page,count,resource-param} 1494 URI Template Variables: 1496 type-lookup-location := RD Lookup URI for a given lookup type 1497 (mandatory). The address is discovered as described in 1498 Section 5.2. 1500 ep := Endpoint name (optional). Used for endpoint, group and 1501 resource lookups. 1503 d := Domain (optional). Used for domain, group, endpoint and 1504 resource lookups. 1506 res := resource (optional). Used for domain, group, endpoint and 1507 resource lookups. 1509 gp := Group name (optional). Used for endpoint, group and 1510 resource lookups. 1512 page := Page (optional). Parameter can not be used without the 1513 count parameter. Results are returned from result set in pages 1514 that contain 'count' links starting from index (page * count). 1515 Page numbering starts with zero. 1517 count := Count (optional). Number of results is limited to this 1518 parameter value. If the page parameter is also present, the 1519 response MUST only include 'count' links starting with the 1520 (page * count) link in the result set from the query. If the 1521 count parameter is not present, then the response MUST return 1522 all matching links in the result set. Link numbering starts 1523 with zero. 1525 rt := Resource type (optional). Used for group, endpoint and 1526 resource lookups. 1528 et := Endpoint type (optional). Used for group, endpoint and 1529 resource lookups. 1531 resource-param := Link attribute parameters (optional). Any link 1532 target attribute as defined in Section 4.1 of [RFC6690], used 1533 for resource lookups. 1535 Content-Format: application/link-format (optional) 1537 Content-Format: application/link-format+json (optional) 1538 Content-Format: application/link-format+cbor (optional) 1540 The following responses codes are defined for this interface: 1542 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1543 format", "application/link-format+cbor", or "application/link- 1544 format+json" payload containing matching entries for the lookup. 1546 Failure: 4.04 "Not Found" or 404 "Not Found" in case no matching 1547 entry is found for a unicast request. 1549 Failure: No error response to a multicast request. 1551 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1552 request. 1554 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1555 Service could not perform the operation. 1557 HTTP support: YES 1559 The examples in this section assume CoAP hosts with a default CoAP 1560 port 61616. HTTP hosts are possible and do not change the nature of 1561 the examples. 1563 The following example shows a client performing a resource lookup 1564 with the example resource look-up locations discovered in Figure 4: 1566 Req: GET /rd-lookup/res?rt=temperature 1568 Res: 2.05 Content 1569 ;rt="temperature" 1571 The following example shows a client performing an endpoint type 1572 lookup: 1574 Req: GET /rd-lookup/ep?et=power-node 1576 Res: 2.05 Content 1577 ;ep="node5", 1578 ;ep="node7" 1580 The following example shows a client performing a domain lookup: 1582 Req: GET /rd-lookup/d 1584 Res: 2.05 Content 1585 <>;d="domain1", 1586 <>;d="domain2" 1588 The following example shows a client performing a group lookup for 1589 all groups: 1591 Req: GET /rd-lookup/gp 1593 Res: 2.05 Content 1594 <>;gp="lights1";d="example.com" 1595 <>;gp="lights2";d="ecample.com" 1597 The following example shows a client performing a lookup for all 1598 endpoints in a particular group: 1600 Req: GET /rd-lookup/ep?gp=lights1 1602 Res: 2.05 Content 1603 ;ep="node1", 1604 ;ep="node2" 1606 The following example shows a client performing a lookup for all 1607 groups an endpoint belongs to: 1609 Req: GET /rd-lookup/gp?ep=node1 1611 Res: 2.05 Content 1612 <>;gp="lights1" 1614 The following example shows a client performing a paginated lookup 1615 Req: GET /rd-lookup/res?page=0&count=5 1617 Res: 2.05 Content 1618 ;rt=sensor;ct=60 1619 ;rt=sensor;ct=60 1620 ;rt=sensor;ct=60 1621 ;rt=sensor;ct=60 1622 ;rt=sensor;ct=60 1624 Req: GET /rd-lookup/res?page=1&count=5 1626 Res: 2.05 Content 1627 ;rt=sensor;ct=60 1628 ;rt=sensor;ct=60 1629 ;rt=sensor;ct=60 1630 ;rt=sensor;ct=60 1631 ;rt=sensor;ct=60 1633 8. Security Considerations 1635 The security considerations as described in Section 7 of [RFC5988] 1636 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1637 may be protected e.g. using DTLS when hosted on a CoAP server as 1638 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1639 all resource directory interfaces defined in this document. 1641 8.1. Endpoint Identification and Authentication 1643 An Endpoint is determined to be unique by an RD by the Endpoint 1644 identifier parameter included during Registration, and any associated 1645 TLS or DTLS security bindings. An Endpoint MUST NOT be identified by 1646 its protocol, port or IP address as these may change over the 1647 lifetime of an Endpoint. 1649 Every operation performed by an Endpoint or Client on a resource 1650 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1651 Public Key or Certificate based security. Endpoints using a 1652 Certificate MUST include the Endpoint identifier as the Subject of 1653 the Certificate, and this identifier MUST be checked by a resource 1654 directory to match the Endpoint identifier included in the 1655 Registration message. 1657 8.2. Access Control 1659 Access control SHOULD be performed separately for the RD 1660 registration, Lookup, and group API paths, as different endpoints may 1661 be authorized to register with an RD from those authorized to lookup 1662 endpoints from the RD. Such access control SHOULD be performed in as 1663 fine-grained a level as possible. For example access control for 1664 lookups could be performed either at the domain, endpoint or resource 1665 level. 1667 8.3. Denial of Service Attacks 1669 Services that run over UDP unprotected are vulnerable to unknowingly 1670 become part of a DDoS attack as UDP does not require return 1671 routability check. Therefore, an attacker can easily spoof the 1672 source IP of the target entity and send requests to such a service 1673 which would then respond to the target entity. This can be used for 1674 large-scale DDoS attacks on the target. Especially, if the service 1675 returns a response that is order of magnitudes larger than the 1676 request, the situation becomes even worse as now the attack can be 1677 amplified. DNS servers have been widely used for DDoS amplification 1678 attacks. There is also a danger that NTP Servers could become 1679 implicated in denial-of-service (DoS) attacks since they run on 1680 unprotected UDP, there is no return routability check, and they can 1681 have a large amplification factor. The responses from the NTP server 1682 were found to be 19 times larger than the request. A Resource 1683 Directory (RD) which responds to wild-card lookups is potentially 1684 vulnerable if run with CoAP over UDP. Since there is no return 1685 routability check and the responses can be significantly larger than 1686 requests, RDs can unknowingly become part of a DDoS amplification 1687 attack. 1689 9. IANA Considerations 1691 9.1. Resource Types 1693 "core.rd", "core.rd-group", "core.rd-lookup-ep", "core.rd-lookup- 1694 res", "core.rd-lookup-d", and "core.rd-lookup-gp" resource types need 1695 to be registered with the resource type registry defined by 1696 [RFC6690]. 1698 9.2. IPv6 ND Resource Directory Address Option 1700 This document registers one new ND option type under the subregistry 1701 "IPv6 Neighbor Discovery Option Formats": 1703 o Resource Directory address Option (38) 1705 9.3. RD Parameter Registry 1707 This specification defines a new sub-registry for registration and 1708 lookup parameters called "RD Parameters" under "CoRE Parameters". 1709 Although this specification defines a basic set of parameters, it is 1710 expected that other standards that make use of this interface will 1711 define new ones. 1713 Each entry in the registry must include the human readable name of 1714 the parameter, the query parameter, validity requirements if any and 1715 a description. The query parameter MUST be a valid URI query key 1716 [RFC3986]. 1718 Initial entries in this sub-registry are as follows: 1720 +----------+-------+---------------+--------------------------------+ 1721 | Name | Query | Validity | Description | 1722 +----------+-------+---------------+--------------------------------+ 1723 | Endpoint | ep | | Name of the endpoint, max 63 | 1724 | Name | | | bytes | 1725 | Lifetime | lt | 60-4294967295 | Lifetime of the registration | 1726 | | | | in seconds | 1727 | Domain | d | | Domain to which this endpoint | 1728 | | | | belongs | 1729 | Endpoint | et | | Semantic name of the endpoint | 1730 | Type | | | | 1731 | Context | con | URI | The scheme, address and port | 1732 | | | | and path at which this server | 1733 | | | | is available | 1734 | Resource | res | | Name of the resource | 1735 | Name | | | | 1736 | Group | gp | | Name of a group in the RD | 1737 | Name | | | | 1738 | Page | page | Integer | Used for pagination | 1739 | Count | count | Integer | Used for pagination | 1740 +----------+-------+---------------+--------------------------------+ 1742 Table 2: RD Parameters 1744 The IANA policy for future additions to the sub-registry is "Expert 1745 Review" as described in [RFC5226]. 1747 10. Examples 1749 Two examples are presented: a Lighting Installation example in 1750 Section 10.1 and a LWM2M example in Section 10.2. 1752 10.1. Lighting Installation 1754 This example shows a simplified lighting installation which makes use 1755 of the Resource Directory (RD) with a CoAP interface to facilitate 1756 the installation and start up of the application code in the lights 1757 and sensors. In particular, the example leads to the definition of a 1758 group and the enabling of the corresponding multicast address. No 1759 conclusions must be drawn on the realization of actual installation 1760 or naming procedures, because the example only "emphasizes" some of 1761 the issues that may influence the use of the RD and does not pretend 1762 to be normative. 1764 10.1.1. Installation Characteristics 1766 The example assumes that the installation is managed. That means 1767 that a Commissioning Tool (CT) is used to authorize the addition of 1768 nodes, name them, and name their services. The CT can be connected 1769 to the installation in many ways: the CT can be part of the 1770 installation network, connected by WiFi to the installation network, 1771 or connected via GPRS link, or other method. 1773 It is assumed that there are two naming authorities for the 1774 installation: (1) the network manager that is responsible for the 1775 correct operation of the network and the connected interfaces, and 1776 (2) the lighting manager that is responsible for the correct 1777 functioning of networked lights and sensors. The result is the 1778 existence of two naming schemes coming from the two managing 1779 entities. 1781 The example installation consists of one presence sensor, and two 1782 luminaries, luminary1 and luminary2, each with their own wireless 1783 interface. Each luminary contains three lamps: left, right and 1784 middle. Each luminary is accessible through one endpoint. For each 1785 lamp a resource exists to modify the settings of a lamp in a 1786 luminary. The purpose of the installation is that the presence 1787 sensor notifies the presence of persons to a group of lamps. The 1788 group of lamps consists of: middle and left lamps of luminary1 and 1789 right lamp of luminary2. 1791 Before commissioning by the lighting manager, the network is 1792 installed and access to the interfaces is proven to work by the 1793 network manager. 1795 At the moment of installation, the network under installation is not 1796 necessarily connected to the DNS infra structure. Therefore, SLAAC 1797 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 1798 Table 3 below: 1800 +--------------------+--------------+ 1801 | Name | IPv6 address | 1802 +--------------------+--------------+ 1803 | luminary1 | FDFD::ABCD:1 | 1804 | luminary2 | FDFD::ABCD:2 | 1805 | Presence sensor | FDFD::ABCD:3 | 1806 | Resource directory | FDFD::ABCD:0 | 1807 +--------------------+--------------+ 1809 Table 3: interface SLAAC addresses 1811 In Section 10.1.2 the use of resource directory during installation 1812 is presented. 1814 10.1.2. RD entries 1816 It is assumed that access to the DNS infrastructure is not always 1817 possible during installation. Therefore, the SLAAC addresses are 1818 used in this section. 1820 For discovery, the resource types (rt) of the devices are important. 1821 The lamps in the luminaries have rt: light, and the presence sensor 1822 has rt: p-sensor. The endpoints have names which are relevant to the 1823 light installation manager. In this case luminary1, luminary2, and 1824 the presence sensor are located in room 2-4-015, where luminary1 is 1825 located at the window and luminary2 and the presence sensor are 1826 located at the door. The endpoint names reflect this physical 1827 location. The middle, left and right lamps are accessed via path 1828 /light/middle, /light/left, and /light/right respectively. The 1829 identifiers relevant to the Resource Directory are shown in Table 4 1830 below: 1832 +----------------+------------------+---------------+---------------+ 1833 | Name | endpoint | resource path | resource type | 1834 +----------------+------------------+---------------+---------------+ 1835 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 1836 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 1837 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 1838 | luminary2 | lm_R2-4-015_door | /light/left | light | 1839 | luminary2 | lm_R2-4-015_door | /light/middle | light | 1840 | luminary2 | lm_R2-4-015_door | /light/right | light | 1841 | Presence | ps_R2-4-015_door | /ps | p-sensor | 1842 | sensor | | | | 1843 +----------------+------------------+---------------+---------------+ 1845 Table 4: Resource Directory identifiers 1847 It is assumed that the CT knows of the RD's address, and has 1848 performed URI discovery on it that gave a response like the one in 1849 the Section 5.2 example. 1851 The CT inserts the endpoints of the luminaries and the sensor in the 1852 RD using the Context parameter (con) to specify the interface 1853 address: 1855 Req: POST coap://[FDFD::ABCD:0]/rd 1856 ?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1]&d=R2-4-015 1857 Payload: 1858 ;rt="light", 1859 ;rt="light", 1860 ;rt="light" 1862 Res: 2.01 Created 1863 Location: /rd/4521 1865 Req: POST coap://[FDFD::ABCD:0]/rd 1866 ?ep=lm_R2-4-015_door&con=coap://[FDFD::ABCD:2]&d=R2-4-015 1867 Payload: 1868 ;rt="light", 1869 ;rt="light", 1870 ;rt="light" 1872 Res: 2.01 Created 1873 Location: /rd/4522 1875 Req: POST coap://[FDFD::ABCD:0]/rd 1876 ?ep=ps_R2-4-015_door&con=coap://[FDFD::ABCD:3]d&d=R2-4-015 1877 Payload: 1878 ;rt="p-sensor" 1880 Res: 2.01 Created 1881 Location: /rd/4523 1883 The domain name d=R2-4-015 has been added for an efficient lookup 1884 because filtering on "ep" name is more awkward. The same domain name 1885 is communicated to the two luminaries and the presence sensor by the 1886 CT. 1888 The group is specified in the RD. The Context parameter is set to 1889 the site-local multicast address allocated to the group. In the POST 1890 in the example below, these two endpoints and the endpoint of the 1891 presence sensor are registered as members of the group. 1893 Req: POST coap://[FDFD::ABCD:0]/rd-group 1894 ?gp=grp_R2-4-015&con=coap://[FF05::1] 1895 Payload: 1896 <>;ep=lm_R2-4-015_wndw, 1897 <>;ep=lm_R2-4-015_door, 1898 <>;ep=ps_R2-4-015_door 1900 Res: 2.01 Created 1901 Location: /rd-group/501 1903 After the filling of the RD by the CT, the application in the 1904 luminaries can learn to which groups they belong, and enable their 1905 interface for the multicast address. 1907 The luminary, knowing its domain, queries the RD for the endpoint 1908 with rt=light and d=R2-4-015. The RD returns all endpoints in the 1909 domain. 1911 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep 1912 ?d=R2-4-015;rt=light 1914 Res: 2.05 Content 1915 ; 1916 ep="lm_R2-4-015_wndw", 1917 ; 1918 ep="lm_R2-4-015_door" 1920 Knowing its own IPv6 address, the luminary discovers its endpoint 1921 name. With the endpoint name the luminary queries the RD for all 1922 groups to which the endpoint belongs. 1924 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/gp 1925 ?ep=lm_R2-4-015_wndw 1927 Res: 2.05 Content 1928 ;gp="grp_R2-4-015" 1930 From the context parameter value, the luminary learns the multicast 1931 address of the multicast group. 1933 Alternatively, the CT can communicate the multicast address directly 1934 to the luminaries by using the "coap-group" resource specified in 1935 [RFC7390]. 1937 Req: POST //[FDFD::ABCD:1]/coap-group 1938 Content-Format: application/coap-group+json 1939 { "a": "[FF05::1]", 1940 "n": "grp_R2-4-015"} 1942 Res: 2.01 Created 1943 Location-Path: /coap-group/1 1945 Dependent on the situation, only the address, "a", or the name, "n", 1946 is specified in the coap-group resource. 1948 10.2. OMA Lightweight M2M (LWM2M) Example 1950 This example shows how the OMA LWM2M specification makes use of 1951 Resource Directory (RD). 1953 OMA LWM2M is a profile for device services based on CoAP(OMA Name 1954 Authority). LWM2M defines a simple object model and a number of 1955 abstract interfaces and operations for device management and device 1956 service enablement. 1958 An LWM2M server is an instance of an LWM2M middleware service layer, 1959 containing a Resource Directory along with other LWM2M interfaces 1960 defined by the LWM2M specification. 1962 CoRE Resource Directory (RD) is used to provide the LWM2M 1963 Registration interface. 1965 LWM2M does not provide for registration domains and does not 1966 currently use the rd-group or rd-lookup interfaces. 1968 The LWM2M specification describes a set of interfaces and a resource 1969 model used between a LWM2M device and an LWM2M server. Other 1970 interfaces, proxies, and applications are currently out of scope for 1971 LWM2M. 1973 The location of the LWM2M Server and RD URI path is provided by the 1974 LWM2M Bootstrap process, so no dynamic discovery of the RD is used. 1975 LWM2M Servers and endpoints are not required to implement the /.well- 1976 known/core resource. 1978 10.2.1. The LWM2M Object Model 1980 The OMA LWM2M object model is based on a simple 2 level class 1981 hierarchy consisting of Objects and Resources. 1983 An LWM2M Resource is a REST endpoint, allowed to be a single value or 1984 an array of values of the same data type. 1986 An LWM2M Object is a resource template and container type that 1987 encapsulates a set of related resources. An LWM2M Object represents 1988 a specific type of information source; for example, there is a LWM2M 1989 Device Management object that represents a network connection, 1990 containing resources that represent individual properties like radio 1991 signal strength. 1993 Since there may potentially be more than one of a given type object, 1994 for example more than one network connection, LWM2M defines instances 1995 of objects that contain the resources that represent a specific 1996 physical thing. 1998 The URI template for LWM2M consists of a base URI followed by Object, 1999 Instance, and Resource IDs: 2001 {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- 2002 instance} 2004 The five variables given here are strings. base-uri can also have 2005 the special value "undefined" (sometimes called "null" in RFC 6570). 2006 Each of the variables object-instance, resource-id, and resource- 2007 instance can be the special value "undefined" only if the values 2008 behind it in this sequence also are "undefined". As a special case, 2009 object-instance can be "empty" (which is different from "undefined") 2010 if resource-id is not "undefined". 2012 base-uri := Base URI for LWM2M resources or "undefined" for default 2013 (empty) base URI 2015 object-id := OMNA (OMA Name Authority) registered object ID (0-65535) 2017 object-instance := Object instance identifier (0-65535) or 2018 "undefined"/"empty" (see above)) to refer to all instances of an 2019 object ID 2021 resource-id := OMNA (OMA Name Authority) registered resource ID 2022 (0-65535) or "undefined" to refer to all resources within an instance 2024 resource-instance := Resource instance identifier or "undefined" to 2025 refer to single instance of a resource 2027 LWM2M IDs are 16 bit unsigned integers represented in decimal (no 2028 leading zeroes except for the value 0) by URI format strings. For 2029 example, a LWM2M URI might be: 2031 /1/0/1 2032 The base uri is empty, the Object ID is 1, the instance ID is 0, the 2033 resource ID is 1, and the resource instance is "undefined". This 2034 example URI points to internal resource 1, which represents the 2035 registration lifetime configured, in instance 0 of a type 1 object 2036 (LWM2M Server Object). 2038 10.2.2. LWM2M Register Endpoint 2040 LWM2M defines a registration interface based on the REST API, 2041 described in Section 5. The RD registration URI path of the LWM2M 2042 Resource Directory is specified to be "/rd". 2044 LWM2M endpoints register object IDs, for example , to indicate 2045 that a particular object type is supported, and register object 2046 instances, for example , to indicate that a particular instance 2047 of that object type exists. 2049 Resources within the LWM2M object instance are not registered with 2050 the RD, but may be discovered by reading the resource links from the 2051 object instance using GET with a CoAP Content-Format of application/ 2052 link-format. Resources may also be read as a structured object by 2053 performing a GET to the object instance with a Content-Format of 2054 senml+json. 2056 When an LWM2M object or instance is registered, this indicates to the 2057 LWM2M server that the object and its resources are available for 2058 management and service enablement (REST API) operations. 2060 LWM2M endpoints may use the following RD registration parameters as 2061 defined in Table 2 : 2063 ep - Endpoint Name 2064 lt - registration lifetime 2066 Endpoint Name is mandatory, all other registration parameters are 2067 optional. 2069 Additional optional LWM2M registration parameters are defined: 2071 +------------+-------+-------------------------------+--------------+ 2072 | Name | Query | Validity | Description | 2073 +------------+-------+-------------------------------+--------------+ 2074 | Protocol | b | {"U",UQ","S","SQ","US","UQS"} | Available | 2075 | Binding | | | Protocols | 2076 | | | | | 2077 | LWM2M | ver | 1.0 | Spec Version | 2078 | Version | | | | 2079 | | | | | 2080 | SMS Number | sms | | MSISDN | 2081 +------------+-------+-------------------------------+--------------+ 2083 Table 5: LWM2M Additional Registration Parameters 2085 The following RD registration parameters are not currently specified 2086 for use in LWM2M: 2088 et - Endpoint Type 2089 con - Context 2091 The endpoint registration must include a payload containing links to 2092 all supported objects and existing object instances, optionally 2093 including the appropriate link-format relations. 2095 Here is an example LWM2M registration payload: 2097 ,,, 2099 This link format payload indicates that object ID 1 (LWM2M Server 2100 Object) is supported, with a single instance 0 existing, object ID 3 2101 (LWM2M Device object) is supported, with a single instance 0 2102 existing, and object 5 (LWM2M Firmware Object) is supported, with no 2103 existing instances. 2105 10.2.3. LWM2M Update Endpoint Registration 2107 An LWM2M Registration update proceeds as described in Section 5.4.1, 2108 and adds some optional parameter updates: 2110 lt - Registration Lifetime 2111 b - Protocol Binding 2112 sms - MSISDN 2113 link payload - new or modified links 2115 A Registration update is also specified to be used to update the 2116 LWM2M server whenever the endpoint's UDP port or IP address are 2117 changed. 2119 10.2.4. LWM2M De-Register Endpoint 2121 LWM2M allows for de-registration using the delete method on the 2122 returned location from the initial registration operation. LWM2M de- 2123 registration proceeds as described in Section 5.4.2. 2125 11. Acknowledgments 2127 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2128 Brandt, Matthieu Vial, Mohit Sethi, Sampo Ukkola, Linyi Tian, 2129 Chistian Amsuss, and Jan Newmarch have provided helpful comments, 2130 discussions and ideas to improve and shape this document. Zach would 2131 also like to thank his colleagues from the EU FP7 SENSEI project, 2132 where many of the resource directory concepts were originally 2133 developed. 2135 12. Changelog 2137 changes from -09 to -10 2139 o removed "ins" and "exp" link-format extensions. 2141 o removed all text concerning DNS-SD. 2143 o removed inconsistency in RDAO text. 2145 o suggestions taken over from various sources 2147 o replaced "Function Set" with "REST API", "base URI", "base path" 2149 o moved simple registration to registration section 2151 changes from -08 to -09 2153 o clarified the "example use" of the base RD resource values /rd, 2154 /rd-lookup, and /rd-group. 2156 o changed "ins" ABNF notation. 2158 o various editorial improvements, including in examples 2160 o clarifications for RDAO 2162 changes from -07 to -08 2164 o removed link target value returned from domain and group lookup 2165 types 2167 o Maximum length of domain parameter 63 bytes for consistency with 2168 group 2170 o removed option for simple POST of link data, don't require a 2171 .well-known/core resource to accept POST data and handle it in a 2172 special way; we already have /rd for that 2174 o add IPv6 ND Option for discovery of an RD 2176 o clarify group configuration section 6.1 that endpoints must be 2177 registered before including them in a group 2179 o removed all superfluous client-server diagrams 2181 o simplified lighting example 2183 o introduced Commissioning Tool 2185 o RD-Look-up text is extended. 2187 changes from -06 to -07 2189 o added text in the discovery section to allow content format hints 2190 to be exposed in the discovery link attributes 2192 o editorial updates to section 9 2194 o update author information 2196 o minor text corrections 2198 Changes from -05 to -06 2200 o added note that the PATCH section is contingent on the progress of 2201 the PATCH method 2203 changes from -04 to -05 2205 o added Update Endpoint Links using PATCH 2207 o http access made explicit in interface specification 2209 o Added http examples 2211 Changes from -03 to -04: 2213 o Added http response codes 2214 o Clarified endpoint name usage 2216 o Add application/link-format+cbor content-format 2218 Changes from -02 to -03: 2220 o Added an example for lighting and DNS integration 2222 o Added an example for RD use in OMA LWM2M 2224 o Added Read Links operation for link inspection by endpoints 2226 o Expanded DNS-SD section 2228 o Added draft authors Peter van der Stok and Michael Koster 2230 Changes from -01 to -02: 2232 o Added a catalogue use case. 2234 o Changed the registration update to a POST with optional link 2235 format payload. Removed the endpoint type update from the update. 2237 o Additional examples section added for more complex use cases. 2239 o New DNS-SD mapping section. 2241 o Added text on endpoint identification and authentication. 2243 o Error code 4.04 added to Registration Update and Delete requests. 2245 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 2246 resource type parameters. 2248 Changes from -00 to -01: 2250 o Removed the ETag validation feature. 2252 o Place holder for the DNS-SD mapping section. 2254 o Explicitly disabled GET or POST on returned Location. 2256 o New registry for RD parameters. 2258 o Added support for the JSON Link Format. 2260 o Added reference to the Groupcomm WG draft. 2262 Changes from -05 to WG Document -00: 2264 o Updated the version and date. 2266 Changes from -04 to -05: 2268 o Restricted Update to parameter updates. 2270 o Added pagination support for the Lookup interface. 2272 o Minor editing, bug fixes and reference updates. 2274 o Added group support. 2276 o Changed rt to et for the registration and update interface. 2278 Changes from -03 to -04: 2280 o Added the ins= parameter back for the DNS-SD mapping. 2282 o Integrated the Simple Directory Discovery from Carsten. 2284 o Editorial improvements. 2286 o Fixed the use of ETags. 2288 o Fixed tickets 383 and 372 2290 Changes from -02 to -03: 2292 o Changed the endpoint name back to a single registration parameter 2293 ep= and removed the h= and ins= parameters. 2295 o Updated REST interface descriptions to use RFC6570 URI Template 2296 format. 2298 o Introduced an improved RD Lookup design as its own function set. 2300 o Improved the security considerations section. 2302 o Made the POST registration interface idempotent by requiring the 2303 ep= parameter to be present. 2305 Changes from -01 to -02: 2307 o Added a terminology section. 2309 o Changed the inclusion of an ETag in registration or update to a 2310 MAY. 2312 o Added the concept of an RD Domain and a registration parameter for 2313 it. 2315 o Recommended the Location returned from a registration to be 2316 stable, allowing for endpoint and Domain information to be changed 2317 during updates. 2319 o Changed the lookup interface to accept endpoint and Domain as 2320 query string parameters to control the scope of a lookup. 2322 13. References 2324 13.1. Normative References 2326 [I-D.ietf-core-links-json] 2327 Li, K., Rahman, A., and C. Bormann, "Representing 2328 Constrained RESTful Environments (CoRE) Link Format in 2329 JSON and CBOR", draft-ietf-core-links-json-08 (work in 2330 progress), April 2017. 2332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2333 Requirement Levels", BCP 14, RFC 2119, 2334 DOI 10.17487/RFC2119, March 1997, 2335 . 2337 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2338 Resource Identifier (URI): Generic Syntax", STD 66, 2339 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2340 . 2342 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2343 IANA Considerations Section in RFCs", RFC 5226, 2344 DOI 10.17487/RFC5226, May 2008, 2345 . 2347 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2348 DOI 10.17487/RFC5988, October 2010, 2349 . 2351 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2352 and D. Orchard, "URI Template", RFC 6570, 2353 DOI 10.17487/RFC6570, March 2012, 2354 . 2356 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2357 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2358 . 2360 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 2361 DOI 10.17487/RFC7396, October 2014, 2362 . 2364 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2365 FETCH Methods for the Constrained Application Protocol 2366 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2367 . 2369 13.2. Informative References 2371 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2372 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2373 Transfer Protocol -- HTTP/1.1", RFC 2616, 2374 DOI 10.17487/RFC2616, June 1999, 2375 . 2377 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 2378 Bormann, "Neighbor Discovery Optimization for IPv6 over 2379 Low-Power Wireless Personal Area Networks (6LoWPANs)", 2380 RFC 6775, DOI 10.17487/RFC6775, November 2012, 2381 . 2383 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2384 Protocol (HTTP/1.1): Message Syntax and Routing", 2385 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2386 . 2388 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2389 Application Protocol (CoAP)", RFC 7252, 2390 DOI 10.17487/RFC7252, June 2014, 2391 . 2393 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2394 the Constrained Application Protocol (CoAP)", RFC 7390, 2395 DOI 10.17487/RFC7390, October 2014, 2396 . 2398 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2399 Application Protocol (CoAP)", RFC 7641, 2400 DOI 10.17487/RFC7641, September 2015, 2401 . 2403 Authors' Addresses 2405 Zach Shelby 2406 ARM 2407 150 Rose Orchard 2408 San Jose 95134 2409 USA 2411 Phone: +1-408-203-9434 2412 Email: zach.shelby@arm.com 2414 Michael Koster 2415 SmartThings 2416 665 Clyde Avenue 2417 Mountain View 94043 2418 USA 2420 Phone: +1-707-502-5136 2421 Email: Michael.Koster@smartthings.com 2423 Carsten Bormann 2424 Universitaet Bremen TZI 2425 Postfach 330440 2426 Bremen D-28359 2427 Germany 2429 Phone: +49-421-218-63921 2430 Email: cabo@tzi.org 2432 Peter van der Stok 2433 consultant 2435 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2436 Email: consultancy@vanderstok.org 2437 URI: www.vanderstok.org 2439 Christian Amsuess (editor) 2440 Energy Harvesting Solutions 2441 Hollandstr. 12/4 2442 1020 2443 Austria 2445 Phone: +43-664-9790639 2446 Email: c.amsuess@energyharvesting.at