idnits 2.17.1 draft-ietf-core-resource-directory-13.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 : ---------------------------------------------------------------------------- ** There are 11 instances of too long lines in the document, the longest one being 22 characters in excess of 72. == There are 1 instance of lines with multicast IPv4 addresses in the document. If these are generic example addresses, they should be changed to use the 233.252.0.x range defined in RFC 5771 == There are 3 instances of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 369 has weird spacing: '... target o----...' == Line 371 has weird spacing: '...--o rel o...' == Line 440 has weird spacing: '... o con o----...' == Line 445 has weird spacing: '... o loc o---...' == Line 449 has weird spacing: '... o ep o---...' == (3 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The commissioning tool SHOULD not send any target attributes with the links to the registration resources, and the resource directory SHOULD reject registrations that contain links with unprocessable attributes. -- The document date (March 01, 2018) is 2246 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: 'I-D.arkko-core-dev-urn' is defined on line 2820, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 2835, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-02) exists of draft-bormann-t2trg-rel-impl-00 == Outdated reference: A later version (-09) exists of draft-silverajan-core-coap-protocol-negotiation-07 -- 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 (~~), 14 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: September 2, 2018 SmartThings 6 C. Bormann 7 Universitaet Bremen TZI 8 P. van der Stok 9 consultant 10 C. Amsuess, Ed. 11 March 01, 2018 13 CoRE Resource Directory 14 draft-ietf-core-resource-directory-13 16 Abstract 18 In many M2M applications, direct discovery of resources is not 19 practical due to sleeping nodes, disperse networks, or networks where 20 multicast traffic is inefficient. These problems can be solved by 21 employing an entity called a Resource Directory (RD), which hosts 22 descriptions of resources held on other servers, allowing lookups to 23 be performed for those resources. This document specifies the web 24 interfaces that a Resource Directory supports in order for web 25 servers to discover the RD and to register, maintain, lookup and 26 remove resource descriptions. Furthermore, new link attributes 27 useful in conjunction with an RD are defined. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on September 2, 2018. 46 Copyright Notice 48 Copyright (c) 2018 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 6 66 3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 6 67 3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 6 68 3.3. RD Content Model . . . . . . . . . . . . . . . . . . . . 8 69 3.4. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 12 70 3.5. Use Case: Home and Building Automation . . . . . . . . . 13 71 3.6. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 13 72 4. Finding a Resource Directory . . . . . . . . . . . . . . . . 14 73 4.1. Resource Directory Address Option (RDAO) . . . . . . . . 15 74 5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 17 75 5.1. Payload Content Formats . . . . . . . . . . . . . . . . . 18 76 5.2. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 18 77 5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 21 78 5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 25 79 5.3.2. Third-party registration . . . . . . . . . . . . . . 26 80 5.4. Operations on the Registration Resource . . . . . . . . . 26 81 5.4.1. Registration Update . . . . . . . . . . . . . . . . . 27 82 5.4.2. Registration Removal . . . . . . . . . . . . . . . . 30 83 5.4.3. Read Endpoint Links . . . . . . . . . . . . . . . . . 31 84 5.4.4. Update Endpoint Links . . . . . . . . . . . . . . . . 32 85 6. RD Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 32 86 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 32 87 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 34 88 7. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 35 89 7.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 36 90 7.2. Endpoint and group lookup . . . . . . . . . . . . . . . . 36 91 7.3. Lookup filtering . . . . . . . . . . . . . . . . . . . . 37 92 7.4. Lookup examples . . . . . . . . . . . . . . . . . . . . . 39 93 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 94 8.1. Endpoint Identification and Authentication . . . . . . . 43 95 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 44 96 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 44 97 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 98 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 45 99 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 45 100 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 45 101 9.3.1. Full description of the "Endpoint Type" Registration 102 Parameter . . . . . . . . . . . . . . . . . . . . . . 47 103 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 47 104 9.5. Multicast Address Registration . . . . . . . . . . . . . 48 105 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 48 106 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 48 107 10.1.1. Installation Characteristics . . . . . . . . . . . . 48 108 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 49 109 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 52 110 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 53 111 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 54 112 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 56 113 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 56 114 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 56 115 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 56 116 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 117 13.1. Normative References . . . . . . . . . . . . . . . . . . 62 118 13.2. Informative References . . . . . . . . . . . . . . . . . 63 119 Appendix A. Web links and the Resource Directory . . . . . . . . 64 120 A.1. A simple example . . . . . . . . . . . . . . . . . . . . 64 121 A.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 64 122 A.1.2. Interpreting attributes and relations . . . . . . . . 65 123 A.2. A slightly more complex example . . . . . . . . . . . . . 65 124 A.3. Enter the Resource Directory . . . . . . . . . . . . . . 66 125 A.4. A note on differences between link-format and Link 126 headers . . . . . . . . . . . . . . . . . . . . . . . . . 67 127 Appendix B. Syntax examples for Protocol Negotiation . . . . . . 68 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 130 1. Introduction 132 The work on Constrained RESTful Environments (CoRE) aims at realizing 133 the REST architecture in a suitable form for the most constrained 134 nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and 135 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 136 applications such as smart energy and building automation. 138 The discovery of resources offered by a constrained server is very 139 important in machine-to-machine applications where there are no 140 humans in the loop and static interfaces result in fragility. The 141 discovery of resources provided by an HTTP Web Server is typically 142 called Web Linking [RFC5988]. The use of Web Linking for the 143 description and discovery of resources hosted by constrained web 144 servers is specified by the CoRE Link Format [RFC6690]. However, 145 [RFC6690] only describes how to discover resources from the web 146 server that hosts them by querying "/.well-known/core". In many M2M 147 scenarios, direct discovery of resources is not practical due to 148 sleeping nodes, disperse networks, or networks where multicast 149 traffic is inefficient. These problems can be solved by employing an 150 entity called a Resource Directory (RD), which hosts descriptions of 151 resources held on other servers, allowing lookups to be performed for 152 those resources. 154 This document specifies the web interfaces that a Resource Directory 155 supports in order for web servers to discover the RD and to register, 156 maintain, lookup and remove resource descriptions. Furthermore, new 157 link attributes useful in conjunction with a Resource Directory are 158 defined. Although the examples in this document show the use of 159 these interfaces with CoAP [RFC7252], they can be applied in an 160 equivalent manner to HTTP [RFC7230]. 162 2. Terminology 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 166 "OPTIONAL" in this document are to be interpreted as described in 167 [RFC2119]. The term "byte" is used in its now customary sense as a 168 synonym for "octet". 170 This specification requires readers to be familiar with all the terms 171 and concepts that are discussed in [RFC3986], [RFC5988] and 172 [RFC6690]. Readers should also be familiar with the terms and 173 concepts discussed in [RFC7252]. To describe the REST interfaces 174 defined in this specification, the URI Template format is used 175 [RFC6570]. 177 This specification makes use of the following additional terminology: 179 resolve against 180 The expression "a URI-reference is _resolved against_ a base URI" 181 is used to describe the process of [RFC3986] Section 5.2. 182 Noteworthy corner cases are that resolving an absolute URI against 183 any base URI gives the original URI, and that resolving an empty 184 URI reference gives the base URI. 186 Resource Directory 187 A web entity that stores information about web resources and 188 implements the REST interfaces defined in this specification for 189 registration and lookup of those resources. 191 Domain 192 In the context of a Resource Directory, a domain is a logical 193 grouping of endpoints. 195 Group 196 In the context of a Resource Directory, a group is a logical 197 grouping of endpoints for the purpose of group communications. 198 All groups within a domain have unique names. 200 Endpoint 201 Endpoint (EP) is a term used to describe a web server or client in 202 [RFC7252]. In the context of this specification an endpoint is 203 used to describe a web server that registers resources to the 204 Resource Directory. An endpoint is identified by its endpoint 205 name, which is included during registration, and has a unique name 206 within the associated domain of the registration. 208 Context 209 A Context is a base URL that gives scheme and (typically) 210 authority information about an Endpoint. The Context of an 211 Endpoint is provided at registration time, and is used by the 212 Resource Directory to resolve relative references inside the 213 registration into absolute URIs. 215 Directory Resource 216 A resource in the Resource Directory (RD) containing registration 217 resources. 219 Group Resource 220 A resource in the RD containing registration resources of the 221 Endpoints that form a group. 223 Registration Resource 224 A resource in the RD that contains information about an Endpoint 225 and its links. 227 Commissioning Tool 228 Commissioning Tool (CT) is a device that assists during the 229 installation of the network by assigning values to parameters, 230 naming endpoints and groups, or adapting the installation to the 231 needs of the applications. 233 RDAO 234 Resource Directory Address Option. 236 3. Architecture and Use Cases 238 3.1. Principles 240 The Resource Directory is primarily a tool to make discovery 241 operations more efficient than querying /.well-known/core on all 242 connected device, or across boundaries that would be limiting those 243 operations. 245 It provides a cache (in the high-level sense, not as defined in 246 [RFC7252]/[RFC2616]) of data that could otherwise only be obtained by 247 directly querying the /.well-known/core resource on the target 248 device, or by accessing those resources with a multicast request. 250 From that, it follows that only information should be stored in the 251 resource directory that is discovered from querying the described 252 device's /.well-known/core resource directly. 254 It also follows that data in the resource directory can only be 255 provided by the device whose descriptions are cached or a dedicated 256 Commissioning Tool (CT). These CTs are thought to act on behalf 257 agents too constrained, or generally unable, to present that 258 information themselves. No other client can modify data in the 259 resource directory. Changes in the Resource Directory do not 260 propagate automatically back to its source. 262 3.2. Architecture 264 The resource directory architecture is illustrated in Figure 1. A 265 Resource Directory (RD) is used as a repository for Web Links 266 [RFC5988] about resources hosted on other web servers, which are 267 called endpoints (EP). An endpoint is a web server associated with a 268 scheme, IP address and port. A physical node may host one or more 269 endpoints. The RD implements a set of REST interfaces for endpoints 270 to register and maintain sets of Web Links (called resource directory 271 registration entries), and for clients to lookup resources from the 272 RD or maintain groups. Endpoints themselves can also act as clients. 273 An RD can be logically segmented by the use of Groups. The group an 274 endpoint is part of, can be defined by the RD or configured by a 275 Commissioning Tool. This information hierarchy is shown in Figure 2. 277 A mechanism to discover an RD using CoRE Link Format [RFC6690] is 278 defined. 280 Endpoints proactively register and maintain resource directory 281 registration entries on the RD, which are soft state and need to be 282 periodically refreshed. 284 An endpoint uses specific interfaces to register, update and remove a 285 resource directory registration entry. It is also possible for an RD 286 to fetch Web Links from endpoints and add them as resource directory 287 registration entries. 289 At the first registration of a set of entries, a "registration 290 resource" is created, the location of which is returned to the 291 registering endpoint. The registering endpoint uses this 292 registration resource to manage the contents of registration entries. 294 A lookup interface for discovering any of the Web Links held in the 295 RD is provided using the CoRE Link Format. 297 Registration Lookup, Group 298 Interface Interfaces 299 +----+ | | 300 | EP |---- | | 301 +----+ ---- | | 302 --|- +------+ | 303 +----+ | ----| | | +--------+ 304 | EP | ---------|-----| RD |----|-----| Client | 305 +----+ | ----| | | +--------+ 306 --|- +------+ | 307 +----+ ---- | | 308 | EP |---- | | 309 +----+ 311 Figure 1: The resource directory architecture. 313 +------------+ 314 | Group | <-- Name, Scheme, IP, Port 315 +------------+ 316 | 317 | 318 +------------+ 319 | Endpoint | <-- Name, Scheme, IP, Port 320 +------------+ 321 | 322 | 323 +------------+ 324 | Resource | <-- Target, Parameters 325 +------------+ 327 Figure 2: The resource directory information hierarchy. 329 3.3. RD Content Model 331 The Entity-Relationship (ER) models shown in Figure 3 and Figure 4 332 model the contents of /.well-known/core and the resource directory 333 respectively, with entity-relationship diagrams [ER]. Entities 334 (rectangles) are used for concepts that exist independently. 335 Attributes (ovals) are used for concepts that exist only in 336 connection with a related entity. Relations (diamonds) give a 337 semantic meaning to the relation between entities. Numbers specify 338 the cardinality of the relations. 340 Some of the attribute values are URIs. Those values are always full 341 URIs and never relative references in the information model. They 342 can, however, be expressed as relative references in serializations, 343 and often are. 345 These models provide an abstract view of the information expressed in 346 link-format documents and a Resource Directory. They cover the 347 concepts, but not necessarily all details of an RD's operation; they 348 are meant to give an overview, and not be a template for 349 implementations. 351 +----------------------+ 352 | /.well-known/core | 353 +----------------------+ 354 | 355 | 1 356 ////////\\\\\\\ 357 < contains > 358 \\\\\\\\/////// 359 | 360 | 0+ 361 +--------------------+ 362 | link | 363 +--------------------+ 364 | 365 | 1 oooooooo 366 +-----o target o 367 0+ | oooooooo 368 oooooooooooo | 369 o target o--------+ 370 o attribute o | 0+ oooooo 371 oooooooooooo +-----o rel o 372 | oooooo 373 | 374 | 1 ooooooooo 375 +-----o context o 376 ooooooooo 378 Figure 3: E-R Model of the content of /.well-known/core 380 The model shown in Figure 3 models the contents of /.well-known/core 381 which contains: 383 o a set of links belonging to the host 385 The host is free to choose links it deems appropriate to be exposed 386 in its ".well-known/core". Typically, the links describe resources 387 that are served by the host, but the set can also contain links to 388 resources on other servers (see examples in [RFC6690] page 14). The 389 set does not necessarily contain links to all resources served by the 390 host. 392 A link has the following attributes (see [RFC5988]): 394 o Zero or more link relations: They describe relations between the 395 link context and the link target. 397 In link-format serialization, they are expressed as space- 398 separated values in the "rel" attribute, and default to "hosts". 400 o A link context URI: It defines the source of the relation, eg. 401 _who_ "hosts" something. 403 In link-format serialization, it is expressed in the "anchor" 404 attribute. There, it can be a relative reference, in which case 405 it gets resolved against the URI of the ".well-known/core" 406 document it was obtained from. It defaults to that document's 407 URI. 409 o A link target URI: It defines the destination of the relation (eg. 410 _what_ is hosted), and is the topic of all target attributes. 412 In link-format serialization, it is expressed between angular 413 brackets, and sometimes called the "href". 415 If there is an anchor attribute present and the link is serialized in 416 [RFC6690] link format, this document will require that the link is an 417 absolute reference to avoid the ambiguities outlined in Appendix A.4. 419 Otherwise, it can be serialized as a relative URI, and gets resolved 420 against the document's URI. 422 o Other target attributes (eg. resource type (rt), interface (if), 423 cor content-type (ct)). These provide additional information 424 about the target URI. 426 +----------------------+ 427 | resource-directory | 428 +----------------------+ 429 | 430 | oooooooooooo 0-1 431 | o MC address o---+ 432 | oooooooooooo | 433 | | 434 //////\\\\ 0+ +--------+ 435 < contains >----------------| group | 436 \\\\\///// +--------+ 437 | | 438 0-n | | 1+ 439 ooooooo 1 +---------------+ ///////\\\\\\ 440 o con o-------| registration |---------< composed of > 441 ooooooo +---------------+ \\\\\\\////// 442 | | 443 | +--------------+ 444 oooooooo 1 | | 445 o loc o----+ /////\\\\ 446 oooooooo | < contains > 447 | \\\\\///// 448 oooooooo 1 | | 449 o ep o----+ | 0+ 450 oooooooo | +------------------+ 451 | | link | 452 oooooooo 0-1 | +------------------+ 453 o d o----+ | 454 oooooooo | | 1 oooooooo 455 | +-----o target o 456 oooooooo 0-1 | | oooooooo 457 o lt o----+ ooooooooooo 0+ | 458 oooooooo | o target o-----+ 459 | o attribute o | 0+ oooooo 460 ooooooooooo 0+ | ooooooooooo +-----o rel o 461 o endpoint o----+ | oooooo 462 o attribute o | 463 ooooooooooo | 1 ooooooooo 464 +----o context o 465 ooooooooo 467 Figure 4: E-R Model of the content of the Resource Directory 469 The model shown in Figure 4 models the contents of the resource 470 directory which contains in addition to /.well-known/core: 472 o 0 to n Registration (entries), 473 o 0 or more Groups 475 A Group has no or one Multicast address attribute and is composed of 476 0 or more endpoints. A registration is associated with one endpoint 477 (ep). An endpoint can be part of 0 or more Groups . A registration 478 defines a set of links as defined for /.well-known/core. A 479 Registration has six attributes: 481 o one ep (endpoint with a unique name) 483 o one con (a string describing the scheme://authority part) 485 o one lt (lifetime), 487 o one loc (location in the RD) 489 o optional one d (domain for query filtering), 491 o optional additional endpoint attributes (from Section 9.3) 493 The cardinality of con is currently 1; future documents are invited 494 to extend the RD specification to support multiple values (eg. 495 [I-D.silverajan-core-coap-protocol-negotiation]). Its value is used 496 as a Base URI when resolving URIs in the links contained in the 497 endpoint. 499 Links are modelled as they are in Figure 3. 501 3.4. Use Case: Cellular M2M 503 Over the last few years, mobile operators around the world have 504 focused on development of M2M solutions in order to expand the 505 business to the new type of users: machines. The machines are 506 connected directly to a mobile network using an appropriate embedded 507 wireless interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing 508 short and wide range wireless interfaces. From the system design 509 point of view, the ambition is to design horizontal solutions that 510 can enable utilization of machines in different applications 511 depending on their current availability and capabilities as well as 512 application requirements, thus avoiding silo like solutions. One of 513 the crucial enablers of such design is the ability to discover 514 resources (machines -- endpoints) capable of providing required 515 information at a given time or acting on instructions from the end 516 users. 518 Imagine a scenario where endpoints installed on vehicles enable 519 tracking of the position of these vehicles for fleet management 520 purposes and allow monitoring of environment parameters. During the 521 boot-up process endpoints register with a Resource Directory, which 522 is hosted by the mobile operator or somewhere in the cloud. 523 Periodically, these endpoints update their registration and may 524 modify resources they offer. 526 When endpoints are not always connected, for example because they 527 enter a sleep mode, a remote server is usually used to provide proxy 528 access to the endpoints. Mobile apps or web applications for 529 environment monitoring contact the RD, look up the endpoints capable 530 of providing information about the environment using an appropriate 531 set of link parameters, obtain information on how to contact them 532 (URLs of the proxy server), and then initiate interaction to obtain 533 information that is finally processed, displayed on the screen and 534 usually stored in a database. Similarly, fleet management systems 535 provide the appropriate link parameters to the RD to look up for EPs 536 deployed on the vehicles the application is responsible for. 538 3.5. Use Case: Home and Building Automation 540 Home and commercial building automation systems can benefit from the 541 use of M2M web services. The discovery requirements of these 542 applications are demanding. Home automation usually relies on run- 543 time discovery to commission the system, whereas in building 544 automation a combination of professional commissioning and run-time 545 discovery is used. Both home and building automation involve peer- 546 to-peer interactions between endpoints, and involve battery-powered 547 sleeping devices. 549 3.6. Use Case: Link Catalogues 551 Resources may be shared through data brokers that have no knowledge 552 beforehand of who is going to consume the data. Resource Directory 553 can be used to hold links about resources and services hosted 554 anywhere to make them discoverable by a general class of 555 applications. 557 For example, environmental and weather sensors that generate data for 558 public consumption may provide the data to an intermediary server, or 559 broker. Sensor data are published to the intermediary upon changes 560 or at regular intervals. Descriptions of the sensors that resolve to 561 links to sensor data may be published to a Resource Directory. 562 Applications wishing to consume the data can use RD Lookup to 563 discover and resolve links to the desired resources and endpoints. 564 The Resource Directory service need not be coupled with the data 565 intermediary service. Mapping of Resource Directories to data 566 intermediaries may be many-to-many. 568 Metadata in web link formats like [RFC6690] are supplied by Resource 569 Directories, which may be internally stored as triples, or relation/ 570 attribute pairs providing metadata about resource links. External 571 catalogs that are represented in other formats may be converted to 572 common web linking formats for storage and access by Resource 573 Directories. Since it is common practice for these to be URN 574 encoded, simple and lossless structural transforms should generally 575 be sufficient to store external metadata in Resource Directories. 577 The additional features of Resource Directory allow domains to be 578 defined to enable access to a particular set of resources from 579 particular applications. This provides isolation and protection of 580 sensitive data when needed. Resource groups may defined to allow 581 batched reads from multiple resources. 583 4. Finding a Resource Directory 585 A (re-e)starting device may want to find one or more resource 586 directories to make itself known with. 588 The device may be pre-configured to exercise specific mechanisms for 589 finding the resource directory: 591 o It may be configured with a specific IP address for the RD. That 592 IP address may also be an anycast address, allowing the network to 593 forward RD requests to an RD that is topologically close; each 594 target network environment in which some of these preconfigured 595 nodes are to be brought up is then configured with a route for 596 this anycast address that leads to an appropriate RD. (Instead of 597 using an anycast address, a multicast address can also be 598 preconfigured. The RD directory servers then need to configure 599 one of their interfaces with this multicast address.) 601 o It may be configured with a DNS name for the RD and a resource- 602 record type to look up under this name; it can find a DNS server 603 to perform the lookup using the usual mechanisms for finding DNS 604 servers. 606 o It may be configured to use a service discovery mechanism such as 607 DNS-SD [RFC6763]. The present specification suggests configuring 608 the service with name rd._sub._coap._udp, preferably within the 609 domain of the querying nodes. 611 For cases where the device is not specifically configured with a way 612 to find a resource directory, the network may want to provide a 613 suitable default. 615 o If the address configuration of the network is performed via 616 SLAAC, this is provided by the RDAO option Section 4.1. 618 o If the address configuration of the network is performed via DHCP, 619 this could be provided via a DHCP option (no such option is 620 defined at the time of writing). 622 Finally, if neither the device nor the network offer any specific 623 configuration, the device may want to employ heuristics to find a 624 suitable resource directory. 626 The present specification does not fully define these heuristics, but 627 suggests a number of candidates: 629 o In a 6LoWPAN, just assume the Edge Router (6LBR) can act as a 630 resource directory (using the ABRO option to find that [RFC6775]). 631 Confirmation can be obtained by sending a Unicast to 632 "coap://[6LBR]/.well-known/core?rt=core.rd*". 634 o In a network that supports multicast well, discovering the RD 635 using a multicast query for /.well-known/core as specified in CoRE 636 Link Format [RFC6690]: Sending a Multicast GET to 637 "coap://[MCD1]/.well-known/core?rt=core.rd*". RDs within the 638 multicast scope will answer the query. 640 As some of the RD addresses obtained by the methods listed here are 641 just (more or less educated) guesses, endpoints MUST make use of any 642 error messages to very strictly rate-limit requests to candidate IP 643 addresses that don't work out. For example, an ICMP Destination 644 Unreachable message (and, in particular, the port unreachable code 645 for this message) may indicate the lack of a CoAP server on the 646 candidate host, or a CoAP error response code such as 4.05 "Method 647 Not Allowed" may indicate unwillingness of a CoAP server to act as a 648 directory server. 650 If multiple candidate addresses are discovered, the device may pick 651 any of them initially, unless the discovery method indicates a more 652 precise selection scheme. 654 4.1. Resource Directory Address Option (RDAO) 656 The Resource Directory Address Option (RDAO) using IPv6 neighbor 657 Discovery (ND) carries information about the address of the Resource 658 Directory (RD). This information is needed when endpoints cannot 659 discover the Resource Directory with a link-local multicast address 660 because the endpoint and the RD are separated by a border Router 661 (6LBR). In many circumstances the availability of DHCP cannot be 662 guaranteed either during commissioning of the network. The presence 663 and the use of the RD is essential during commissioning. 665 It is possible to send multiple RDAO options in one message, 666 indicating as many resource directory addresses. 668 The lifetime 0x0 means that the RD address is invalid and to be 669 removed. 671 The RDAO format is: 673 0 1 2 3 674 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 675 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 676 | Type | Length = 3 | Valid Lifetime | 677 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 678 | Reserved | 679 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 680 | | 681 + + 682 | | 683 + RD Address + 684 | | 685 + + 686 | | 687 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 689 Fields: 691 Type: 38 693 Length: 8-bit unsigned integer. The length of 694 the option in units of 8 bytes. 695 Always 3. 697 Valid Lifetime: 16-bit unsigned integer. The length of 698 time in units of 60 seconds (relative to 699 the time the packet is received) that 700 this Resource Directory address is valid. 701 A value of all zero bits (0x0) indicates 702 that this Resource Directory address 703 is not valid anymore. 705 Reserved: This field is unused. It MUST be 706 initialized to zero by the sender and 707 MUST be ignored by the receiver. 709 RD Address: IPv6 address of the RD. 711 Figure 5: Resource Directory Address Option 713 5. Resource Directory 715 This section defines the required set of REST interfaces between a 716 Resource Directory (RD) and endpoints. Although the examples 717 throughout this section assume the use of CoAP [RFC7252], these REST 718 interfaces can also be realized using HTTP [RFC7230]. In all 719 definitions in this section, both CoAP response codes (with dot 720 notation) and HTTP response codes (without dot notation) are shown. 722 An RD implementing this specification MUST support the discovery, 723 registration, update, lookup, and removal interfaces defined in this 724 section. 726 All operations on the contents of the Resource Directory MUST be 727 atomic and idempotent. 729 A resource directory MAY make the information submitted to it 730 available to further directories, if it can ensure that a loop does 731 not form. The protocol used between directories to ensure loop-free 732 operation is outside the scope of this document. 734 5.1. Payload Content Formats 736 Resource Directory implementations using this specification MUST 737 support the application/link-format content format (ct=40). 739 Resource Directories implementing this specification MAY support 740 additional content formats. 742 Any additional content format supported by a Resource Directory 743 implementing this specification MUST have an equivalent serialization 744 in the application/link-format content format. 746 5.2. URI Discovery 748 Before an endpoint can make use of an RD, it must first know the RD's 749 address and port, and the URI path information for its REST APIs. 750 This section defines discovery of the RD and its URIs using the well- 751 known interface of the CoRE Link Format [RFC6690]. A complete set of 752 RD discovery methods is described in Section 4. 754 Discovery of the RD registration URI path is performed by sending 755 either a multicast or unicast GET request to "/.well-known/core" and 756 including a Resource Type (rt) parameter [RFC6690] with the value 757 "core.rd" in the query string. Likewise, a Resource Type parameter 758 value of "core.rd-lookup*" is used to discover the URIs for RD Lookup 759 operations, and "core.rd-group" is used to discover the URI path for 760 RD Group operations. Upon success, the response will contain a 761 payload with a link format entry for each RD function discovered, 762 indicating the URI of the RD function returned and the corresponding 763 Resource Type. When performing multicast discovery, the multicast IP 764 address used will depend on the scope required and the multicast 765 capabilities of the network. 767 A Resource Directory MAY provide hints about the content-formats it 768 supports in the links it exposes or registers, using the "ct" link 769 attribute, as shown in the example below. Clients MAY use these 770 hints to select alternate content-formats for interaction with the 771 Resource Directory. 773 HTTP does not support multicast and consequently only unicast 774 discovery can be supported using HTTP. Links to Resource Directories 775 MAY be registered in other Resource Directories. The well-known 776 entry points SHOULD be provided to enable the bootstrapping of 777 unicast discovery. 779 An implementation of this resource directory specification MUST 780 support query filtering for the rt parameter as defined in [RFC6690]. 782 While the link targets in this discovery step are often expressed in 783 path-absolute form, this is not a requirement. Clients SHOULD 784 therefore accept URIs of all schemes they support, both in absolute 785 and relative forms, and not limit the set of discovered URIs to those 786 hosted at the address used for URI discovery. 788 The URI Discovery operation can yield multiple URIs of a given 789 resource type. The client can use any of the discovered addresses 790 initially. 792 The discovery request interface is specified as follows: 794 Interaction: EP -> RD 796 Method: GET 798 URI Template: /.well-known/core{?rt} 800 URI Template Variables: 802 rt := Resource Type (optional). MAY contain one of the values 803 "core.rd", "core.rd-lookup*", "core.rd-lookup-res", "core.rd- 804 lookup-ep", "core.rd-lookup-gp", "core.rd-group" or "core.rd*" 806 Content-Format: application/link-format (if any) 808 Content-Format: application/link-format+json (if any) 810 Content-Format: application/link-format+cbor (if any) 812 The following response codes are defined for this interface: 814 Success: 2.05 "Content" or 200 "OK" with an application/link-format, 815 application/link-format+json, or application/link-format+cbor 816 payload containing one or more matching entries for the RD 817 resource. 819 Failure: 4.00 "Bad Request" or 400 "Bad Request" is returned in case 820 of a malformed request for a unicast request. 822 Failure: No error response to a multicast request. 824 HTTP support : YES (Unicast only) 826 The following example shows an endpoint discovering an RD using this 827 interface, thus learning that the directory resource is, in this 828 example, at /rd, and that the content-format delivered by the server 829 hosting the resource is application/link-format (ct=40). Note that 830 it is up to the RD to choose its RD resource paths. 832 Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* 834 Res: 2.05 Content 835 ;rt="core.rd";ct=40, 836 ;rt="core.rd-lookup-ep";ct=40, 837 ;rt="core.rd-lookup-res";ct=40, 838 ;rt="core.rd-lookup-gp";ct=40, 839 ;rt="core.rd-group";ct=40 841 Figure 6: Example discovery exchange 843 The following example shows the way of indicating that a client may 844 request alternate content-formats. The Content-Format code attribute 845 "ct" MAY include a space-separated sequence of Content-Format codes 846 as specified in Section 7.2.1 of [RFC7252], indicating that multiple 847 content-formats are available. The example below shows the required 848 Content-Format 40 (application/link-format) indicated as well as the 849 the CBOR and JSON representation of link format. The RD resource 850 paths /rd, /rd-lookup, and /rd-group are example values. The server 851 in this example also indicates that it is capable of providing 852 observation on resource lookups. 854 [ The RFC editor is asked to replace these and later occurrences of 855 TBD64 and TBD504 with the numeric ID values assigned by IANA to 856 application/link-format+cbor and application/link-format+json, 857 respectively, as they are defined in I-D.ietf-core-links-json. ] 859 Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* 861 Res: 2.05 Content 862 ;rt="core.rd";ct="40 65225", 863 ;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs, 864 ;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504", 865 ;rt="core.rd-lookup-gp";ct=40 TBD64 TBD504", 866 ;rt="core.rd-group";ct="40 TBD64 TBD504" 867 From a management and maintenance perspective, it is necessary to 868 identify the components that constitute the server. The 869 identification refers to information about for example client-server 870 incompatibilities, supported features, required updates and other 871 aspects. The URI discovery address, a described in section 4 of 872 [RFC6690] can be used to find the identification. 874 It would typically be stored in an implementation information link 875 (as described in [I-D.bormann-t2trg-rel-impl]): 877 Req: GET /.well-known/core?rel=impl-info 879 Res: 2.05 Content 880 ; 881 rel="impl-info" 883 Note that depending on the particular server's architecture, such a 884 link could be anchored at the server's root, at the discovery site 885 (as in this example) or at individual RD components. The latter is 886 to be expected when different applications are run on the same 887 server. 889 5.3. Registration 891 After discovering the location of an RD, an endpoint MAY register its 892 resources using the registration interface. This interface accepts a 893 POST from an endpoint containing the list of resources to be added to 894 the directory as the message payload in the CoRE Link Format 895 [RFC6690], JSON CoRE Link Format (application/link-format+json), or 896 CBOR CoRE Link Format (application/link-format+cbor) 897 [I-D.ietf-core-links-json], along with query parameters indicating 898 the name of the endpoint, and optionally the domain and the lifetime 899 of the registration. It is expected that other specifications will 900 define further parameters (see Section 9.3). The RD then creates a 901 new registration resource in the RD and returns its location. An 902 endpoint MUST use that location when refreshing registrations using 903 this interface. Registration resources in the RD are kept active for 904 the period indicated by the lifetime parameter. The endpoint is 905 responsible for refreshing the registration resource within this 906 period using either the registration or update interface. The 907 registration interface MUST be implemented to be idempotent, so that 908 registering twice with the same endpoint parameters ep and d does not 909 create multiple registration resources. A new registration resource 910 may be created at any time to supersede an existing registration, 911 replacing the registration parameters and links. 913 The posted link-format document can (and typically does) contain 914 relative references both in its link targets and in its anchors, or 915 contain empty anchors. The RD server needs to resolve these 916 references in order to faithfully represent them in lookups. The 917 Base URI against which they are resolved is the context of the 918 registration, which is provided either explicitly in the "con" 919 parameter or constructed implicitly from the requester's network 920 address. 922 Documents in [RFC6690] Link Format SHOULD NOT contain links in which 923 resolving the target literal against the base URI gives a different 924 result than resolving it against the resolved anchor; this is to 925 avoid the ambiguities described in Appendix A.4. * Entries in which 926 there is no anchor attribute, * entries in which the target is an 927 absolute reference and * entries in which both the target and the 928 anchor start with a slash ("/") 930 never cause that kind of ambiguity. 932 The registration request interface is specified as follows: 934 Interaction: EP -> RD 936 Method: POST 938 URI Template: {+rd}{?ep,d,lt,con,extra-attrs*} 940 URI Template Variables: 942 rd := RD registration URI (mandatory). This is the location of 943 the RD, as obtained from discovery. 945 ep := Endpoint name (mostly mandatory). The endpoint name is an 946 identifier that MUST be unique within a domain. The maximum 947 length of this parameter is 63 bytes. If the RD is configured 948 to recognize the endpoint (eg. based on its security context), 949 the endpoint can ignore the endpoint name, and assign one based 950 on a se of configuration parameter values. 952 d := Domain (optional). The domain to which this endpoint 953 belongs. The maximum length of this parameter is 63 bytes. 954 When this parameter is not present, the RD MAY associate the 955 endpoint with a configured default domain or leave it empty. 957 lt := Lifetime (optional). Lifetime of the registration in 958 seconds. Range of 60-4294967295. If no lifetime is included 959 in the initial registration, a default value of 86400 (24 960 hours) SHOULD be assumed. 962 con := Context (optional). This parameter sets the Default Base 963 URI under which the request's links are to be interpreted. The 964 specified URI MUST NOT have a path component of its own, but 965 MUST be suitable as a base URI to resolve any relative 966 references given in the registration. The parameter is 967 therefore of the shape "scheme://authority" for HTTP and CoAP 968 URIs. In the absence of this parameter the scheme of the 969 protocol, source address and source port of the registration 970 request are assumed. This parameter is mandatory when the 971 directory is filled by a third party such as an commissioning 972 tool. If the endpoint uses an ephemeral port to register with, 973 it MUST include the con parameter in the registration to 974 provide a valid network path. If the endpoint which is located 975 behind a NAT gateway is registering with a Resource Directory 976 which is on the network service side of the NAT gateway, the 977 endpoint MUST use a persistent port for the outgoing 978 registration in order to provide the NAT gateway with a valid 979 network address for replies and incoming requests. 981 extra-attrs := Additional registration attributes (optional). 982 The endpoint can pass any parameter registered at Section 9.3 983 to the directory. If the RD is aware of the parameter's 984 specified semantics, it processes it accordingly. Otherwise, 985 it MUST store the unknown key and its value(s) as an endpoint 986 attribute for further lookup. 988 Content-Format: application/link-format 990 Content-Format: application/link-format+json 992 Content-Format: application/link-format+cbor 994 The following response codes are defined for this interface: 996 Success: 2.01 "Created" or 201 "Created". The Location header 997 option MUST be included in the response when a new registration 998 resource is created. This Location MUST be a stable identifier 999 generated by the RD as it is used for all subsequent operations on 1000 this registration resource. The registration resource location 1001 thus returned is for the purpose of updating the lifetime of the 1002 registration and for maintaining the content of the registered 1003 links, including updating and deleting links. A registration with 1004 an already registered ep and d value pair responds with the same 1005 success code and Location as the original registration; the set of 1006 links registered with the endpoint is replaced with the links from 1007 the payload. 1009 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1010 request. 1012 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1013 Service could not perform the operation. 1015 HTTP support: YES 1017 If the registration fails with a Service Unavailable response and a 1018 Max-Age option or Retry-After header, the client SHOULD retry the 1019 operation after the time indicated. If the registration fails in 1020 another way, including request timeouts, or if the Service 1021 Unavailable error persists after several retries, or indicates a 1022 longer time than the endpoint is willing to wait, it SHOULD pick 1023 another registration URI from the "URI Discovery" step and if there 1024 is only one or the list is exhausted, pick other choices from the 1025 "Finding a Resource Directory" step. Care has to be taken to 1026 consider the freshness of results obtained earlier, eg. of the result 1027 of a "/.well-known/core" response, the lifetime of an RDAO option and 1028 of DNS responses. Any rate limits and persistent errors from the 1029 "Finding a Resource Directory" step must be considered for the whole 1030 registration time, not only for a single operation. 1032 The following example shows an endpoint with the name "node1" 1033 registering two resources to an RD using this interface. The 1034 location "/rd" is an example RD location discovered in a request 1035 similar to Figure 6. 1037 Req: POST coap://rd.example.com/rd?ep=node1 1038 Content-Format: 40 1039 Payload: 1040 ;ct=41;rt="temperature-c";if="sensor"; 1041 anchor="coap://spurious.example.com:5683", 1042 ;ct=41;rt="light-lux";if="sensor" 1044 Res: 2.01 Created 1045 Location: /rd/4521 1047 Figure 7: Example registration payload 1049 A Resource Directory may optionally support HTTP. Here is an example 1050 of almost the same registration operation above, when done using HTTP 1051 and the JSON Link Format. 1053 Req: POST /rd?ep=node1&con=http://[2001:db8:1::1] HTTP/1.1 1054 Host : example.com 1055 Content-Type: application/link-format+json 1056 Payload: 1057 [ 1058 {"href": "/sensors/temp", "ct": "41", "rt": "temperature-c", "if": "sensor", 1059 "anchor": "coap://spurious.example.com:5683"}, 1060 {"href": "/sensors/light", "ct": "41", "rt": "light-lux", "if": "sensor"} 1061 ] 1063 Res: 201 Created 1064 Location: /rd/4521 1066 5.3.1. Simple Registration 1068 Not all endpoints hosting resources are expected to know how to 1069 upload links to a RD as described in Section 5.3. Instead, simple 1070 endpoints can implement the Simple Registration approach described in 1071 this section. An RD implementing this specification MUST implement 1072 Simple Registration. However, there may be security reasons why this 1073 form of directory discovery would be disabled. 1075 This approach requires that the endpoint makes available the hosted 1076 resources that it wants to be discovered, as links on its "/.well- 1077 known/core" interface as specified in [RFC6690]. The links in that 1078 document are subject to the same limitations as the payload of a 1079 registration (no relative target references when anchor is present). 1081 The endpoint then finds one or more addresses of the directory server 1082 as described in Section 4. 1084 An endpoint finally asks the selected directory server to probe it 1085 for resources and publish them as follows: 1087 The endpoint sends (and regularly refreshes with) a POST request to 1088 the "/.well-known/core" URI of the directory server of choice. The 1089 body of the POST request is empty, which triggers the resource 1090 directory server to perform GET requests at the requesting server's 1091 default discovery URI to obtain the link-format payload to register. 1093 The endpoint includes the same registration parameters in the POST 1094 request as it would per Section 5.3. The context of the registration 1095 is taken from the requesting server's URI. 1097 The endpoints MUST be deleted after the expiration of their lifetime. 1098 Additional operations on the registration resource cannot be executed 1099 because no registration location is returned. 1101 The following example shows an endpoint using Simple Registration, by 1102 simply sending an empty POST to a resource directory. 1104 Req:(to RD server from [2001:db8:2::1]) 1105 POST /.well-known/core?lt=6000&ep=node1 1106 Content-Format: 40 1107 No payload 1109 Res: 2.04 Changed 1111 (later) 1113 Req: (from RD server to [2001:db8:2::1]) 1114 GET /.well-known/core 1115 Accept: 40 1117 Res: 2.05 Content 1118 Payload: 1119 1121 5.3.2. Third-party registration 1123 For some applications, even Simple Registration may be too taxing for 1124 some very constrained devices, in particular if the security 1125 requirements become too onerous. 1127 In a controlled environment (e.g. building control), the Resource 1128 Directory can be filled by a third device, called a commissioning 1129 tool. The commissioning tool can fill the Resource Directory from a 1130 database or other means. For that purpose the scheme, IP address and 1131 port of the registered device is indicated in the Context parameter 1132 of the registration described in Section 5.3. 1134 It should be noted that the value of the con parameter applies to all 1135 the links of the registration and has consequences for the anchor 1136 value of the individual links as exemplified in Appendix A. An 1137 eventual (currently non-existing) con attribute of the link is not 1138 affected by the value of con parameter in the registration. 1140 5.4. Operations on the Registration Resource 1142 After the initial registration, an endpoint should retain the 1143 returned location of the Registration Resource for further 1144 operations, including refreshing the registration in order to extend 1145 the lifetime and "keep-alive" the registration. When the lifetime of 1146 the registration has expired, the RD SHOULD NOT respond to discovery 1147 queries concerning this endpoint. The RD SHOULD continue to provide 1148 access to the Registration Resource after a registration time-out 1149 occurs in order to enable the registering endpoint to eventually 1150 refresh the registration. The RD MAY eventually remove the 1151 registration resource for the purpose of garbage collection and 1152 remove it from any group it belongs to. If the Registration Resource 1153 is removed, the endpoint will need to re-register. 1155 The Registration Resource may also be used to inspect the 1156 registration resource using GET, update the registration, or cancel 1157 the registration using DELETE. 1159 These operations are described in this section. 1161 5.4.1. Registration Update 1163 The update interface is used by an endpoint to refresh or update its 1164 registration with an RD. To use the interface, the endpoint sends a 1165 POST request to the registration resource returned by the initial 1166 registration operation. 1168 An update MAY update the lifetime- or the context- registration 1169 parameters "lt", "con" as in Section 5.3. Parameters that are not 1170 being changed SHOULD NOT be included in an update. Adding parameters 1171 that have not changed increases the size of the message but does not 1172 have any other implications. Parameters MUST be included as query 1173 parameters in an update operation as in Section 5.3. 1175 A registration update resets the timeout of the registration to the 1176 (possibly updated) lifetime of the registration, independent of 1177 whether a "lt" parameter was given. 1179 If the context of the registration is changed in an update explicitly 1180 or implicitly, relative references submitted in the original 1181 registration or later updates are resolved anew against the new 1182 context (like in the original registration). 1184 The registration update operation only describes the use of POST with 1185 an empty payload. Future standards might describe the semantics of 1186 using content formats and payloads with the POST method to update the 1187 links of a registration (see Section 5.4.4). 1189 The update registration request interface is specified as follows: 1191 Interaction: EP -> RD 1193 Method: POST 1195 URI Template: {+location}{?lt,con,extra-attrs*} 1196 URI Template Variables: 1198 location := This is the Location returned by the RD as a result 1199 of a successful earlier registration. 1201 lt := Lifetime (optional). Lifetime of the registration in 1202 seconds. Range of 60-4294967295. If no lifetime is included, 1203 the previous last lifetime set on a previous update or the 1204 original registration (falling back to 86400) SHOULD be used. 1206 con := Context (optional). This parameter updates the context 1207 established in the original registration to a new value. If 1208 the parameter is set in an update, it is stored by the RD as 1209 the new Base URI under which to interpret the links of the 1210 registration, following the same restrictions as in the 1211 registration. If the parameter is not set and was set 1212 explicitly before, the previous context value is kept 1213 unmodified. If the parameter is not set and was not set 1214 explicitly before either, the source address and source port of 1215 the update request are stored as the context. 1217 extra-attrs := Additional registration attributes (optional). As 1218 with the registration, the RD processes them if it knows their 1219 semantics. Otherwise, unknown attributes are stored as 1220 endpoint attributes, overriding any previously stored endpoint 1221 attributes of the same key. 1223 Content-Format: none (no payload) 1225 The following response codes are defined for this interface: 1227 Success: 2.04 "Changed" or 204 "No Content" if the update was 1228 successfully processed. 1230 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1231 request. 1233 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1234 exist (e.g. may have expired). 1236 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1237 Service could not perform the operation. 1239 HTTP support: YES 1241 If the registration update fails with a "Service Unavailable" 1242 response and a Max-Age option or Retry-After header, the client 1243 SHOULD retry the operation after the time indicated. If the 1244 registration fails in another way, including request timeouts, or if 1245 the time indicated excedes the remaining lifetime, the client SHOULD 1246 attempt registration again. 1248 The following example shows an endpoint updating its registration 1249 resource at an RD using this interface with the example location 1250 value: /rd/4521. 1252 Req: POST /rd/4521 1254 Res: 2.04 Changed 1256 The following example shows an endpoint updating its registration 1257 resource at an RD using this interface with the example location 1258 value: /rd/4521. The initial registration by the client set the 1259 following values: 1261 o endpoint name (ep)=endpoint1 1263 o lifetime (lt)=500 1265 o context (con)=coap://local-proxy-old.example.com:5683 1267 o payload of Figure 7 1269 The initial state of the Resource Directory is reflected in the 1270 following request: 1272 Req: GET /rd-lookup/res?ep=endpoint1 1274 Res: 2.01 Content 1275 Payload: 1276 ;ct=41;rt="temperature"; 1277 anchor="coap://spurious.example.com:5683", 1278 ;ct=41;rt="light-lux"; 1279 if="sensor";anchor="coap://local-proxy-old.example.com:5683" 1281 The following example shows an EP changing the context to 1282 "coaps://new.example.com:5684": 1284 Req: POST /rd/4521?con=coaps://new.example.com:5684 1286 Res: 2.04 Changed 1288 The consecutive query returns: 1290 Req: GET /rd-lookup/res?ep=endpoint1 1292 Res: 2.01 Content 1293 Payload: 1294 ;ct=41;rt="temperature"; 1295 anchor="coap://spurious.example.com:5683", 1296 ;ct=41;rt="light-lux";if="sensor"; 1297 anchor="coaps://new.example.com:5684", 1299 5.4.2. Registration Removal 1301 Although RD entries have soft state and will eventually timeout after 1302 their lifetime, an endpoint SHOULD explicitly remove its entry from 1303 the RD if it knows it will no longer be available (for example on 1304 shut-down). This is accomplished using a removal interface on the RD 1305 by performing a DELETE on the endpoint resource. 1307 Removed endpoints are implicitly removed from the groups to which 1308 they belong. 1310 The removal request interface is specified as follows: 1312 Interaction: EP -> RD 1314 Method: DELETE 1316 URI Template: {+location} 1318 URI Template Variables: 1320 location := This is the Location returned by the RD as a result 1321 of a successful earlier registration. 1323 The following responses codes are defined for this interface: 1325 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1327 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1328 request. 1330 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1331 exist (e.g. may have expired). 1333 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1334 Service could not perform the operation. 1336 HTTP support: YES 1337 The following examples shows successful removal of the endpoint from 1338 the RD with example location value /rd/4521. 1340 Req: DELETE /rd/4521 1342 Res: 2.02 Deleted 1344 5.4.3. Read Endpoint Links 1346 Some endpoints may wish to manage their links as a collection, and 1347 may need to read the current set of links stored in the registration 1348 resource, in order to determine link maintenance operations. 1350 One or more links MAY be selected by using query filtering as 1351 specified in [RFC6690] Section 4.1 1353 If no links are selected, the Resource Directory SHOULD return an 1354 empty payload. 1356 The read request interface is specified as follows: 1358 Interaction: EP -> RD 1360 Method: GET 1362 URI Template: {+location}{?href,rel,rt,if,ct} 1364 URI Template Variables: 1366 location := This is the Location returned by the RD as a result 1367 of a successful earlier registration. 1369 href,rel,rt,if,ct := link relations and attributes specified in 1370 the query in order to select particular links based on their 1371 relations and attributes. "href" denotes the URI target of the 1372 link. See [RFC6690] Sec. 4.1 1374 The following response codes are defined for this interface: 1376 Success: 2.05 "Content" or 200 "OK" upon success with an 1377 "application/link-format", "application/link-format+cbor", or 1378 "application/link-format+json" payload. 1380 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1381 request. 1383 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1384 exist (e.g. may have expired). 1386 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1387 Service could not perform the operation. 1389 HTTP support: YES 1391 The following examples show successful read of the endpoint links 1392 from the RD, with example location value /rd/4521 and example 1393 registration payload of Figure 7. 1395 Req: GET /rd/4521 1397 Res: 2.01 Content 1398 Payload: 1399 ;ct=41;rt="temperature-c";if="sensor"; 1400 anchor="coap://spurious.example.com:5683", 1401 ;ct=41;rt="light-lux";if="sensor" 1403 5.4.4. Update Endpoint Links 1405 An iPATCH (or PATCH) update [RFC8132] adds, removes or changes links 1406 of a registration by including link update information in the payload 1407 of the update with a media type that still needs to be defined. 1409 6. RD Groups 1411 This section defines the REST API for the creation, management, and 1412 lookup of endpoints for group operations. Similar to endpoint 1413 registration entries in the RD, groups may be created or removed. 1414 However unlike an endpoint entry, a group entry consists of a list of 1415 endpoints and does not have a lifetime associated with it. In order 1416 to make use of multicast requests with CoAP, a group MAY have a 1417 multicast address associated with it. 1419 6.1. Register a Group 1421 In order to create a group, a commissioning tool (CT) used to 1422 configure groups, makes a request to the RD indicating the name of 1423 the group to create (or update), optionally the domain the group 1424 belongs to, and optionally the multicast address of the group. This 1425 specification does not require that the endpoints belong to the same 1426 domain as the group, but a Resource Directory implementation can 1427 impose requirements on the domains of groups and endpoints depending 1428 on its configuration. 1430 The registration message is a list of links to registration resources 1431 of the endpoints that belong to that group. The registration 1432 resources MAY be located on different hosts than the group hosting 1433 RD. In that case the endpoint link points to the registration 1434 resource on the other RD. The commissioning tool SHOULD NOT attempt 1435 to enter a foreign registration in a group unless it found it in the 1436 group RD's lookup results, or has other reasons to assume that the 1437 foreign registration will be accepted. 1439 The commissioning tool SHOULD not send any target attributes with the 1440 links to the registration resources, and the resource directory 1441 SHOULD reject registrations that contain links with unprocessable 1442 attributes. 1444 Configuration of the endpoints themselves is out of scope of this 1445 specification. Such an interface for managing the group membership 1446 of an endpoint has been defined in [RFC7390]. 1448 The registration request interface is specified as follows: 1450 Interaction: CT -> RD 1452 Method: POST 1454 URI Template: {+rd-group}{?gp,d,con} 1456 URI Template Variables: 1458 rd-group := RD Group URI (mandatory). This is the location of 1459 the RD Group REST API. 1461 gp := Group Name (mandatory). The name of the group to be 1462 created or replaced, unique within that domain. The maximum 1463 length of this parameter is 63 bytes. 1465 d := Domain (optional). The domain to which this group belongs. 1466 The maximum length of this parameter is 63 bytes. When this 1467 parameter is not present, the RD MAY associate the group with a 1468 configured default domain or leave it empty. 1470 con := Context (optional). This parameter sets the scheme, 1471 address and port of the multicast address associated with the 1472 group. When con is used, scheme and host are mandatory and 1473 port parameter is optional. 1475 Content-Format: application/link-format 1477 Content-Format: application/link-format+json 1479 Content-Format: application/link-format+cbor 1481 The following response codes are defined for this interface: 1483 Success: 2.01 "Created" or 201 "Created". The Location header 1484 option MUST be returned in response to a successful group CREATE 1485 operation. This Location MUST be a stable identifier generated by 1486 the RD as it is used for delete operations of the group resource. 1488 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1489 request. 1491 Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not 1492 registered in the RD (e.g. may have expired). 1494 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1495 Service could not perform the operation. 1497 HTTP support: YES 1499 The following example shows an EP registering a group with the name 1500 "lights" which has two endpoints. The RD group path /rd-group is an 1501 example RD location discovered in a request similar to Figure 6. 1503 Req: POST coap://rd.example.com/rd-group?gp=lights 1504 &con=coap://[ff35:30:2001:db8::1] 1505 Content-Format: 40 1506 Payload: 1507 , 1508 1510 Res: 2.01 Created 1511 Location: /rd-group/12 1513 A relative href value denotes the path to the registration resource 1514 of the Endpoint. When pointing to a registration resource on a 1515 different RD, the href value is an absolute URI. 1517 6.2. Group Removal 1519 A group can be removed simply by sending a removal message to the 1520 location of the group registration resource which was returned when 1521 initially registering the group. Removing a group MUST NOT remove 1522 the endpoints of the group from the RD. 1524 The removal request interface is specified as follows: 1526 Interaction: CT -> RD 1528 Method: DELETE 1530 URI Template: {+location} 1531 URI Template Variables: 1533 location := This is the path of the group resource returned by 1534 the RD as a result of a successful group registration. 1536 The following responses codes are defined for this interface: 1538 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1540 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1541 request. 1543 Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. 1545 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1546 Service could not perform the operation. 1548 HTTP support: YES 1550 The following examples shows successful removal of the group from the 1551 RD with the example location value /rd-group/12. 1553 Req: DELETE /rd-group/12 1555 Res: 2.02 Deleted 1557 7. RD Lookup 1559 To discover the resources registered with the RD, a lookup interface 1560 must be provided. This lookup interface is defined as a default, and 1561 it is assumed that RDs may also support lookups to return resource 1562 descriptions in alternative formats (e.g. Atom or HTML Link) or 1563 using more advanced interfaces (e.g. supporting context or semantic 1564 based lookup). 1566 RD Lookup allows lookups for groups, endpoints and resources using 1567 attributes defined in this document and for use with the CoRE Link 1568 Format. The result of a lookup request is the list of links (if any) 1569 corresponding to the type of lookup. Thus, a group lookup MUST 1570 return a list of groups, an endpoint lookup MUST return a list of 1571 endpoints and a resource lookup MUST return a list of links to 1572 resources. 1574 The lookup type is selected by a URI endpoint, which is indicated by 1575 a Resource Type as per Table 1 below: 1577 +-------------+--------------------+-----------+ 1578 | Lookup Type | Resource Type | Mandatory | 1579 +-------------+--------------------+-----------+ 1580 | Resource | core.rd-lookup-res | Mandatory | 1581 | Endpoint | core.rd-lookup-ep | Mandatory | 1582 | Group | core.rd-lookup-gp | Optional | 1583 +-------------+--------------------+-----------+ 1585 Table 1: Lookup Types 1587 7.1. Resource lookup 1589 Resource lookup results in links that are semantically equivalent to 1590 the links submitted to the RD if they were accessed on the endpoint 1591 itself. The links and link parameters returned are equal to the 1592 submitted, except that the target and anchor references are fully 1593 resolved. 1595 Links that did not have an anchor attribute are therefore returned 1596 with the (explicitly or implicitly set) context URI of the 1597 registration as the anchor. Links whose href or anchor was submitted 1598 as an absolute URI are returned with respective attributes 1599 unmodified. 1601 Above rules allow the client to interpret the response as links 1602 without any further knowledge of what the RD does. The Resource 1603 Directory MAY replace the contexts with a configured intermediate 1604 proxy, e.g. in the case of an HTTP lookup interface for CoAP 1605 endpoints. 1607 7.2. Endpoint and group lookup 1609 Endpoint and group lookups result in links to registration resources 1610 and group resources, respectively. Endpoint registration resources 1611 are annotated with their endpoint names (ep), domains (d, if 1612 present), context (con) and lifetime (lt, if present). Additional 1613 endpoint attributes are added as link attributes to their endpoint 1614 link unless their specification says otherwise. Group resources are 1615 annotated with their group names (gp), domain (d, if present) and 1616 multicast address (con, if present). 1618 While Endpoint Lookup does expose the registration resources, the RD 1619 does not need to make them accessible to clients. Clients SHOULD NOT 1620 attempt to dereference or manipulate them. 1622 A Resource Directory can report endpoints or groups in lookup that 1623 are not hosted at the same address. While the setup and management 1624 of such a distributed system is out of scope for this document, 1625 lookup clients MUST be prepared to see arbitrary URIs as registration 1626 or group resources in the results. 1628 For groups, a Resource Directory as specified here does not provide a 1629 lookup mechanism for the resources that can be accessed on a group's 1630 multicast address (ie. no lookup will return links like 1631 ";..." for a group registered 1632 with "con=coap://[ff35...]"). Such an additional lookup interface 1633 could be specified in an extension document. 1635 7.3. Lookup filtering 1637 Using the Accept Option, the requester can control whether the 1638 returned list is returned in CoRE Link Format ("application/link- 1639 format", default) or its alternate content-formats ("application/ 1640 link-format+json" or "application/link-format+cbor"). 1642 The page and count parameters are used to obtain lookup results in 1643 specified increments using pagination, where count specifies how many 1644 links to return and page specifies which subset of links organized in 1645 sequential pages, each containing 'count' links, starting with link 1646 zero and page zero. Thus, specifying count of 10 and page of 0 will 1647 return the first 10 links in the result set (links 0-9). Count = 10 1648 and page = 1 will return the next 'page' containing links 10-19, and 1649 so on. 1651 Multiple search criteria MAY be included in a lookup. All included 1652 criteria MUST match for a link to be returned. The Resource 1653 Directory MUST support matching with multiple search criteria. 1655 A link matches a search criterion if it has an attribute of the same 1656 name and the same value, allowing for a trailing "*" wildcard 1657 operator as in Section 4.1 of [RFC6690]. Attributes that are defined 1658 as "link-type" match if the search value matches any of their values 1659 (see Section 4.1 of [RFC6690]; eg. "?if=core.s" matches ";if="abc 1660 core.s";"). A link also matches a search criterion if the link that 1661 would be produced for any of its containing entities would match the 1662 criterion, or an entity contained in it would: A search criterion 1663 matches an endpoint if it matches the endpoint itself, any of the 1664 groups it is contained in or any resource it contains. A search 1665 criterion matches a resource if it matches the resource itself, the 1666 resource's endpoint, or any of the endpoint's groups. 1668 Note that "href" is also a valid search criterion and matches target 1669 references. Like all search criteria, on a resource lookup it can 1670 match the target reference of the resource link itself, but also the 1671 registration resource of the endpoint that registered it, or any 1672 group resource that endpoint is contained in. 1674 Clients that are interested in a lookup result repeatedly or 1675 continuously can use mechanisms like ETag caching, resource 1676 observation ([RFC7641]), or any future mechanism that might allow 1677 more efficient observations of collections. These are advertised, 1678 detected and used according to their own specifications and can be 1679 used with the lookup interface as with any other resource. 1681 When resource observation is used, every time the set of matching 1682 links changes, or the content of a matching link changes, the RD 1683 sends a notification with the matching link set. The notification 1684 contains the successful current response to the given request, 1685 especially with respect to representing zero matching links (see 1686 "Success" item below). 1688 The lookup interface is specified as follows: 1690 Interaction: Client -> RD 1692 Method: GET 1694 URI Template: {+type-lookup-location}{?page,count,search*} 1696 URI Template Variables: 1698 type-lookup-location := RD Lookup URI for a given lookup type 1699 (mandatory). The address is discovered as described in 1700 Section 5.2. 1702 search := Search criteria for limiting the number of results 1703 (optional). 1705 page := Page (optional). Parameter can not be used without the 1706 count parameter. Results are returned from result set in pages 1707 that contain 'count' links starting from index (page * count). 1708 Page numbering starts with zero. 1710 count := Count (optional). Number of results is limited to this 1711 parameter value. If the page parameter is also present, the 1712 response MUST only include 'count' links starting with the 1713 (page * count) link in the result set from the query. If the 1714 count parameter is not present, then the response MUST return 1715 all matching links in the result set. Link numbering starts 1716 with zero. 1718 Content-Format: application/link-format (optional) 1720 Content-Format: application/link-format+json (optional) 1721 Content-Format: application/link-format+cbor (optional) 1723 The following responses codes are defined for this interface: 1725 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1726 format", "application/link-format+cbor", or "application/link- 1727 format+json" payload containing matching entries for the lookup. 1728 The payload can contain zero links (which is an empty payload, 1729 "80" (hex) or "[]" in the respective content format), indicating 1730 that no entities matched the request. 1732 Failure: No error response to a multicast request. 1734 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1735 request. 1737 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1738 Service could not perform the operation. 1740 HTTP support: YES 1742 7.4. Lookup examples 1744 The examples in this section assume the existence of CoAP hosts with 1745 a default CoAP port 61616. HTTP hosts are possible and do not change 1746 the nature of the examples. 1748 The following example shows a client performing a resource lookup 1749 with the example resource look-up locations discovered in Figure 6: 1751 Req: GET /rd-lookup/res?rt=temperature 1753 Res: 2.05 Content 1754 ;rt="temperature";anchor="coap://[2001:db8:3::123]:61616" 1756 The same lookup using the CBOR Link Format media type: 1758 Req: GET /rd-lookup/res?rt=temperature 1759 Accept: TBD64 1761 Res: 2.05 Content 1762 Content-Format: TBD64 1763 Payload in Hex notation: 1764 81A3017823636F61703A2F2F5B323030313A6462383A333A3A3132335D3A36313631362F 1765 74656D7003781E636F61703A2F2F5B323030313A6462383A333A3A3132335D3A36313631 1766 36096B74656D7065726174757265 1767 Decoded payload: 1768 [{1: "coap://[2001:db8:3::123]:61616/temp", 9: "temperature", 1769 3: "coap://[2001:db8:3::123]:61616"}] 1771 A client that wants to be notified of new resources as they show up 1772 can use observation: 1774 Req: GET /rd-lookup/res?rt=light 1775 Observe: 0 1777 Res: 2.05 Content 1778 Observe: 23 1779 Payload: empty 1781 (at a later point in time) 1783 Res: 2.05 Content 1784 Observe: 24 1785 Payload: 1786 ;rt="light"; 1787 anchor="coap://[2001:db8:3::124]", 1788 ;rt="light"; 1789 anchor="coap://[2001:db8:3::124]", 1790 ;rt="light"; 1791 anchor="coap://[2001:db8:3::124]" 1793 The following example shows a client performing an endpoint type (et) 1794 lookup with the value oic.d.sensor (which is currently a registered 1795 rt value): 1797 Req: GET /rd-lookup/ep?et=oic.d.sensor 1799 Res: 2.05 Content 1800 ;con="coap://[2001:db8:3::127]:61616";ep="node5"; 1801 et="oic.d.sensor";ct="40";lt="600", 1802 ;con="coap://[2001:db8:3::129]:61616";ep="node7"; 1803 et="oic.d.sensor";ct="40";lt="600";d="floor-3" 1804 The following example shows a client performing a group lookup for 1805 all groups: 1807 Req: GET /rd-lookup/gp 1809 Res: 2.05 Content 1810 ;gp="lights1";d="example.com";con="coap://[ff35:30:2001:db8::1]", 1811 ;gp="lights2";d="example.com";con="coap://[ff35:30:2001:db8::2]" 1813 The following example shows a client performing a lookup for all 1814 endpoints in a particular group, with one endpoint hosted by another 1815 RD: 1817 Req: GET /rd-lookup/ep?gp=lights1 1819 Res: 2.05 Content 1820 ;con="coap://[2001:db8:3::123]:61616"; 1821 anchor="coap://[other-rd]";ep="node1";et="oic.d.sensor";ct="40";lt="600", 1822 ;con="coap://[2001:db8:3::124]:61616"; 1823 ep="node2";et="oic.d.sensor";ct="40";lt="600" 1825 The following example shows a client performing a lookup for all 1826 groups the endpoint "node1" belongs to: 1828 Req: GET /rd-lookup/gp?ep=node1 1830 Res: 2.05 Content 1831 ;gp="lights1" 1833 The following example shows a client performing a paginated resource 1834 lookup 1835 Req: GET /rd-lookup/res?page=0&count=5 1837 Res: 2.05 Content 1838 ;rt=sensor;ct=60; 1839 anchor="coap://[2001:db8:3::123]:61616", 1840 ;rt=sensor;ct=60; 1841 anchor="coap://[2001:db8:3::123]:61616", 1842 ;rt=sensor;ct=60; 1843 anchor="coap://[2001:db8:3::123]:61616", 1844 ;rt=sensor;ct=60; 1845 anchor="coap://[2001:db8:3::123]:61616", 1846 ;rt=sensor;ct=60; 1847 anchor="coap://[2001:db8:3::123]:61616" 1849 Req: GET /rd-lookup/res?page=1&count=5 1851 Res: 2.05 Content 1852 ;rt=sensor;ct=60; 1853 anchor="coap://[2001:db8:3::123]:61616", 1854 ;rt=sensor;ct=60; 1855 anchor="coap://[2001:db8:3::123]:61616", 1856 ;rt=sensor;ct=60; 1857 anchor="coap://[2001:db8:3::123]:61616", 1858 ;rt=sensor;ct=60; 1859 anchor="coap://[2001:db8:3::123]:61616", 1860 ;rt=sensor;ct=60; 1861 anchor="coap://[2001:db8:3::123]:61616" 1863 The following example shows a client performing a lookup of all 1864 resources from endpoints of all endpoints of a given endpoint type. 1865 It assumes that two endpoints (with endpoint names "sensor1" and 1866 "sensor2") have previously registered with their respective addresses 1867 "coap://sensor1.example.com" and "coap://sensor2.example.com", and 1868 posted the very payload of the 6th request of section 5 of [RFC6690]. 1870 It demonstrates how absolute link targets stay unmodified, while 1871 relative ones are resolved: 1873 Req: GET /rd-lookup/res?et=oic.d.sensor 1875 ;ct=40;title="Sensor Index"; 1876 anchor="coap://sensor1.example.com", 1877 ;rt="temperature-c";if="sensor"; 1878 anchor="coap://sensor1.example.com", 1879 ;rt="light-lux";if="sensor"; 1880 anchor="coap://sensor1.example.com", 1881 ;rel="describedby"; 1882 anchor="coap://sensor1.example.com/sensors/temp", 1883 ;rel="alternate"; 1884 anchor="coap://sensor1.example.com/sensors/temp", 1885 ;ct=40;title="Sensor Index"; 1886 anchor="coap://sensor2.example.com", 1887 ;rt="temperature-c";if="sensor"; 1888 anchor="coap://sensor2.example.com", 1889 ;rt="light-lux";if="sensor"; 1890 anchor="coap://sensor2.example.com", 1891 ;rel="describedby"; 1892 anchor="coap://sensor2.example.com/sensors/temp", 1893 ;rel="alternate"; 1894 anchor="coap://sensor2.example.com/sensors/temp" 1896 8. Security Considerations 1898 The security considerations as described in Section 7 of [RFC5988] 1899 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1900 may be protected e.g. using DTLS when hosted on a CoAP server as 1901 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1902 all resource directory interfaces defined in this document. 1904 8.1. Endpoint Identification and Authentication 1906 An Endpoint is determined to be unique within (the domain of) an RD 1907 by the Endpoint identifier parameter included during Registration, 1908 and any associated TLS or DTLS security bindings. An Endpoint MUST 1909 NOT be identified by its protocol, port or IP address as these may 1910 change over the lifetime of an Endpoint. 1912 Every operation performed by an Endpoint or Client on a resource 1913 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1914 Public Key or Certificate based security. 1916 Consider te following threat: two devices A and B are managed by a 1917 single server. Both devices have unique, per-device credentials for 1918 use with DTLS to make sure that only parties with authorization to 1919 access A or B can do so. 1921 Now, imagine that a malicious device A wants to sabotage the device 1922 B. It uses its credentials during the DTLS exchange. Then, it puts 1923 the endpoint name of device B. If the server does not check whether 1924 the identifier provided in the DTLS handshake matches the identifier 1925 used at the CoAP layer then it may be inclined to use the endpoint 1926 name for looking up what information to provision to the malicious 1927 device. 1929 Therfore, Endpoints MUST include the Endpoint identifier in the 1930 message, and this identifier MUST be checked by a resource directory 1931 to match the Endpoint identifier included in the Registration 1932 message. 1934 8.2. Access Control 1936 Access control SHOULD be performed separately for the RD 1937 registration, Lookup, and group API paths, as different endpoints may 1938 be authorized to register with an RD from those authorized to lookup 1939 endpoints from the RD. Such access control SHOULD be performed in as 1940 fine-grained a level as possible. For example access control for 1941 lookups could be performed either at the domain, endpoint or resource 1942 level. 1944 8.3. Denial of Service Attacks 1946 Services that run over UDP unprotected are vulnerable to unknowingly 1947 become part of a DDoS attack as UDP does not require return 1948 routability check. Therefore, an attacker can easily spoof the 1949 source IP of the target entity and send requests to such a service 1950 which would then respond to the target entity. This can be used for 1951 large-scale DDoS attacks on the target. Especially, if the service 1952 returns a response that is order of magnitudes larger than the 1953 request, the situation becomes even worse as now the attack can be 1954 amplified. DNS servers have been widely used for DDoS amplification 1955 attacks. There is also a danger that NTP Servers could become 1956 implicated in denial-of-service (DoS) attacks since they run on 1957 unprotected UDP, there is no return routability check, and they can 1958 have a large amplification factor. The responses from the NTP server 1959 were found to be 19 times larger than the request. A Resource 1960 Directory (RD) which responds to wild-card lookups is potentially 1961 vulnerable if run with CoAP over UDP. Since there is no return 1962 routability check and the responses can be significantly larger than 1963 requests, RDs can unknowingly become part of a DDoS amplification 1964 attack. 1966 9. IANA Considerations 1968 9.1. Resource Types 1970 "core.rd", "core.rd-group", "core.rd-lookup-ep", "core.rd-lookup- 1971 res", and "core.rd-lookup-gp" resource types need to be registered 1972 with the resource type registry defined by [RFC6690]. 1974 9.2. IPv6 ND Resource Directory Address Option 1976 This document registers one new ND option type under the subregistry 1977 "IPv6 Neighbor Discovery Option Formats": 1979 o Resource Directory address Option (38) 1981 9.3. RD Parameter Registry 1983 This specification defines a new sub-registry for registration and 1984 lookup parameters called "RD Parameters" under "CoRE Parameters". 1985 Although this specification defines a basic set of parameters, it is 1986 expected that other standards that make use of this interface will 1987 define new ones. 1989 Each entry in the registry must include 1991 o the human readable name of the parameter, 1993 o the short name as used in query parameters or link attributes, 1995 o indication of whether it can be passed as a query parameter at 1996 registration of endpoints or groups, as a query parameter in 1997 lookups, or be expressed as a link attribute, 1999 o validity requirements if any, and 2001 o a description. 2003 The query parameter MUST be both a valid URI query key [RFC3986] and 2004 a parmname as used in [RFC5988]. 2006 The description must give details on which registrations they apply 2007 to (Endpoint, group registrations or both? Can they be updated?), 2008 and how they are to be processed in lookups. 2010 The mechanisms around new RD parameters should be designed in such a 2011 way that they tolerate RD implementations that are unaware of the 2012 parameter and expose any parameter passed at registration or updates 2013 on in endpoint lookups. (For example, if a parameter used at 2014 registration were to be confidential, the registering endpoint should 2015 be instructed to only set that parameter if the RD advertises support 2016 for keeping it confidential at the discovery step.) 2018 Initial entries in this sub-registry are as follows: 2020 +----------+-------+---------------+-----+--------------------------+ 2021 | Full | Short | Validity | Use | Description | 2022 | name | | | | | 2023 +----------+-------+---------------+-----+--------------------------+ 2024 | Endpoint | ep | | RLA | Name of the endpoint, | 2025 | Name | | | | max 63 bytes | 2026 | Lifetime | lt | 60-4294967295 | RLA | Lifetime of the | 2027 | | | | | registration in seconds | 2028 | Domain | d | | RLA | Domain to which this | 2029 | | | | | endpoint belongs | 2030 | Context | con | URI | RLA | The scheme, address and | 2031 | | | | | port and path at which | 2032 | | | | | this server is available | 2033 | Group | gp | | RLA | Name of a group in the | 2034 | Name | | | | RD | 2035 | Page | page | Integer | L | Used for pagination | 2036 | Count | count | Integer | L | Used for pagination | 2037 | Endpoint | et | | RLA | Semantic name of the | 2038 | Type | | | | endpoint (see Section | 2039 | | | | | 9.4) | 2040 +----------+-------+---------------+-----+--------------------------+ 2042 Table 2: RD Parameters 2044 (Short: Short name used in query parameters or link attributes. Use: 2045 R = used at registration, L = used at lookup, A = expressed in link 2046 attribute 2048 The descriptions for the options defined in this document are only 2049 summarized here. To which registrations they apply and when they are 2050 to be shown is described in the respective sections of this document. 2052 The IANA policy for future additions to the sub-registry is "Expert 2053 Review" as described in [RFC8126]. The evaluation should consider 2054 formal criteria, duplication of functionality (Is the new entry 2055 redundant with an existing one?), topical suitability (Eg. is the 2056 described property actually a property of the endpoint and not a 2057 property of a particular resource, in which case it should go into 2058 the payload of the registration and need not be registered?), and the 2059 potential for conflict with commonly used link attributes (For 2060 example, "if" could be used as a parameter for conditional 2061 registration if it were not to be used in lookup or attributes, but 2062 would make a bad parameter for lookup, because a resource lookup with 2063 an "if" query parameter could ambiguously filter by the registered 2064 endpoint property or the [RFC6690] link attribute). It is expected 2065 that the registry will receive between 5 and 50 registrations in 2066 total over the next years. 2068 9.3.1. Full description of the "Endpoint Type" Registration Parameter 2070 An endpoint registering at an RD can describe itself with endpoint 2071 types, similar to how resources are described with Resource Types in 2072 [RFC6690]. An endpoint type is expressed as a string, which can be 2073 either a URI or one of the values defined in the Endpoint Type 2074 subregistry. Endpoint types can be passed in the "et" query 2075 parameter as part of extra-attrs at the Registration step, are shown 2076 on endpoint lookups using the "et" target attribute, and can be 2077 filtered for using "et" as a search criterion in resource and 2078 endpoint lookup. Multiple endpoint types are given as separate query 2079 parameters or link attributes. 2081 Note that Endpoint Type differs from Resource Type in that it uses 2082 multiple attributes rather than space separated values. As a result, 2083 Resource Directory implementations automatically support correct 2084 filtering in the lookup interfaces from the rules for unknown 2085 endpoint attributes. 2087 9.4. "Endpoint Type" (et=) RD Parameter values 2089 This specification establishes a new sub-registry under "CoRE 2090 Parameters" called '"Endpoint Type" (et=) RD Parameter values'. The 2091 registry properties (required policy, requirements, template) are 2092 identical to those of the Resource Type parameters in [RFC6690], in 2093 short: 2095 The review policy is IETF Review for values starting with "core", and 2096 Specification Required for others. 2098 The requirements to be enforced are: 2100 o The values MUST be related to the purpose described in 2101 Section 9.3.1. 2103 o The registered values MUST conform to the ABNF reg-rel-type 2104 definition of [RFC6690] and MUST NOT be a URI. 2106 o It is recommended to use the period "." character for 2107 segmentation. 2109 The registry is initially empty. 2111 9.5. Multicast Address Registration 2113 IANA has assigned the following multicast addresses for use by CoAP 2114 nodes: 2116 IPv4 - "all CoRE resource directories" address, from the "IPv4 2117 Multicast Address Space Registry" equal to "All CoAP Nodes", 2118 224.0.1.187. As the address is used for discovery that may span 2119 beyond a single network, it has come from the Internetwork Control 2120 Block (224.0.1.x, RFC 5771). 2122 IPv6 - "all CoRE resource directories" address MCD1 (uggestions 2123 FF0X::FE), from the "IPv6 Multicast Address Space Registry", in the 2124 "Variable Scope Multicast Addresses" space (RFC 3307). Note that 2125 there is a distinct multicast address for each scope that interested 2126 CoAP nodes should listen to; CoAP needs the Link-Local and Site-Local 2127 scopes only. 2129 10. Examples 2131 Two examples are presented: a Lighting Installation example in 2132 Section 10.1 and a LWM2M example in Section 10.2. 2134 10.1. Lighting Installation 2136 This example shows a simplified lighting installation which makes use 2137 of the Resource Directory (RD) with a CoAP interface to facilitate 2138 the installation and start up of the application code in the lights 2139 and sensors. In particular, the example leads to the definition of a 2140 group and the enabling of the corresponding multicast address. No 2141 conclusions must be drawn on the realization of actual installation 2142 or naming procedures, because the example only "emphasizes" some of 2143 the issues that may influence the use of the RD and does not pretend 2144 to be normative. 2146 10.1.1. Installation Characteristics 2148 The example assumes that the installation is managed. That means 2149 that a Commissioning Tool (CT) is used to authorize the addition of 2150 nodes, name them, and name their services. The CT can be connected 2151 to the installation in many ways: the CT can be part of the 2152 installation network, connected by WiFi to the installation network, 2153 or connected via GPRS link, or other method. 2155 It is assumed that there are two naming authorities for the 2156 installation: (1) the network manager that is responsible for the 2157 correct operation of the network and the connected interfaces, and 2158 (2) the lighting manager that is responsible for the correct 2159 functioning of networked lights and sensors. The result is the 2160 existence of two naming schemes coming from the two managing 2161 entities. 2163 The example installation consists of one presence sensor, and two 2164 luminaries, luminary1 and luminary2, each with their own wireless 2165 interface. Each luminary contains three lamps: left, right and 2166 middle. Each luminary is accessible through one endpoint. For each 2167 lamp a resource exists to modify the settings of a lamp in a 2168 luminary. The purpose of the installation is that the presence 2169 sensor notifies the presence of persons to a group of lamps. The 2170 group of lamps consists of: middle and left lamps of luminary1 and 2171 right lamp of luminary2. 2173 Before commissioning by the lighting manager, the network is 2174 installed and access to the interfaces is proven to work by the 2175 network manager. 2177 At the moment of installation, the network under installation is not 2178 necessarily connected to the DNS infra structure. Therefore, SLAAC 2179 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 2180 Table 3 below: 2182 +--------------------+----------------+ 2183 | Name | IPv6 address | 2184 +--------------------+----------------+ 2185 | luminary1 | 2001:db8:4::1 | 2186 | luminary2 | 2001:db8:4::2 | 2187 | Presence sensor | 2001:db8:4::3 | 2188 | Resource directory | 2001:db8:4::ff | 2189 +--------------------+----------------+ 2191 Table 3: interface SLAAC addresses 2193 In Section 10.1.2 the use of resource directory during installation 2194 is presented. 2196 10.1.2. RD entries 2198 It is assumed that access to the DNS infrastructure is not always 2199 possible during installation. Therefore, the SLAAC addresses are 2200 used in this section. 2202 For discovery, the resource types (rt) of the devices are important. 2203 The lamps in the luminaries have rt: light, and the presence sensor 2204 has rt: p-sensor. The endpoints have names which are relevant to the 2205 light installation manager. In this case luminary1, luminary2, and 2206 the presence sensor are located in room 2-4-015, where luminary1 is 2207 located at the window and luminary2 and the presence sensor are 2208 located at the door. The endpoint names reflect this physical 2209 location. The middle, left and right lamps are accessed via path 2210 /light/middle, /light/left, and /light/right respectively. The 2211 identifiers relevant to the Resource Directory are shown in Table 4 2212 below: 2214 +----------------+------------------+---------------+---------------+ 2215 | Name | endpoint | resource path | resource type | 2216 +----------------+------------------+---------------+---------------+ 2217 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 2218 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 2219 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 2220 | luminary2 | lm_R2-4-015_door | /light/left | light | 2221 | luminary2 | lm_R2-4-015_door | /light/middle | light | 2222 | luminary2 | lm_R2-4-015_door | /light/right | light | 2223 | Presence | ps_R2-4-015_door | /ps | p-sensor | 2224 | sensor | | | | 2225 +----------------+------------------+---------------+---------------+ 2227 Table 4: Resource Directory identifiers 2229 It is assumed that the CT knows the RD's address, and has performed 2230 URI discovery on it that returned a response like the one in the 2231 Section 5.2 example. 2233 The CT inserts the endpoints of the luminaries and the sensor in the 2234 RD using the Context parameter (con) to specify the interface 2235 address: 2237 Req: POST coap://[2001:db8:4::ff]/rd 2238 ?ep=lm_R2-4-015_wndw&con=coap://[2001:db8:4::1]&d=R2-4-015 2239 Payload: 2240 ;rt="light", 2241 ;rt="light", 2242 ;rt="light" 2244 Res: 2.01 Created 2245 Location: /rd/4521 2246 Req: POST coap://[2001:db8:4::ff]/rd 2247 ?ep=lm_R2-4-015_door&con=coap://[2001:db8:4::2]&d=R2-4-015 2248 Payload: 2249 ;rt="light", 2250 ;rt="light", 2251 ;rt="light" 2253 Res: 2.01 Created 2254 Location: /rd/4522 2256 Req: POST coap://[2001:db8:4::ff]/rd 2257 ?ep=ps_R2-4-015_door&con=coap://[2001:db8:4::3]d&d=R2-4-015 2258 Payload: 2259 ;rt="p-sensor" 2261 Res: 2.01 Created 2262 Location: /rd/4523 2264 The domain name d=R2-4-015 has been added for an efficient lookup 2265 because filtering on "ep" name is more awkward. The same domain name 2266 is communicated to the two luminaries and the presence sensor by the 2267 CT. 2269 The group is specified in the RD. The Context parameter is set to 2270 the site-local multicast address allocated to the group. In the POST 2271 in the example below, these two endpoints and the endpoint of the 2272 presence sensor are registered as members of the group. 2274 Req: POST coap://[2001:db8:4::ff]/rd-group 2275 ?gp=grp_R2-4-015&con=coap://[ff05::1] 2276 Payload: 2277 , 2278 , 2279 2281 Res: 2.01 Created 2282 Location: /rd-group/501 2284 After the filling of the RD by the CT, the application in the 2285 luminaries can learn to which groups they belong, and enable their 2286 interface for the multicast address. 2288 The luminary, knowing its domain, queries the RD for the endpoint 2289 with rt=light and d=R2-4-015. The RD returns all endpoints in the 2290 domain. 2292 Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep 2293 ?d=R2-4-015&rt=light 2295 Res: 2.05 Content 2296 ;con="coap://[2001:db8:4::1]"; 2297 ep="lm_R2-4-015_wndw", 2298 ;con="coap://[2001:db8:4::2]"; 2299 ep="lm_R2-4-015_door" 2301 Knowing its own IPv6 address, the luminary discovers its endpoint 2302 name. With the endpoint name the luminary queries the RD for all 2303 groups to which the endpoint belongs. 2305 Req: GET coap://[2001:db8:4::ff]/rd-lookup/gp 2306 ?ep=lm_R2-4-015_wndw 2308 Res: 2.05 Content 2309 ;gp="grp_R2-4-015";con="coap://[ff05::1]" 2311 From the context parameter value, the luminary learns the multicast 2312 address of the multicast group. 2314 Alternatively, the CT can communicate the multicast address directly 2315 to the luminaries by using the "coap-group" resource specified in 2316 [RFC7390]. 2318 Req: POST coap://[2001:db8:4::1]/coap-group 2319 Content-Format: application/coap-group+json 2320 Payload: 2321 { "a": "[ff05::1]", "n": "grp_R2-4-015"} 2323 Res: 2.01 Created 2324 Location-Path: /coap-group/1 2326 Dependent on the situation, only the address, "a", or the name, "n", 2327 is specified in the coap-group resource. 2329 10.2. OMA Lightweight M2M (LWM2M) Example 2331 This example shows how the OMA LWM2M specification makes use of 2332 Resource Directory (RD). 2334 OMA LWM2M is a profile for device services based on CoAP(OMA Name 2335 Authority). LWM2M defines a simple object model and a number of 2336 abstract interfaces and operations for device management and device 2337 service enablement. 2339 An LWM2M server is an instance of an LWM2M middleware service layer, 2340 containing a Resource Directory along with other LWM2M interfaces 2341 defined by the LWM2M specification. 2343 CoRE Resource Directory (RD) is used to provide the LWM2M 2344 Registration interface. 2346 LWM2M does not provide for registration domains and does not 2347 currently use the rd-group or rd-lookup interfaces. 2349 The LWM2M specification describes a set of interfaces and a resource 2350 model used between a LWM2M device and an LWM2M server. Other 2351 interfaces, proxies, and applications are currently out of scope for 2352 LWM2M. 2354 The location of the LWM2M Server and RD URI path is provided by the 2355 LWM2M Bootstrap process, so no dynamic discovery of the RD is used. 2356 LWM2M Servers and endpoints are not required to implement the /.well- 2357 known/core resource. 2359 10.2.1. The LWM2M Object Model 2361 The OMA LWM2M object model is based on a simple 2 level class 2362 hierarchy consisting of Objects and Resources. 2364 An LWM2M Resource is a REST endpoint, allowed to be a single value or 2365 an array of values of the same data type. 2367 An LWM2M Object is a resource template and container type that 2368 encapsulates a set of related resources. An LWM2M Object represents 2369 a specific type of information source; for example, there is a LWM2M 2370 Device Management object that represents a network connection, 2371 containing resources that represent individual properties like radio 2372 signal strength. 2374 Since there may potentially be more than one of a given type object, 2375 for example more than one network connection, LWM2M defines instances 2376 of objects that contain the resources that represent a specific 2377 physical thing. 2379 The URI template for LWM2M consists of a base URI followed by Object, 2380 Instance, and Resource IDs: 2382 {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- 2383 instance} 2385 The five variables given here are strings. base-uri can also have 2386 the special value "undefined" (sometimes called "null" in RFC 6570). 2388 Each of the variables object-instance, resource-id, and resource- 2389 instance can be the special value "undefined" only if the values 2390 behind it in this sequence also are "undefined". As a special case, 2391 object-instance can be "empty" (which is different from "undefined") 2392 if resource-id is not "undefined". 2394 base-uri := Base URI for LWM2M resources or "undefined" for default 2395 (empty) base URI 2397 object-id := OMNA (OMA Name Authority) registered object ID (0-65535) 2399 object-instance := Object instance identifier (0-65535) or 2400 "undefined"/"empty" (see above)) to refer to all instances of an 2401 object ID 2403 resource-id := OMNA (OMA Name Authority) registered resource ID 2404 (0-65535) or "undefined" to refer to all resources within an instance 2406 resource-instance := Resource instance identifier or "undefined" to 2407 refer to single instance of a resource 2409 LWM2M IDs are 16 bit unsigned integers represented in decimal (no 2410 leading zeroes except for the value 0) by URI format strings. For 2411 example, a LWM2M URI might be: 2413 /1/0/1 2415 The base uri is empty, the Object ID is 1, the instance ID is 0, the 2416 resource ID is 1, and the resource instance is "undefined". This 2417 example URI points to internal resource 1, which represents the 2418 registration lifetime configured, in instance 0 of a type 1 object 2419 (LWM2M Server Object). 2421 10.2.2. LWM2M Register Endpoint 2423 LWM2M defines a registration interface based on the REST API, 2424 described in Section 5. The RD registration URI path of the LWM2M 2425 Resource Directory is specified to be "/rd". 2427 LWM2M endpoints register object IDs, for example , to indicate 2428 that a particular object type is supported, and register object 2429 instances, for example , to indicate that a particular instance 2430 of that object type exists. 2432 Resources within the LWM2M object instance are not registered with 2433 the RD, but may be discovered by reading the resource links from the 2434 object instance using GET with a CoAP Content-Format of application/ 2435 link-format. Resources may also be read as a structured object by 2436 performing a GET to the object instance with a Content-Format of 2437 senml+json. 2439 When an LWM2M object or instance is registered, this indicates to the 2440 LWM2M server that the object and its resources are available for 2441 management and service enablement (REST API) operations. 2443 LWM2M endpoints may use the following RD registration parameters as 2444 defined in Table 2 : 2446 ep - Endpoint Name 2447 lt - registration lifetime 2449 Endpoint Name, Lifetime, and LWM2M Version are mandatory parameters 2450 for the register operation, all other registration parameters are 2451 optional. 2453 Additional optional LWM2M registration parameters are defined: 2455 +-----------+-------+-------------------------------+---------------+ 2456 | Name | Query | Validity | Description | 2457 +-----------+-------+-------------------------------+---------------+ 2458 | Binding | b | {"U",UQ","S","SQ","US","UQS"} | Available | 2459 | Mode | | | Protocols | 2460 | | | | | 2461 | LWM2M | ver | 1.0 | Spec Version | 2462 | Version | | | | 2463 | | | | | 2464 | SMS | sms | | MSISDN | 2465 | Number | | | | 2466 +-----------+-------+-------------------------------+---------------+ 2468 Table 5: LWM2M Additional Registration Parameters 2470 The following RD registration parameters are not currently specified 2471 for use in LWM2M: 2473 et - Endpoint Type 2474 con - Context 2476 The endpoint registration must include a payload containing links to 2477 all supported objects and existing object instances, optionally 2478 including the appropriate link-format relations. 2480 Here is an example LWM2M registration payload: 2482 ,,, 2483 This link format payload indicates that object ID 1 (LWM2M Server 2484 Object) is supported, with a single instance 0 existing, object ID 3 2485 (LWM2M Device object) is supported, with a single instance 0 2486 existing, and object 5 (LWM2M Firmware Object) is supported, with no 2487 existing instances. 2489 10.2.3. LWM2M Update Endpoint Registration 2491 The LwM2M update is really very similar to the registration update as 2492 described in Section 5.4.1, with the only difference that there are 2493 more parameters defined and available. All the parameters listed in 2494 that section are also available with the initial registration but are 2495 all optional: 2497 lt - Registration Lifetime 2498 b - Protocol Binding 2499 sms - MSISDN 2500 link payload - new or modified links 2502 A Registration update is also specified to be used to update the 2503 LWM2M server whenever the endpoint's UDP port or IP address are 2504 changed. 2506 10.2.4. LWM2M De-Register Endpoint 2508 LWM2M allows for de-registration using the delete method on the 2509 returned location from the initial registration operation. LWM2M de- 2510 registration proceeds as described in Section 5.4.2. 2512 11. Acknowledgments 2514 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2515 Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, 2516 Hannes Tschofenig, Sampo Ukkola, Linyi Tian, and Jan Newmarch have 2517 provided helpful comments, discussions and ideas to improve and shape 2518 this document. Zach would also like to thank his colleagues from the 2519 EU FP7 SENSEI project, where many of the resource directory concepts 2520 were originally developed. 2522 12. Changelog 2524 changes from -12 to -13 2526 o Added "all resource directory" nodes MC address 2528 o Clarified observation behavior 2530 o version identification 2531 o example rt= and et= values 2533 o domain from figure 2 2535 o more explanatory text 2537 o endpoints of a groups hosted by different RD 2539 o resolve RFC6690-vs-8288 resolution ambiguities: 2541 * require registered links not to be relative when using anchor 2543 * return absolute URIs in resource lookup 2545 changes from -11 to -12 2547 o added Content Model section, including ER diagram 2549 o removed domain lookup interface; domains are now plain attributes 2550 of groups and endpoints 2552 o updated chapter "Finding a Resource Directory"; now distinguishes 2553 configuration-provided, network-provided and heuristic sources 2555 o improved text on: atomicity, idempotency, lookup with multiple 2556 parameters, endpoint removal, simple registration 2558 o updated LWM2M description 2560 o clarified where relative references are resolved, and how context 2561 and anchor interact 2563 o new appendix on the interaction with RFCs 6690, 5988 and 3986 2565 o lookup interface: group and endpoint lookup return group and 2566 registration resources as link targets 2568 o lookup interface: search parameters work the same across all 2569 entities 2571 o removed all methods that modify links in an existing registration 2572 (POST with payload, PATCH and iPATCH) 2574 o removed plurality definition (was only needed for link 2575 modification) 2577 o enhanced IANA registry text 2578 o state that lookup resources can be observable 2580 o More examples and improved text 2582 changes from -09 to -10 2584 o removed "ins" and "exp" link-format extensions. 2586 o removed all text concerning DNS-SD. 2588 o removed inconsistency in RDAO text. 2590 o suggestions taken over from various sources 2592 o replaced "Function Set" with "REST API", "base URI", "base path" 2594 o moved simple registration to registration section 2596 changes from -08 to -09 2598 o clarified the "example use" of the base RD resource values /rd, 2599 /rd-lookup, and /rd-group. 2601 o changed "ins" ABNF notation. 2603 o various editorial improvements, including in examples 2605 o clarifications for RDAO 2607 changes from -07 to -08 2609 o removed link target value returned from domain and group lookup 2610 types 2612 o Maximum length of domain parameter 63 bytes for consistency with 2613 group 2615 o removed option for simple POST of link data, don't require a 2616 .well-known/core resource to accept POST data and handle it in a 2617 special way; we already have /rd for that 2619 o add IPv6 ND Option for discovery of an RD 2621 o clarify group configuration section 6.1 that endpoints must be 2622 registered before including them in a group 2624 o removed all superfluous client-server diagrams 2625 o simplified lighting example 2627 o introduced Commissioning Tool 2629 o RD-Look-up text is extended. 2631 changes from -06 to -07 2633 o added text in the discovery section to allow content format hints 2634 to be exposed in the discovery link attributes 2636 o editorial updates to section 9 2638 o update author information 2640 o minor text corrections 2642 Changes from -05 to -06 2644 o added note that the PATCH section is contingent on the progress of 2645 the PATCH method 2647 changes from -04 to -05 2649 o added Update Endpoint Links using PATCH 2651 o http access made explicit in interface specification 2653 o Added http examples 2655 Changes from -03 to -04: 2657 o Added http response codes 2659 o Clarified endpoint name usage 2661 o Add application/link-format+cbor content-format 2663 Changes from -02 to -03: 2665 o Added an example for lighting and DNS integration 2667 o Added an example for RD use in OMA LWM2M 2669 o Added Read Links operation for link inspection by endpoints 2671 o Expanded DNS-SD section 2672 o Added draft authors Peter van der Stok and Michael Koster 2674 Changes from -01 to -02: 2676 o Added a catalogue use case. 2678 o Changed the registration update to a POST with optional link 2679 format payload. Removed the endpoint type update from the update. 2681 o Additional examples section added for more complex use cases. 2683 o New DNS-SD mapping section. 2685 o Added text on endpoint identification and authentication. 2687 o Error code 4.04 added to Registration Update and Delete requests. 2689 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 2690 resource type parameters. 2692 Changes from -00 to -01: 2694 o Removed the ETag validation feature. 2696 o Place holder for the DNS-SD mapping section. 2698 o Explicitly disabled GET or POST on returned Location. 2700 o New registry for RD parameters. 2702 o Added support for the JSON Link Format. 2704 o Added reference to the Groupcomm WG draft. 2706 Changes from -05 to WG Document -00: 2708 o Updated the version and date. 2710 Changes from -04 to -05: 2712 o Restricted Update to parameter updates. 2714 o Added pagination support for the Lookup interface. 2716 o Minor editing, bug fixes and reference updates. 2718 o Added group support. 2720 o Changed rt to et for the registration and update interface. 2722 Changes from -03 to -04: 2724 o Added the ins= parameter back for the DNS-SD mapping. 2726 o Integrated the Simple Directory Discovery from Carsten. 2728 o Editorial improvements. 2730 o Fixed the use of ETags. 2732 o Fixed tickets 383 and 372 2734 Changes from -02 to -03: 2736 o Changed the endpoint name back to a single registration parameter 2737 ep= and removed the h= and ins= parameters. 2739 o Updated REST interface descriptions to use RFC6570 URI Template 2740 format. 2742 o Introduced an improved RD Lookup design as its own function set. 2744 o Improved the security considerations section. 2746 o Made the POST registration interface idempotent by requiring the 2747 ep= parameter to be present. 2749 Changes from -01 to -02: 2751 o Added a terminology section. 2753 o Changed the inclusion of an ETag in registration or update to a 2754 MAY. 2756 o Added the concept of an RD Domain and a registration parameter for 2757 it. 2759 o Recommended the Location returned from a registration to be 2760 stable, allowing for endpoint and Domain information to be changed 2761 during updates. 2763 o Changed the lookup interface to accept endpoint and Domain as 2764 query string parameters to control the scope of a lookup. 2766 13. References 2768 13.1. Normative References 2770 [I-D.ietf-core-links-json] 2771 Li, K., Rahman, A., and C. Bormann, "Representing 2772 Constrained RESTful Environments (CoRE) Link Format in 2773 JSON and CBOR", draft-ietf-core-links-json-10 (work in 2774 progress), February 2018. 2776 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2777 Requirement Levels", BCP 14, RFC 2119, 2778 DOI 10.17487/RFC2119, March 1997, 2779 . 2781 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2782 Resource Identifier (URI): Generic Syntax", STD 66, 2783 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2784 . 2786 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2787 DOI 10.17487/RFC5988, October 2010, 2788 . 2790 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2791 and D. Orchard, "URI Template", RFC 6570, 2792 DOI 10.17487/RFC6570, March 2012, 2793 . 2795 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2796 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2797 . 2799 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2800 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2801 . 2803 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2804 Writing an IANA Considerations Section in RFCs", BCP 26, 2805 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2806 . 2808 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2809 FETCH Methods for the Constrained Application Protocol 2810 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2811 . 2813 13.2. Informative References 2815 [ER] Chen, P., "The entity-relationship model---toward a 2816 unified view of data", ACM Transactions on Database 2817 Systems Vol. 1, pp. 9-36, DOI 10.1145/320434.320440, March 2818 1976. 2820 [I-D.arkko-core-dev-urn] 2821 Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 2822 Names for Device Identifiers", draft-arkko-core-dev-urn-05 2823 (work in progress), October 2017. 2825 [I-D.bormann-t2trg-rel-impl] 2826 Bormann, C., "impl-info: A link relation type for 2827 disclosing implementation information", draft-bormann- 2828 t2trg-rel-impl-00 (work in progress), January 2018. 2830 [I-D.silverajan-core-coap-protocol-negotiation] 2831 Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation", 2832 draft-silverajan-core-coap-protocol-negotiation-07 (work 2833 in progress), October 2017. 2835 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2836 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2837 Transfer Protocol -- HTTP/1.1", RFC 2616, 2838 DOI 10.17487/RFC2616, June 1999, 2839 . 2841 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 2842 Bormann, "Neighbor Discovery Optimization for IPv6 over 2843 Low-Power Wireless Personal Area Networks (6LoWPANs)", 2844 RFC 6775, DOI 10.17487/RFC6775, November 2012, 2845 . 2847 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2848 Protocol (HTTP/1.1): Message Syntax and Routing", 2849 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2850 . 2852 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2853 Application Protocol (CoAP)", RFC 7252, 2854 DOI 10.17487/RFC7252, June 2014, 2855 . 2857 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2858 the Constrained Application Protocol (CoAP)", RFC 7390, 2859 DOI 10.17487/RFC7390, October 2014, 2860 . 2862 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2863 Application Protocol (CoAP)", RFC 7641, 2864 DOI 10.17487/RFC7641, September 2015, 2865 . 2867 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2868 DOI 10.17487/RFC8288, October 2017, 2869 . 2871 Appendix A. Web links and the Resource Directory 2873 Understanding the semantics of a link-format document and its URI 2874 references is a journey through different documents ([RFC3986] 2875 defining URIs, [RFC6690] defining link-format documents based on 2876 [RFC8288] which defines link headers, and [RFC7252] providing the 2877 transport). This appendix summarizes the mechanisms and semantics at 2878 play from an entry in ".well-known/core" to a resource lookup. 2880 This text is primarily aimed at people entering the field of 2881 Constrained Restful Environments from applications that previously 2882 did not use web mechanisms. 2884 A.1. A simple example 2886 Let's start this example with a very simple host, "2001:db8:f0::1". 2887 A client that follows classical CoAP Discovery ([RFC7252] Section 7), 2888 sends the following multicast request to learn about neighbours 2889 supporting resources with resource-type "temperature". 2891 The client sends a link-local multicast: 2893 GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature 2895 RES 2.05 Content 2896 ;rt=temperature;ct=0 2898 where the response is sent by the server, "[2001:db8:f0::1]:5683". 2900 While the client - on the practical or implementation side - can just 2901 go ahead and create a new request to "[2001:db8:f0::1]:5683" with 2902 Uri-Path: "temp", the full resolution steps without any shortcuts 2903 are: 2905 A.1.1. Resolving the URIs 2907 The client parses the single returned record. The link's target 2908 (sometimes called "href") is ""/temp"", which is a relative URI that 2909 needs resolving. As long as all involved links follow the 2910 restrictions set forth for this document (see Appendix A.4), the base 2911 URI to resolve this against the requested URI. 2913 The URI of the requested resource can be composed by following the 2914 steps of [RFC7252] section 6.5 (with an addition at the end of 8.2) 2915 into ""coap://[2001:db8:f0::1]/.well-known/core"". 2917 The record's target is resolved by replacing the path ""/.well-known/ 2918 core"" from the Base URI (section 5.2 [RFC3986]) with the relative 2919 target URI ""/temp"" into ""coap://[2001:db8:f0::1]/temp"". 2921 A.1.2. Interpreting attributes and relations 2923 Some more information but the record's target can be obtained from 2924 the payload: the resource type of the target is "temperature", and 2925 its content type is text/plain (ct=0). 2927 A relation in a web link is a three-part statement that the context 2928 resource has a named relation to the target resource, like "_This 2929 page_ has _its table of contents_ at _/toc.html_". In [RFC6690] 2930 link-format documents, there is an implicit "host relation" specified 2931 with default parameter: rel="hosts". 2933 In our example, the context of the link is the URI of the requested 2934 document itself. A full English expression of the "host relation" 2935 is: 2937 '"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource 2938 "coap://[2001:db8:f0::1]/temp", which is of the resource type 2939 "temperature" and can be accessed using the text/plain content 2940 format.' 2942 A.2. A slightly more complex example 2944 Omitting the "rt=temperature" filter, the discovery query would have 2945 given some more records in the payload: 2947 ;rt=temperature;ct=0, 2948 ;rt=light-lux;ct=0, 2949 ;anchor="/sensors/temp";rel=alternate, 2950 ;anchor="/sensors/temp"; 2951 rel="describedby" 2953 Parsing the third record, the client encounters the "anchor" 2954 parameter. It is a URI relative to the document's Base URI and is 2955 thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That is 2956 the context resource of the link, so the "rel" statement is not about 2957 the target and the document Base URI any more, but about the target 2958 and that address. 2960 Thus, the third record could be read as 2961 ""coap://[2001:db8:f0::1]/sensors/temp" has an alternate 2962 representation at "coap://[2001:db8:f0::1]/t"". 2964 The fourth record can be read as ""coap://[2001:db8:f0::1]/sensors/ 2965 temp" is described by "http://www.example.com/sensors/t123"". 2967 A.3. Enter the Resource Directory 2969 The resource directory tries to carry the semantics obtainable by 2970 classical CoAP discovery over to the resource lookup interface as 2971 faithfully as possible. 2973 For the following queries, we will assume that the simple host has 2974 used Simple Registration to register at the resource directory that 2975 was announced to it, sending this request from its UDP port 2976 "[2001:db8:f0::1]:6553": 2978 POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1 2980 The resource directory would have accepted the registration, and 2981 queried the simple host's ".well-known/core" by itself. As a result, 2982 the host is registered as an endpoint in the RD with the name 2983 "simple-host1". The registration is active for 86400 seconds, and 2984 the endpoint registration Base URI is ""coap://[2001:db8:f0::1]/"" 2985 because that is the address the registration was sent from (and no 2986 explicit "con=" was given). 2988 If the client now queries the RD as it would previously have issued a 2989 multicast request, it would go through the RD discovery steps by 2990 fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- 2991 lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the 2992 resource lookup endpoint, and issue a request to 2993 "coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive 2994 the following data: 2996 ;rt=temperature;ct=0; 2997 anchor="coap://[2001:db8:f0::1]" 2999 This is not _literally_ the same response that it would have received 3000 from a multicast request, but it would contain the (almost) same 3001 statement: 3003 '"coap://[2001:db8:f0::1]" is hosting the resource 3004 "coap://[2001:db8:f0::1]/temp", which is of the resource type 3005 "temperature" and can be accessed using the text/plain content 3006 format.' 3008 (The difference is whether "/" or "/.well-known/core" hosts the 3009 resources, which is subject of ongoing discussion about RFC6690). 3011 To complete the examples, the client could also query all resources 3012 hosted at the endpoint with the known endpoint name "simple-host1". 3013 A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1" 3014 would return 3016 ;rt=temperature;ct=0; 3017 anchor="coap://[2001:db8:f0::1]", 3018 ;rt=light-lux;ct=0; 3019 anchor="coap://[2001:db8:f0::1]", 3020 ; 3021 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, 3022 ; 3023 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby" 3025 All the target and anchor references are already in absolute form 3026 there, which don't need to be resolved any further. 3028 Had the simple host registered with an explicit context (eg. 3029 "?ep=simple-host1&con=coap+tcp://simple-host1.example.com"), that 3030 context would have been used to resolve the relative anchor values 3031 instead, giving 3033 ;rt=temperature;ct=0; 3034 anchor="coap+tcp://simple-host1.example.com" 3036 and analogous records. 3038 A.4. A note on differences between link-format and Link headers 3040 While link-format and Link headers look very similar and are based on 3041 the same model of typed links, there are some differences between 3042 [RFC6690] and [RFC5988], which are dealt with differently: 3044 o "Resolving the target against the anchor": [RFC6690] Section 2.1 3045 states that the anchor of a link uses the Base URI against which 3046 the term inside the angle brackets (the target) is resolved. 3047 [RFC8288] Section B.2 describes that the anchor is immaterial to 3048 the resolution of the target reference. 3050 In the context of a Resource Directory, the authors decided not to 3051 not let this become an issue by requiring that RFC6690 links be 3052 serialized in a way that either rule set can be applied and give 3053 the same results. Note that all examples of [RFC6690], [RFC8288] 3054 and this document comply with that rule. 3056 Applications that would prefer to transport references with a 3057 relative target and an absolute anchor are advised to use a 3058 different serialization of the links. [I-D.ietf-core-links-json] 3059 might provide such formats. 3061 o There is no percent encoding in link-format documents. 3063 A link-format document is a UTF-8 encoded string of Unicode 3064 characters and does not have percent encoding, while Link headers 3065 are practically ASCII strings that use percent encoding for non- 3066 ASCII characters, stating the encoding explictly when required. 3068 For example, while a Link header in a page about a Swedish city 3069 might read 3071 "Link: ;rel="live-environment-data"" 3073 a link-format document from the same source might describe the 3074 link as 3076 ";rel="live-environment-data"" 3078 Parsers and producers of link-format and header data need to be 3079 aware of this difference. 3081 Appendix B. Syntax examples for Protocol Negotiation 3083 [ This appendix should not show up in a published version of this 3084 document. ] 3086 The protocol negotiation that is being worked on in 3087 [I-D.silverajan-core-coap-protocol-negotiation] makes use of the 3088 Resource Directory. 3090 Until that document is update to use the latest resource-directory 3091 specification, here are some examples of protocol negotiation with 3092 the current Resource Directory: 3094 An endpoint could register as follows from its address 3095 "[2001:db8:f1::2]:5683": 3097 Req: POST coap://rd.example.com/rd?ep=node1 3098 &at=coap+tcp://[2001:db8:f1::2] 3099 Content-Format: 40 3100 Payload: 3101 ;ct=0;rt="temperature";if="core.s" 3103 Res: 2.01 Created 3104 Location: /rd/1234 3106 An endpoint lookup would just reflect the registered attributes: 3108 Req: GET /rd-lookup/ep 3110 Res: 2.05 Content 3111 ;ep="node1";con="coap://[2001:db8:f1::2]:5683"; 3112 at="coap+tcp://[2001:db8:f1::2]" 3114 A UDP client would then see the following in a resource lookup: 3116 Req: GET /rd-lookup/res?rt=temperature 3118 Res: 2.05 Content 3119 ;ct=0;rt="temperature";if="core.s"; 3120 anchor="coap://[2001:db8:f1::2]" 3122 while a TCP capable client could say: 3124 Req: GET /rd-lookup/res?rt=temperature&tt=tcp 3126 Res: 2.05 Content 3127 ;ct=0;rt="temperature"; 3128 if="core.s";anchor="coap+tcp://[2001:db8:f1::2]" 3130 Authors' Addresses 3132 Zach Shelby 3133 ARM 3134 150 Rose Orchard 3135 San Jose 95134 3136 USA 3138 Phone: +1-408-203-9434 3139 Email: zach.shelby@arm.com 3140 Michael Koster 3141 SmartThings 3142 665 Clyde Avenue 3143 Mountain View 94043 3144 USA 3146 Phone: +1-707-502-5136 3147 Email: Michael.Koster@smartthings.com 3149 Carsten Bormann 3150 Universitaet Bremen TZI 3151 Postfach 330440 3152 Bremen D-28359 3153 Germany 3155 Phone: +49-421-218-63921 3156 Email: cabo@tzi.org 3158 Peter van der Stok 3159 consultant 3161 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 3162 Email: consultancy@vanderstok.org 3163 URI: www.vanderstok.org 3165 Christian Amsuess (editor) 3166 Hollandstr. 12/4 3167 1020 3168 Austria 3170 Phone: +43-664-9790639 3171 Email: christian@amsuess.com