idnits 2.17.1 draft-ietf-core-resource-directory-24.txt: -(10): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 3 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 14 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 394 has weird spacing: '... target o----...' == Line 396 has weird spacing: '...--o rel o...' == Line 461 has weird spacing: '...o href o----...' == Line 465 has weird spacing: '... o ep o---...' == Line 473 has weird spacing: '... o lt o---...' == (2 more instances...) -- The document date (9 March 2020) is 1508 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-02) exists of draft-bormann-t2trg-rel-impl-00 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-33 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 12 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft ARM 4 Intended status: Standards Track M. Koster 5 Expires: 10 September 2020 SmartThings 6 C. Bormann 7 Universitaet Bremen TZI 8 P. van der Stok 9 consultant 10 C. Amsüss, Ed. 11 9 March 2020 13 CoRE Resource Directory 14 draft-ietf-core-resource-directory-24 16 Abstract 18 In many IoT 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 contains 22 information about resources held on other servers, allowing lookups 23 to be performed for those resources. The input to an RD is composed 24 of links and the output is composed of links constructed from the 25 information stored in the RD. This document specifies the web 26 interfaces that a Resource Directory supports for web servers to 27 discover the RD and to register, maintain, lookup and remove 28 information on resources. Furthermore, new target attributes useful 29 in conjunction with an RD are defined. 31 Note to Readers 33 Discussion of this document takes place on the CORE Working Group 34 mailing list (core@ietf.org), which is archived at 35 https://mailarchive.ietf.org/arch/browse/core/ 36 (https://mailarchive.ietf.org/arch/browse/core/). 38 Source for this draft and an issue tracker can be found at 39 https://github.com/core-wg/resource-directory (https://github.com/ 40 core-wg/resource-directory). 42 Status of This Memo 44 This Internet-Draft is submitted in full conformance with the 45 provisions of BCP 78 and BCP 79. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at https://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on 10 September 2020. 59 Copyright Notice 61 Copyright (c) 2020 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 66 license-info) in effect on the date of publication of this document. 67 Please review these documents carefully, as they describe your rights 68 and restrictions with respect to this document. Code Components 69 extracted from this document must include Simplified BSD License text 70 as described in Section 4.e of the Trust Legal Provisions and are 71 provided without warranty as described in the Simplified BSD License. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 76 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 77 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 6 78 3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 6 79 3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 7 80 3.3. RD Content Model . . . . . . . . . . . . . . . . . . . . 8 81 3.4. Link-local addresses and zone identifiers . . . . . . . . 12 82 3.5. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 12 83 3.6. Use Case: Home and Building Automation . . . . . . . . . 13 84 3.7. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 14 85 4. RD discovery and other interface-independent components . . . 14 86 4.1. Finding a Resource Directory . . . . . . . . . . . . . . 15 87 4.1.1. Resource Directory Address Option (RDAO) . . . . . . 17 88 4.1.2. Using DNS-SD to discover a resource directory . . . . 19 89 4.2. Payload Content Formats . . . . . . . . . . . . . . . . . 19 90 4.3. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 19 91 5. Registration . . . . . . . . . . . . . . . . . . . . . . . . 22 92 5.1. Simple Registration . . . . . . . . . . . . . . . . . . . 26 93 5.2. Third-party registration . . . . . . . . . . . . . . . . 28 94 5.3. Operations on the Registration Resource . . . . . . . . . 29 95 5.3.1. Registration Update . . . . . . . . . . . . . . . . . 29 96 5.3.2. Registration Removal . . . . . . . . . . . . . . . . 33 97 5.3.3. Further operations . . . . . . . . . . . . . . . . . 33 98 6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 34 99 6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 34 100 6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 35 101 6.3. Resource lookup examples . . . . . . . . . . . . . . . . 37 102 6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 39 103 7. Security policies . . . . . . . . . . . . . . . . . . . . . . 40 104 7.1. Secure RD discovery . . . . . . . . . . . . . . . . . . . 41 105 7.2. Secure RD filtering . . . . . . . . . . . . . . . . . . . 42 106 7.3. Secure endpoint Name assignment . . . . . . . . . . . . . 42 107 8. Security Considerations . . . . . . . . . . . . . . . . . . . 42 108 8.1. Endpoint Identification and Authentication . . . . . . . 42 109 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 43 110 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 43 111 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 112 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 44 113 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 44 114 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 44 115 9.3.1. Full description of the "Endpoint Type" Registration 116 Parameter . . . . . . . . . . . . . . . . . . . . . . 47 117 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 47 118 9.5. Multicast Address Registration . . . . . . . . . . . . . 48 119 9.6. Well-Kown URIs . . . . . . . . . . . . . . . . . . . . . 48 120 9.7. Service Names and Transport Protocol Port Number 121 Registry . . . . . . . . . . . . . . . . . . . . . . . . 48 122 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 49 123 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 49 124 10.1.1. Installation Characteristics . . . . . . . . . . . . 49 125 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 50 126 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 54 127 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 54 128 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 56 129 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 57 130 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 58 131 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58 132 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 58 133 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 134 13.1. Normative References . . . . . . . . . . . . . . . . . . 68 135 13.2. Informative References . . . . . . . . . . . . . . . . . 69 136 Appendix A. Groups Registration and Lookup . . . . . . . . . . . 71 137 Appendix B. Web links and the Resource Directory . . . . . . . . 73 138 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 73 139 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 74 140 B.1.2. Interpreting attributes and relations . . . . . . . . 74 141 B.2. A slightly more complex example . . . . . . . . . . . . . 74 142 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 75 143 B.4. A note on differences between link-format and Link header 144 fields . . . . . . . . . . . . . . . . . . . . . . . . . 77 146 Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 78 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 149 1. Introduction 151 In the work on Constrained RESTful Environments (CoRE), a REST 152 architecture suitable for constrained nodes (e.g. with limited RAM 153 and ROM [RFC7228]) and networks (e.g. 6LoWPAN [RFC4944]) has been 154 established and is used in Internet-of-Things (IoT) or machine-to- 155 machine (M2M) applications such as smart energy and building 156 automation. 158 The discovery of resources offered by a constrained server is very 159 important in machine-to-machine applications where there are no 160 humans in the loop and static interfaces result in fragility. The 161 discovery of resources provided by an HTTP Web Server is typically 162 called Web Linking [RFC8288]. The use of Web Linking for the 163 description and discovery of resources hosted by constrained web 164 servers is specified by the CoRE Link Format [RFC6690]. However, 165 [RFC6690] only describes how to discover resources from the web 166 server that hosts them by querying "/.well-known/core". In many 167 constrained scenarios, direct discovery of resources is not practical 168 due to sleeping nodes, disperse networks, or networks where multicast 169 traffic is inefficient. These problems can be solved by employing an 170 entity called a Resource Directory (RD), which contains information 171 about resources held on other servers, allowing lookups to be 172 performed for those resources. 174 This document specifies the web interfaces that a Resource Directory 175 supports for web servers to discover the RD and to register, 176 maintain, lookup and remove information on resources. Furthermore, 177 new target attributes useful in conjunction with a Resource Directory 178 are defined. Although the examples in this document show the use of 179 these interfaces with CoAP [RFC7252], they can be applied in an 180 equivalent manner to HTTP [RFC7230]. 182 2. Terminology 184 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 185 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 186 "OPTIONAL" in this document are to be interpreted as described in 187 [RFC2119]. The term "byte" is used in its now customary sense as a 188 synonym for "octet". 190 This specification requires readers to be familiar with all the terms 191 and concepts that are discussed in [RFC3986], [RFC8288] and 192 [RFC6690]. Readers should also be familiar with the terms and 193 concepts discussed in [RFC7252]. To describe the REST interfaces 194 defined in this specification, the URI Template format is used 195 [RFC6570]. 197 This specification makes use of the following additional terminology: 199 resolve against 200 The expression "a URI-reference is _resolved against_ a base URI" 201 is used to describe the process of [RFC3986] Section 5.2. 202 Noteworthy corner cases are that if the URI-reference is a (full) 203 URI and resolved against any base URI, that gives the original 204 full URI, and that resolving an empty URI reference gives the base 205 URI without any fragment identifier. 207 Resource Directory 208 A web entity that stores information about web resources and 209 implements the REST interfaces defined in this specification for 210 registration and lookup of those resources. 212 Sector 213 In the context of a Resource Directory, a sector is a logical 214 grouping of endpoints. 216 The abbreviation "d=" is used for the sector in query parameters 217 for compatibility with deployed implementations. 219 Endpoint 220 Endpoint (EP) is a term used to describe a web server or client in 221 [RFC7252]. In the context of this specification an endpoint is 222 used to describe a web server that registers resources to the 223 Resource Directory. An endpoint is identified by its endpoint 224 name, which is included during registration, and has a unique name 225 within the associated sector of the registration. 227 Registration Base URI 228 The Base URI of a Registration is a URI that typically gives 229 scheme and authority information about an Endpoint. The 230 Registration Base URI is provided at registration time, and is 231 used by the Resource Directory to resolve relative references of 232 the registration into URIs. 234 Target 235 The target of a link is the destination address (URI) of the link. 236 It is sometimes identified with "href=", or displayed as 237 "". Relative targets need resolving with respect to the 238 Base URI (section 5.2 of [RFC3986]). 240 This use of the term Target is consistent with [RFC8288]'s use of 241 the term. 243 Context 244 The context of a link is the source address (URI) of the link, and 245 describes which resource is linked to the target. A link's 246 context is made explicit in serialized links as the "anchor=" 247 attribute. 249 This use of the term Context is consistent with [RFC8288]'s use of 250 the term. 252 Directory Resource 253 A resource in the Resource Directory (RD) containing registration 254 resources. 256 Registration Resource 257 A resource in the RD that contains information about an Endpoint 258 and its links. 260 Commissioning Tool 261 Commissioning Tool (CT) is a device that assists during the 262 installation of the network by assigning values to parameters, 263 naming endpoints and groups, or adapting the installation to the 264 needs of the applications. 266 Registrant-ep 267 Registrant-ep is the endpoint that is registered into the RD. The 268 registrant-ep can register itself, or a CT registers the 269 registrant-ep. 271 RDAO 272 Resource Directory Address Option. A new IPv6 Neighbor Discovery 273 option defined for announcing a Resource Directory's address. 275 3. Architecture and Use Cases 277 3.1. Principles 279 The Resource Directory is primarily a tool to make discovery 280 operations more efficient than querying /.well-known/core on all 281 connected devices, or across boundaries that would be limiting those 282 operations. 284 It provides information about resources hosted by other devices that 285 could otherwise only be obtained by directly querying the /.well- 286 known/core resource on these other devices, either by a unicast 287 request or a multicast request. 289 Information SHOULD only be stored in the resource directory if it can 290 be obtained by querying the described device's /.well-known/core 291 resource directly. 293 Data in the resource directory can only be provided by the device 294 which hosts those data or a dedicated Commissioning Tool (CT). These 295 CTs are thought to act on behalf of endpoints too constrained, or 296 generally unable, to present that information themselves. No other 297 client can modify data in the resource directory. Changes to the 298 information in the Resource Directory do not propagate automatically 299 back to the web servers from where the information originated. 301 3.2. Architecture 303 The resource directory architecture is illustrated in Figure 1. A 304 Resource Directory (RD) is used as a repository of registrations 305 describing resources hosted on other web servers, also called 306 endpoints (EP). An endpoint is a web server associated with a 307 scheme, IP address and port. A physical node may host one or more 308 endpoints. The RD implements a set of REST interfaces for endpoints 309 to register and maintain resource directory registrations, and for 310 endpoints to lookup resources from the RD. An RD can be logically 311 segmented by the use of Sectors. 313 A mechanism to discover an RD using CoRE Link Format [RFC6690] is 314 defined. 316 Registrations in the RD are soft state and need to be periodically 317 refreshed. 319 An endpoint uses specific interfaces to register, update and remove a 320 registration. It is also possible for an RD to fetch Web Links from 321 endpoints and add their contents to resource directory registrations. 323 At the first registration of an endpoint, a "registration resource" 324 is created, the location of which is returned to the registering 325 endpoint. The registering endpoint uses this registration resource 326 to manage the contents of registrations. 328 A lookup interface for discovering any of the Web Links stored in the 329 RD is provided using the CoRE Link Format. 331 Registration Lookup 332 Interface Interface 333 +----+ | | 334 | EP |---- | | 335 +----+ ---- | | 336 --|- +------+ | 337 +----+ | ----| | | +--------+ 338 | EP | ---------|-----| RD |----|-----| Client | 339 +----+ | ----| | | +--------+ 340 --|- +------+ | 341 +----+ ---- | | 342 | CT |---- | | 343 +----+ 345 Figure 1: The resource directory architecture. 347 A Registrant-EP MAY keep concurrent registrations to more than one RD 348 at the same time if explicitly configured to do so, but that is not 349 expected to be supported by typical EP implementations. Any such 350 registrations are independent of each other. The usual expectation 351 when multiple discovery mechanisms or addresses are configured is 352 that they constitute a fall-back path for a single registration. 354 3.3. RD Content Model 356 The Entity-Relationship (ER) models shown in Figure 2 and Figure 3 357 model the contents of /.well-known/core and the resource directory 358 respectively, with entity-relationship diagrams [ER]. Entities 359 (rectangles) are used for concepts that exist independently. 360 Attributes (ovals) are used for concepts that exist only in 361 connection with a related entity. Relations (diamonds) give a 362 semantic meaning to the relation between entities. Numbers specify 363 the cardinality of the relations. 365 Some of the attribute values are URIs. Those values are always full 366 URIs and never relative references in the information model. They 367 can, however, be expressed as relative references in serializations, 368 and often are. 370 These models provide an abstract view of the information expressed in 371 link-format documents and a Resource Directory. They cover the 372 concepts, but not necessarily all details of an RD's operation; they 373 are meant to give an overview, and not be a template for 374 implementations. 376 +----------------------+ 377 | /.well-known/core | 378 +----------------------+ 379 | 380 | 1 381 ////////\\\\\\\ 382 < contains > 383 \\\\\\\\/////// 384 | 385 | 0+ 386 +--------------------+ 387 | link | 388 +--------------------+ 389 | 390 | 1 oooooooo 391 +-----o target o 392 | oooooooo 393 oooooooooooo 0+ | 394 o target o--------+ 395 o attribute o | 0+ oooooo 396 oooooooooooo +-----o rel o 397 | oooooo 398 | 399 | 1 ooooooooo 400 +-----o context o 401 ooooooooo 403 Figure 2: E-R Model of the content of /.well-known/core 405 The model shown in Figure 2 models the contents of /.well-known/core 406 which contains: 408 * a set of links belonging to the hosting web server 410 The web server is free to choose links it deems appropriate to be 411 exposed in its ".well-known/core". Typically, the links describe 412 resources that are served by the host, but the set can also contain 413 links to resources on other servers (see examples in [RFC6690] page 414 14). The set does not necessarily contain links to all resources 415 served by the host. 417 A link has the following attributes (see [RFC8288]): 419 * Zero or more link relations: They describe relations between the 420 link context and the link target. 422 In link-format serialization, they are expressed as space- 423 separated values in the "rel" attribute, and default to "hosts". 425 * A link context URI: It defines the source of the relation, e.g. 426 _who_ "hosts" something. 428 In link-format serialization, it is expressed in the "anchor" 429 attribute. It defaults to that document's URI. 431 * A link target URI: It defines the destination of the relation 432 (e.g. _what_ is hosted), and is the topic of all target 433 attributes. 435 In link-format serialization, it is expressed between angular 436 brackets, and sometimes called the "href". 438 * Other target attributes (e.g. resource type (rt), interface (if), 439 or content format (ct)). These provide additional information 440 about the target URI. 442 +----------------------+ 443 | resource-directory | 444 +----------------------+ 445 | 1 446 | 447 | 448 | 449 | 450 //////\\\\ 451 < contains > 452 \\\\\///// 453 | 454 0+ | 455 ooooooo 1 +---------------+ 456 o base o-------| registration | 457 ooooooo +---------------+ 458 | | 1 459 | +--------------+ 460 oooooooo 1 | | 461 o href o----+ /////\\\\ 462 oooooooo | < contains > 463 | \\\\\///// 464 oooooooo 1 | | 465 o ep o----+ | 0+ 466 oooooooo | +------------------+ 467 | | link | 468 oooooooo 0-1 | +------------------+ 469 o d o----+ | 470 oooooooo | | 1 oooooooo 471 | +-----o target o 472 oooooooo 1 | | oooooooo 473 o lt o----+ ooooooooooo 0+ | 474 oooooooo | o target o-----+ 475 | o attribute o | 0+ oooooo 476 ooooooooooo 0+ | ooooooooooo +-----o rel o 477 o endpoint o----+ | oooooo 478 o attribute o | 479 ooooooooooo | 1 ooooooooo 480 +----o context o 481 ooooooooo 483 Figure 3: E-R Model of the content of the Resource Directory 485 The model shown in Figure 3 models the contents of the resource 486 directory which contains in addition to /.well-known/core: 488 * 0 to n Registrations of endpoints, 489 A registration is associated with one endpoint. A registration 490 defines a set of links as defined for /.well-known/core. A 491 Registration has six types of attributes: 493 * an endpoint name ("ep", a Unicode string) unique within a sector 495 * a Registration Base URI ("base", a URI typically describing the 496 scheme://authority part) 498 * a lifetime ("lt"), 500 * a registration resource location inside the RD ("href"), 502 * optionally a sector ("d", a Unicode string) 504 * optional additional endpoint attributes (from Section 9.3) 506 The cardinality of "base" is currently 1; future documents are 507 invited to extend the RD specification to support multiple values 508 (e.g. [I-D.silverajan-core-coap-protocol-negotiation]). Its value 509 is used as a Base URI when resolving URIs in the links contained in 510 the endpoint. 512 Links are modelled as they are in Figure 2. 514 3.4. Link-local addresses and zone identifiers 516 Registration Base URIs can contain link-local IP addresses. To be 517 usable across hosts, those can not be serialized to contain zone 518 identifiers (see [RFC6874] Section 1). 520 Link-local addresses can only be used on a single link (therefore RD 521 servers can not announce them when queried on a different link), and 522 lookup clients using them need to keep track of which interface they 523 got them from. 525 Therefore, it is advisable in many scenarios to use addresses with 526 larger scope if available. 528 3.5. Use Case: Cellular M2M 530 Over the last few years, mobile operators around the world have 531 focused on development of M2M solutions in order to expand the 532 business to the new type of users: machines. The machines are 533 connected directly to a mobile network using an appropriate embedded 534 wireless interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing 535 short and wide range wireless interfaces. From the system design 536 point of view, the ambition is to design horizontal solutions that 537 can enable utilization of machines in different applications 538 depending on their current availability and capabilities as well as 539 application requirements, thus avoiding silo like solutions. One of 540 the crucial enablers of such design is the ability to discover 541 resources (machines -- endpoints) capable of providing required 542 information at a given time or acting on instructions from the end 543 users. 545 Imagine a scenario where endpoints installed on vehicles enable 546 tracking of the position of these vehicles for fleet management 547 purposes and allow monitoring of environment parameters. During the 548 boot-up process endpoints register with a Resource Directory, which 549 is hosted by the mobile operator or somewhere in the cloud. 550 Periodically, these endpoints update their registration and may 551 modify resources they offer. 553 When endpoints are not always connected, for example because they 554 enter a sleep mode, a remote server is usually used to provide proxy 555 access to the endpoints. Mobile apps or web applications for 556 environment monitoring contact the RD, look up the endpoints capable 557 of providing information about the environment using an appropriate 558 set of link parameters, obtain information on how to contact them 559 (URLs of the proxy server), and then initiate interaction to obtain 560 information that is finally processed, displayed on the screen and 561 usually stored in a database. Similarly, fleet management systems 562 provide the appropriate link parameters to the RD to look up for EPs 563 deployed on the vehicles the application is responsible for. 565 3.6. Use Case: Home and Building Automation 567 Home and commercial building automation systems can benefit from the 568 use of M2M web services. The discovery requirements of these 569 applications are demanding. Home automation usually relies on run- 570 time discovery to commission the system, whereas in building 571 automation a combination of professional commissioning and run-time 572 discovery is used. Both home and building automation involve peer- 573 to-peer interactions between endpoints, and involve battery-powered 574 sleeping devices. 576 Two phases can be discerned for a network servicing the system: (1) 577 installation and (2) operation. During the operational phase, the 578 network is connected to the Internet with a Border router (6LBR) and 579 the nodes connected to the network can use the Internet services that 580 are provided by the Internet Provider or the network administrator. 581 During the installation phase, the network is completely stand-alone, 582 no 6LBR is connected, and the network only supports the IP 583 communication between the connected nodes. The installation phase is 584 usually followed by the operational phase. 586 3.7. Use Case: Link Catalogues 588 Resources may be shared through data brokers that have no knowledge 589 beforehand of who is going to consume the data. Resource Directory 590 can be used to hold links about resources and services hosted 591 anywhere to make them discoverable by a general class of 592 applications. 594 For example, environmental and weather sensors that generate data for 595 public consumption may provide data to an intermediary server, or 596 broker. Sensor data are published to the intermediary upon changes 597 or at regular intervals. Descriptions of the sensors that resolve to 598 links to sensor data may be published to a Resource Directory. 599 Applications wishing to consume the data can use RD Lookup to 600 discover and resolve links to the desired resources and endpoints. 601 The Resource Directory service need not be coupled with the data 602 intermediary service. Mapping of Resource Directories to data 603 intermediaries may be many-to-many. 605 Metadata in web link formats like [RFC6690] which may be internally 606 stored as triples, or relation/attribute pairs providing metadata 607 about resource links, need to be supported by Resource Directories . 608 External catalogues that are represented in other formats may be 609 converted to common web linking formats for storage and access by 610 Resource Directories. Since it is common practice for these to be 611 encoded in URNs [RFC8141], simple and lossless structural transforms 612 should generally be sufficient to store external metadata in Resource 613 Directories. 615 The additional features of Resource Directory allow sectors to be 616 defined to enable access to a particular set of resources from 617 particular applications. This provides isolation and protection of 618 sensitive data when needed. Application groups with multicast 619 addresses may be defined to support efficient data transport. 621 4. RD discovery and other interface-independent components 623 This and the following sections define the required set of REST 624 interfaces between a Resource Directory (RD), endpoints and lookup 625 clients. Although the examples throughout these sections assume the 626 use of CoAP [RFC7252], these REST interfaces can also be realized 627 using HTTP [RFC7230]. Only multicast discovery operations are not 628 possible on HTTP, and Simple Registration can not be executed as base 629 attribute (which is mandatory for HTTP) can not be used there. In 630 all definitions in these sections, both CoAP response codes (with dot 631 notation) and HTTP response codes (without dot notation) are shown. 632 An RD implementing this specification MUST support the discovery, 633 registration, update, lookup, and removal interfaces. 635 All operations on the contents of the Resource Directory MUST be 636 atomic and idempotent. 638 For several operations, interface templates are given in list form; 639 those describe the operation participants, request codes, URIs, 640 content formats and outcomes. Sections of those templates contain 641 normative content about Interaction, Method, URI Template and URI 642 Template Variables as well as the details of the Success condition. 643 The additional sections on options like Content-Format and on Failure 644 codes give typical cases that an implementation of the RD should deal 645 with. Those serve to illustrate the typical responses to readers who 646 are not yet familiar with all the details of CoAP based interfaces; 647 they do not limit what a server may respond under atypical 648 circumstances. 650 REST clients (registrant-EPs / CTs, lookup clients, RD servers during 651 simple registrations) MUST be prepared to receive any unsuccessful 652 code and act upon it according to its definition, options and/or 653 payload to the best of their capabilities, falling back to failing 654 the operation if recovery is not possible. In particular, they 655 should retry the request upon 5.03 (Service Unavailable; 503 in HTTP) 656 according to the Max-Age (Retry-After in HTTP) option, and fall back 657 to link-format when receiving 4.15 (Unsupported Content-Format; 415 658 in HTTP). 660 A resource directory MAY make the information submitted to it 661 available to further directories, if it can ensure that a loop does 662 not form. The protocol used between directories to ensure loop-free 663 operation is outside the scope of this document. 665 4.1. Finding a Resource Directory 667 A (re-)starting device may want to find one or more resource 668 directories for discovery purposes. Dependent on the operational 669 conditions, one or more of the techniques below apply. 671 The device may be pre-configured to exercise specific mechanisms for 672 finding the resource directory: 674 1. It may be configured with a specific IP address for the RD. That 675 IP address may also be an anycast address, allowing the network 676 to forward RD requests to an RD that is topologically close; each 677 target network environment in which some of these preconfigured 678 nodes are to be brought up is then configured with a route for 679 this anycast address that leads to an appropriate RD. (Instead 680 of using an anycast address, a multicast address can also be 681 preconfigured. The RD servers then need to configure one of 682 their interfaces with this multicast address.) 684 2. It may be configured with a DNS name for the RD and use DNS to 685 return the IP address of the RD; it can find a DNS server to 686 perform the lookup using the usual mechanisms for finding DNS 687 servers. 689 3. It may be configured to use a service discovery mechanism such as 690 DNS-SD, as outlined in Section 4.1.2. 692 For cases where the device is not specifically configured with a way 693 to find a resource directory, the network may want to provide a 694 suitable default. 696 1. If the address configuration of the network is performed via 697 SLAAC, this is provided by the RDAO option Section 4.1.1. 699 2. If the address configuration of the network is performed via 700 DHCP, this could be provided via a DHCP option (no such option is 701 defined at the time of writing). 703 Finally, if neither the device nor the network offers any specific 704 configuration, the device may want to employ heuristics to find a 705 suitable resource directory. 707 The present specification does not fully define these heuristics, but 708 suggests a number of candidates: 710 1. In a 6LoWPAN, just assume the Border Router (6LBR) can act as a 711 resource directory (using the ABRO option to find that 712 [RFC6775]). Confirmation can be obtained by sending a Unicast to 713 "coap://[6LBR]/.well-known/core?rt=core.rd*". 715 2. In a network that supports multicast well, discovering the RD 716 using a multicast query for /.well-known/core as specified in 717 CoRE Link Format [RFC6690]: Sending a Multicast GET to 718 "coap://[MCD1]/.well-known/core?rt=core.rd*". RDs within the 719 multicast scope will answer the query. 721 When answering a multicast request directed at a link-local address, 722 the RD may want to respond from a routable address; this makes it 723 easier for registrants to use one of their own routable addresses for 724 registration. 726 As some of the RD addresses obtained by the methods listed here are 727 just (more or less educated) guesses, endpoints MUST make use of any 728 error messages to very strictly rate-limit requests to candidate IP 729 addresses that don't work out. For example, an ICMP Destination 730 Unreachable message (and, in particular, the port unreachable code 731 for this message) may indicate the lack of a CoAP server on the 732 candidate host, or a CoAP error response code such as 4.05 "Method 733 Not Allowed" may indicate unwillingness of a CoAP server to act as a 734 directory server. 736 The following RD discovery mechanisms are recommended: 738 * In managed networks with border routers that need stand-alone 739 operation, the RDAO option is recommended (e.g. operational phase 740 described in Section 3.6). 742 * In managed networks without border router (no Internet services 743 available), the use of a preconfigured anycast address is 744 recommended (e.g. installation phase described in Section 3.6). 746 * In networks managed using DNS-SD, the use of DNS-SD for discovery 747 as described in Section 4.1.2 is recommended. 749 The use of multicast discovery in mesh networks is NOT recommended. 751 4.1.1. Resource Directory Address Option (RDAO) 753 The Resource Directory Address Option (RDAO) using IPv6 Neighbor 754 Discovery (ND) carries information about the address of the Resource 755 Directory (RD). This information is needed when endpoints cannot 756 discover the Resource Directory with a link-local or realm-local 757 scope multicast address, for instance because the endpoint and the RD 758 are separated by a Border Router (6LBR). In many circumstances the 759 availability of DHCP cannot be guaranteed either during commissioning 760 of the network. The presence and the use of the RD is essential 761 during commissioning. 763 It is possible to send multiple RDAO options in one message, 764 indicating as many resource directory addresses. 766 The RDAO format is: 768 0 1 2 3 769 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 770 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 771 | Type | Length = 3 | Valid Lifetime | 772 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 773 | Reserved | 774 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 775 | | 776 + + 777 | | 778 + RD Address + 779 | | 780 + + 781 | | 782 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 784 Fields: 786 Type: TBD38 788 Length: 8-bit unsigned integer. The length of 789 the option in units of 8 bytes. 790 Always 3. 792 Valid Lifetime: 16-bit unsigned integer. The length of 793 time in units of 60 seconds (relative to 794 the time the packet is received) that 795 this Resource Directory address is valid. 796 A value of all zero bits (0x0) indicates 797 that this Resource Directory address 798 is not valid anymore. 800 Reserved: This field is unused. It MUST be 801 initialized to zero by the sender and 802 MUST be ignored by the receiver. 804 RD Address: IPv6 address of the RD. 806 Figure 4: Resource Directory Address Option 808 4.1.2. Using DNS-SD to discover a resource directory 810 A resource directory can advertise its presence in DNS-SD [RFC6763] 811 using the service name "_core-rd._udp" (for CoAP), "_core-rd- 812 dtls._udp" (for CoAP over DTLS), "_core-rd._tcp" (for CoAP over TCP) 813 or "_core-rd-tls._tcp" (for CoAP over TLS) defined in this document. 814 (For the WebSocket transports of CoAP, no service is defined as DNS- 815 SD is typically unavailable in environments where CoAP over 816 WebSockets is used). 818 The selection of the service indicates the protocol used, and the SRV 819 record points the client to a host name and port to use as a starting 820 point for the URI discovery steps of Section 4.3. 822 This section is a simplified concrete application of the more generic 823 mechanism specified in [I-D.ietf-core-rd-dns-sd]. 825 4.2. Payload Content Formats 827 Resource Directory implementations using this specification MUST 828 support the application/link-format content format (ct=40). 830 Resource Directories implementing this specification MAY support 831 additional content formats. 833 Any additional content format supported by a Resource Directory 834 implementing this specification SHOULD be able to express all the 835 information expressible in link-format. It MAY be able to express 836 information that is inexpressible in link-format, but those 837 expressions SHOULD be avoided where possible. 839 4.3. URI Discovery 841 Before an endpoint can make use of an RD, it must first know the RD's 842 address and port, and the URI path information for its REST APIs. 843 This section defines discovery of the RD and its URIs using the well- 844 known interface of the CoRE Link Format [RFC6690] after having 845 discovered a host as described in Section 4.1. 847 Discovery of the RD registration URI path is performed by sending 848 either a multicast or unicast GET request to "/.well-known/core" and 849 including a Resource Type (rt) parameter [RFC6690] with the value 850 "core.rd" in the query string. Likewise, a Resource Type parameter 851 value of "core.rd-lookup*" is used to discover the URIs for RD Lookup 852 operations, core.rd* is used to discover all URI paths for RD 853 operations. Upon success, the response will contain a payload with a 854 link format entry for each RD function discovered, indicating the URI 855 of the RD function returned and the corresponding Resource Type. 857 When performing multicast discovery, the multicast IP address used 858 will depend on the scope required and the multicast capabilities of 859 the network (see Section 9.5). 861 A Resource Directory MAY provide hints about the content-formats it 862 supports in the links it exposes or registers, using the "ct" target 863 attribute, as shown in the example below. Clients MAY use these 864 hints to select alternate content-formats for interaction with the 865 Resource Directory. 867 HTTP does not support multicast and consequently only unicast 868 discovery can be supported at the using the HTTP "/.well-known/core" 869 resource. 871 An implementation of this resource directory specification MUST 872 support query filtering for the rt parameter as defined in [RFC6690]. 874 While the link targets in this discovery step are often expressed in 875 path-absolute form, this is not a requirement. Clients of the RD 876 SHOULD therefore accept URIs of all schemes they support, both as 877 URIs and relative references, and not limit the set of discovered 878 URIs to those hosted at the address used for URI discovery. 880 The URI Discovery operation can yield multiple URIs of a given 881 resource type. The client of the RD can use any of the discovered 882 addresses initially. 884 The discovery request interface is specified as follows (this is 885 exactly the Well-Known Interface of [RFC6690] Section 4, with the 886 additional requirement that the server MUST support query filtering): 888 Interaction: EP and Client -> RD 890 Method: GET 892 URI Template: /.well-known/core{?rt} 894 URI Template Variables: rt := Resource Type. SHOULD contain one of 895 the values "core.rd", "core.rd-lookup*", "core.rd-lookup-res", 896 "core.rd-lookup-ep", or "core.rd*" 898 Accept: absent, application/link-format or any other media type 899 representing web links 901 The following response is expected on this interface: 903 Success: 2.05 "Content" or 200 "OK" with an application/link-format 904 or other web link payload containing one or more matching entries 905 for the RD resource. 907 The following example shows an endpoint discovering an RD using this 908 interface, thus learning that the directory resource location, in 909 this example, is /rd, and that the content-format delivered by the 910 server hosting the resource is application/link-format (ct=40). Note 911 that it is up to the RD to choose its RD locations. 913 Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* 915 Res: 2.05 Content 916 ;rt="core.rd";ct=40, 917 ;rt="core.rd-lookup-ep";ct=40, 918 ;rt="core.rd-lookup-res";ct=40, 920 Figure 5: Example discovery exchange 922 The following example shows the way of indicating that a client may 923 request alternate content-formats. The Content-Format code attribute 924 "ct" MAY include a space-separated sequence of Content-Format codes 925 as specified in Section 7.2.1 of [RFC7252], indicating that multiple 926 content-formats are available. The example below shows the required 927 Content-Format 40 (application/link-format) indicated as well as a 928 CBOR and JSON representation from [I-D.ietf-core-links-json] (which 929 have no numeric values assigned yet, so they are shown as TBD64 and 930 TBD504 as in that draft). The RD resource locations /rd, and /rd- 931 lookup are example values. The server in this example also indicates 932 that it is capable of providing observation on resource lookups. 934 Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* 936 Res: 2.05 Content 937 ;rt="core.rd";ct="40 65225", 938 ;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs, 939 ;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504", 941 Figure 6: Example discovery exchange indicating additional 942 content-formats 944 From a management and maintenance perspective, it is necessary to 945 identify the components that constitute the RD server. The 946 identification refers to information about for example client-server 947 incompatibilities, supported features, required updates and other 948 aspects. The URI discovery address, a described in section 4 of 949 [RFC6690] can be used to find the identification. 951 It would typically be stored in an implementation information link 952 (as described in [I-D.bormann-t2trg-rel-impl]): 954 Req: GET /.well-known/core?rel=impl-info 956 Res: 2.05 Content 957 ; 958 rel="impl-info" 960 Figure 7: Example exchange of obtaining implementation information 962 Note that depending on the particular server's architecture, such a 963 link could be anchored at the RD server's root, at the discovery site 964 (as in this example) or at individual RD components. The latter is 965 to be expected when different applications are run on the same 966 server. 968 5. Registration 970 After discovering the location of an RD, a registrant-ep or CT MAY 971 register the resources of the registrant-ep using the registration 972 interface. This interface accepts a POST from an endpoint containing 973 the list of resources to be added to the directory as the message 974 payload in the CoRE Link Format [RFC6690] or other representations of 975 web links, along with query parameters indicating the name of the 976 endpoint, and optionally the sector, lifetime and base URI of the 977 registration. It is expected that other specifications will define 978 further parameters (see Section 9.3). The RD then creates a new 979 registration resource in the RD and returns its location. The 980 receiving endpoint MUST use that location when refreshing 981 registrations using this interface. Registration resources in the RD 982 are kept active for the period indicated by the lifetime parameter. 983 The creating endpoint is responsible for refreshing the registration 984 resource within this period using either the registration or update 985 interface. The registration interface MUST be implemented to be 986 idempotent, so that registering twice with the same endpoint 987 parameters ep and d (sector) does not create multiple registration 988 resources. 990 The following rules apply for a registration request targeting a 991 given (ep, d) value pair: 993 * When the (ep, d) value pair of the registration-request is 994 different from any existing registration, a new registration is 995 generated. 997 * When the (ep, d) value pair of the registration-request is equal 998 to an existing registration, the content and parameters of the 999 existing registration are replaced with the content of the 1000 registration request. 1002 The posted link-format document can (and typically does) contain 1003 relative references both in its link targets and in its anchors, or 1004 contain empty anchors. The RD server needs to resolve these 1005 references in order to faithfully represent them in lookups. They 1006 are resolved against the base URI of the registration, which is 1007 provided either explicitly in the "base" parameter or constructed 1008 implicitly from the requester's URI as constructed from its network 1009 address and scheme. 1011 For media types to which Appendix C applies (i.e. documents in 1012 application/link-format), the RD only needs to accept representations 1013 in Limited Link Format as described there. Its behavior with 1014 representations outside that subset is implementation defined. 1016 The registration request interface is specified as follows: 1018 Interaction: EP -> RD 1020 Method: POST 1022 URI Template: {+rd}{?ep,d,lt,base,extra-attrs*} 1024 URI Template Variables: rd := RD registration URI (mandatory). 1025 This is the location of the RD, as obtained from discovery. 1027 ep := Endpoint name (mostly mandatory). 1028 The endpoint name is an identifier that MUST be unique within a 1029 sector. As the endpoint name is a Unicode string, it is 1030 encoded in UTF-8 (and possibly pct-encoded) during variable 1031 expansion (see [RFC6570] Section 3.2.1). The endpoint name 1032 MUST NOT contain any character in the inclusive ranges 0-31 or 1033 127-159. The maximum length of this parameter is 63 UTF-8 1034 encoded bytes. If the RD is configured to recognize the 1035 endpoint (e.g. based on its security context), the RD assigns 1036 an endpoint name based on a set of configuration parameter 1037 values. 1039 d := Sector (optional). The sector to 1040 which this endpoint belongs. When this parameter is not 1041 present, the RD MAY associate the endpoint with a configured 1042 default sector or leave it empty. The sector is encoded like 1043 the ep parameter, and is limited to 63 UTF-8 encoded bytes as 1044 well. The endpoint name and sector name are not set when one 1045 or both are set in an accompanying authorization token. 1047 lt := Lifetime (optional). Lifetime of the 1048 registration in seconds. Range of 1-4294967295. If no 1049 lifetime is included in the initial registration, a default 1050 value of 90000 (25 hours) SHOULD be assumed. 1052 base := Base URI (optional). This 1053 parameter sets the base URI of the registration, under which 1054 the relative links in the payload are to be interpreted. The 1055 specified URI typically does not have a path component of its 1056 own, and MUST be suitable as a base URI to resolve any relative 1057 references given in the registration. The parameter is 1058 therefore usually of the shape "scheme://authority" for HTTP 1059 and CoAP URIs. The URI SHOULD NOT have a query or fragment 1060 component as any non-empty relative part in a reference would 1061 remove those parts from the resulting URI. 1063 In the absence of this parameter the scheme of the protocol, 1064 source address and source port of the registration request are 1065 assumed. The Base URI is consecutively constructed by 1066 concatenating the used protocol's scheme with the characters 1067 "://", the requester's source address as an address literal and 1068 ":" followed by its port (if it was not the protocol's default 1069 one) in analogy to [RFC7252] Section 6.5. 1071 This parameter is mandatory when the directory is filled by a 1072 third party such as an commissioning tool. 1074 If the registrant-ep uses an ephemeral port to register with, 1075 it MUST include the base parameter in the registration to 1076 provide a valid network path. 1078 A registrant that can not be reached by potential lookup 1079 clients at the address it registers from (e.g. because it is 1080 behind some form of Network Address Translation (NAT)) MUST 1081 provide a reachable base address with its registration. 1083 If the Base URI contains a link-local IP literal, it MUST NOT 1084 contain a Zone Identifier, and MUST be local to the link on 1085 which the registration request is received. 1087 Endpoints that register with a base that contains a path 1088 component can not meaningfully use [RFC6690] Link Format due to 1089 its prevalence of the Origin concept in relative reference 1090 resolution. Those applications should use different 1091 representations of links to which Appendix C is not applicable 1092 (e.g. [I-D.hartke-t2trg-coral]). 1094 extra-attrs := Additional registration 1096 attributes (optional). The endpoint can pass any parameter 1097 registered at Section 9.3 to the directory. If the RD is aware 1098 of the parameter's specified semantics, it processes it 1099 accordingly. Otherwise, it MUST store the unknown key and its 1100 value(s) as an endpoint attribute for further lookup. 1102 Content-Format: application/link-format or any other indicated media 1103 type representing web links 1105 The following response is expected on this interface: 1107 Success: 2.01 "Created" or 201 "Created". The Location-Path option 1108 or Location header field MUST be included in the response. This 1109 location MUST be a stable identifier generated by the RD as it is 1110 used for all subsequent operations on this registration resource. 1111 The registration resource location thus returned is for the 1112 purpose of updating the lifetime of the registration and for 1113 maintaining the content of the registered links, including 1114 updating and deleting links. 1116 A registration with an already registered ep and d value pair 1117 responds with the same success code and location as the original 1118 registration; the set of links registered with the endpoint is 1119 replaced with the links from the payload. 1121 The location MUST NOT have a query or fragment component, as that 1122 could conflict with query parameters during the Registration 1123 Update operation. Therefore, the Location-Query option MUST NOT 1124 be present in a successful response. 1126 If the registration fails, including request timeouts, or if delays 1127 from Service Unavailable responses with Max-Age or Retry-After 1128 accumulate to exceed the registrant's configured timeouts, it SHOULD 1129 pick another registration URI from the "URI Discovery" step and if 1130 there is only one or the list is exhausted, pick other choices from 1131 the "Finding a Resource Directory" step. Care has to be taken to 1132 consider the freshness of results obtained earlier, e.g. of the 1133 result of a "/.well-known/core" response, the lifetime of an RDAO 1134 option and of DNS responses. Any rate limits and persistent errors 1135 from the "Finding a Resource Directory" step must be considered for 1136 the whole registration time, not only for a single operation. 1138 The following example shows a registrant-ep with the name "node1" 1139 registering two resources to an RD using this interface. The 1140 location "/rd" is an example RD location discovered in a request 1141 similar to Figure 5. 1143 Req: POST coap://rd.example.com/rd?ep=node1 1144 Content-Format: 40 1145 Payload: 1146 ;ct=41;rt="temperature-c";if="sensor", 1147 ; 1148 anchor="/sensors/temp";rel="describedby" 1150 Res: 2.01 Created 1151 Location-Path: /rd/4521 1153 Figure 8: Example registration payload 1155 A Resource Directory may optionally support HTTP. Here is an example 1156 of almost the same registration operation above, when done using 1157 HTTP. 1159 Req: 1160 POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1 1161 Host: example.com 1162 Content-Type: application/link-format 1164 ;ct=41;rt="temperature-c";if="sensor", 1165 ; 1166 anchor="/sensors/temp";rel="describedby" 1168 Res: 1169 HTTP/1.1 201 Created 1170 Location: /rd/4521 1172 Figure 9: Example registration payload as expressed using HTTP 1174 5.1. Simple Registration 1176 Not all endpoints hosting resources are expected to know how to 1177 upload links to an RD as described in Section 5. Instead, simple 1178 endpoints can implement the Simple Registration approach described in 1179 this section. An RD implementing this specification MUST implement 1180 Simple Registration. However, there may be security reasons why this 1181 form of directory discovery would be disabled. 1183 This approach requires that the registrant-ep makes available the 1184 hosted resources that it wants to be discovered, as links on its 1185 "/.well-known/core" interface as specified in [RFC6690]. The links 1186 in that document are subject to the same limitations as the payload 1187 of a registration (with respect to Appendix C). 1189 * The registrant-ep finds one or more addresses of the directory 1190 server as described in Section 4.1. 1192 * The registrant-ep sends (and regularly refreshes with) a POST 1193 request to the "/.well-known/core" URI of the directory server of 1194 choice. The body of the POST request is empty, and triggers the 1195 resource directory server to perform GET requests at the 1196 requesting registrant-ep's /.well-known/core to obtain the link- 1197 format payload to register. 1199 The registrant-ep includes the same registration parameters in the 1200 POST request as it would per Section 5. The registration base URI 1201 of the registration is taken from the registrant-ep's network 1202 address (as is default with regular registrations). 1204 Example request from registrant-EP to RD (unanswered until the 1205 next step): 1207 Req: POST /.well-known/core?lt=6000&ep=node1 1208 (No payload) 1210 Figure 10: First half example exchange of a simple registration 1212 * The Resource Directory queries the registrant-ep's discovery 1213 resource to determine the success of the operation. It SHOULD 1214 keep a cache of the discovery resource and not query it again as 1215 long as it is fresh. 1217 Example request from the RD to the registrant-EP: 1219 Req: GET /.well-known/core 1220 Accept: 40 1222 Res: 2.05 Content 1223 Content-Format: 40 1224 Payload: 1225 1227 Figure 11: Example exchange of the RD querying the simple endpoint 1229 With this response, the RD would answer the previous step's request: 1231 Res: 2.04 Changed 1233 Figure 12: Second half example exchange of a simple registration 1235 The sequence of fetching the registration content before sending a 1236 successful response was chosen to make responses reliable, and the 1237 caching item was chosen to still allow very constrained registrants. 1238 Registrants MUST be able to serve a GET request to "/.well-known/ 1239 core" after having requested registration. Constrained devices MAY 1240 regard the initial request as temporarily failed when they need RAM 1241 occupied by their own request to serve the RD's GET, and retry later 1242 when the RD already has a cached representation of their discovery 1243 resources. Then, the RD can reply immediately and the registrant can 1244 receive the response. 1246 The simple registration request interface is specified as follows: 1248 Interaction: EP -> RD 1250 Method: POST 1252 URI Template: /.well-known/core{?ep,d,lt,extra-attrs*} 1254 URI Template Variables are as they are for registration in Section 5. 1255 The base attribute is not accepted to keep the registration interface 1256 simple; that rules out registration over CoAP-over-TCP or HTTP that 1257 would need to specify one. 1259 The following response is expected on this interface: 1261 Success: 2.04 "Changed". 1263 For the second interaction triggered by the above, the registrant-ep 1264 takes the role of server and the RD the role of client. (Note that 1265 this is exactly the Well-Known Interface of [RFC6690] Section 4): 1267 Interaction: RD -> EP 1269 Method: GET 1271 URI Template: /.well-known/core 1273 The following response is expected on this interface: 1275 Success: 2.05 "Content". 1277 The RD MUST delete registrations created by simple registration after 1278 the expiration of their lifetime. Additional operations on the 1279 registration resource cannot be executed because no registration 1280 location is returned. 1282 5.2. Third-party registration 1284 For some applications, even Simple Registration may be too taxing for 1285 some very constrained devices, in particular if the security 1286 requirements become too onerous. 1288 In a controlled environment (e.g. building control), the Resource 1289 Directory can be filled by a third party device, called a 1290 Commissioning Tool (CT). The commissioning tool can fill the 1291 Resource Directory from a database or other means. For that purpose 1292 scheme, IP address and port of the URI of the registered device is 1293 the value of the "base" parameter of the registration described in 1294 Section 5. 1296 It should be noted that the value of the "base" parameter applies to 1297 all the links of the registration and has consequences for the anchor 1298 value of the individual links as exemplified in Appendix B. An 1299 eventual (currently non-existing) "base" attribute of the link is not 1300 affected by the value of "base" parameter in the registration. 1302 5.3. Operations on the Registration Resource 1304 This section describes how the registering endpoint can maintain the 1305 registrations that it created. The registering endpoint can be the 1306 registrant-ep or the CT. An endpoint SHOULD NOT use this interface 1307 for registrations that it did not create. The registrations are 1308 resources of the RD. 1310 After the initial registration, the registering endpoint retains the 1311 returned location of the Registration Resource for further 1312 operations, including refreshing the registration in order to extend 1313 the lifetime and "keep-alive" the registration. When the lifetime of 1314 the registration has expired, the RD SHOULD NOT respond to discovery 1315 queries concerning this endpoint. The RD SHOULD continue to provide 1316 access to the Registration Resource after a registration time-out 1317 occurs in order to enable the registering endpoint to eventually 1318 refresh the registration. The RD MAY eventually remove the 1319 registration resource for the purpose of garbage collection. If the 1320 Registration Resource is removed, the corresponding endpoint will 1321 need to be re-registered. 1323 The Registration Resource may also be used cancel the registration 1324 using DELETE, and to perform further operations beyond the scope of 1325 this specification. 1327 These operations are described below. 1329 5.3.1. Registration Update 1331 The update interface is used by the registering endpoint to refresh 1332 or update its registration with an RD. To use the interface, the 1333 registering endpoint sends a POST request to the registration 1334 resource returned by the initial registration operation. 1336 An update MAY update the lifetime or the base URI registration 1337 parameters "lt", "base" as in Section 5. Parameters that are not 1338 being changed SHOULD NOT be included in an update. Adding parameters 1339 that have not changed increases the size of the message but does not 1340 have any other implications. Parameters MUST be included as query 1341 parameters in an update operation as in Section 5. 1343 A registration update resets the timeout of the registration to the 1344 (possibly updated) lifetime of the registration, independent of 1345 whether a "lt" parameter was given. 1347 If the base URI of the registration is changed in an update, relative 1348 references submitted in the original registration or later updates 1349 are resolved anew against the new base. 1351 The registration update operation only describes the use of POST with 1352 an empty payload. Future standards might describe the semantics of 1353 using content formats and payloads with the POST method to update the 1354 links of a registration (see Section 5.3.3). 1356 The update registration request interface is specified as follows: 1358 Interaction: EP -> RD 1360 Method: POST 1362 URI Template: {+location}{?lt,base,extra-attrs*} 1364 URI Template Variables: location := This is the Location returned 1365 by the RD as a result of a successful earlier registration. 1367 lt := Lifetime (optional). Lifetime of the 1368 registration in seconds. Range of 1-4294967295. If no 1369 lifetime is included, the previous last lifetime set on a 1370 previous update or the original registration (falling back to 1371 90000) SHOULD be used. 1373 base := Base URI (optional). This 1374 parameter updates the Base URI established in the original 1375 registration to a new value. If the parameter is set in an 1376 update, it is stored by the RD as the new Base URI under which 1377 to interpret the relative links present in the payload of the 1378 original registration, following the same restrictions as in 1379 the registration. If the parameter is not set in the request 1380 but was set before, the previous Base URI value is kept 1381 unmodified. If the parameter is not set in the request and was 1382 not set before either, the source address and source port of 1383 the update request are stored as the Base URI. 1385 extra-attrs := Additional registration 1386 attributes (optional). As with the registration, the RD 1387 processes them if it knows their semantics. Otherwise, unknown 1388 attributes are stored as endpoint attributes, overriding any 1389 previously stored endpoint attributes of the same key. 1391 Note that this default behavior does not allow removing an 1392 endpoint attribute in an update. For attributes whose 1393 functionality depends on the endpoints' ability to remove them 1394 in an update, it can make sense to define a value whose 1395 presence is equivalent to the absence of a value. As an 1396 alternative, an extension can define different updating rules 1397 for their attributes. That necessitates either discovery of 1398 whether the RD is aware of that extension, or tolerating the 1399 default behavior. 1401 Content-Format: none (no payload) 1403 The following responses are expected on this interface: 1405 Success: 2.04 "Changed" or 204 "No Content" if the update was 1406 successfully processed. 1408 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1409 exist (e.g. may have been removed). 1411 If the registration fails in any way, including "Not Found" and 1412 request timeouts, or if the time indicated in a Service Unavailable 1413 Max-Age/Retry-After exceeds the remaining lifetime, the registering 1414 endpoint SHOULD attempt registration again. 1416 The following example shows how the registering endpoint updates its 1417 registration resource at an RD using this interface with the example 1418 location value: /rd/4521. 1420 Req: POST /rd/4521 1422 Res: 2.04 Changed 1424 Figure 13: Example update of a registration 1426 The following example shows the registering endpoint updating its 1427 registration resource at an RD using this interface with the example 1428 location value: /rd/4521. The initial registration by the 1429 registering endpoint set the following values: 1431 * endpoint name (ep)=endpoint1 1432 * lifetime (lt)=500 1434 * Base URI (base)=coap://local-proxy-old.example.com:5683 1436 * payload of Figure 8 1438 The initial state of the Resource Directory is reflected in the 1439 following request: 1441 Req: GET /rd-lookup/res?ep=endpoint1 1443 Res: 2.05 Content 1444 Payload: 1445 ;ct=41; 1446 rt="temperature-c";if="sensor"; 1447 anchor="coap://local-proxy-old.example.com:5683/", 1448 ; 1449 anchor="coap://local-proxy-old.example.com:5683/sensors/temp";rel="describedby" 1451 Figure 14: Example lookup before a change to the base address 1453 The following example shows the registering endpoint changing the 1454 Base URI to "coaps://new.example.com:5684": 1456 Req: POST /rd/4521?base=coaps://new.example.com:5684 1458 Res: 2.04 Changed 1460 Figure 15: Example registration update that changes the base address 1462 The consecutive query returns: 1464 Req: GET /rd-lookup/res?ep=endpoint1 1466 Res: 2.05 Content 1467 Payload: 1468 ;ct=41; 1469 rt="temperature-c";if="sensor"; 1470 anchor="coap://new.example.com:5684/", 1471 ; 1472 anchor="coap://new.example.com:5684/sensors/temp";rel="describedby" 1474 Figure 16: Example lookup after a change to the base address 1476 5.3.2. Registration Removal 1478 Although RD registrations have soft state and will eventually timeout 1479 after their lifetime, the registering endpoint SHOULD explicitly 1480 remove an entry from the RD if it knows it will no longer be 1481 available (for example on shut-down). This is accomplished using a 1482 removal interface on the RD by performing a DELETE on the endpoint 1483 resource. 1485 The removal request interface is specified as follows: 1487 Interaction: EP -> RD 1489 Method: DELETE 1491 URI Template: {+location} 1493 URI Template Variables: location := This is the Location returned 1494 by the RD as a result of a successful earlier registration. 1496 The following responses are expected on this interface: 1498 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1500 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1501 exist (e.g. may already have been removed). 1503 The following examples shows successful removal of the endpoint from 1504 the RD with example location value /rd/4521. 1506 Req: DELETE /rd/4521 1508 Res: 2.02 Deleted 1510 Figure 17: Example of a registration removal 1512 5.3.3. Further operations 1514 Additional operations on the registration can be specified in future 1515 documents, for example: 1517 * Send iPATCH (or PATCH) updates ([RFC8132]) to add, remove or 1518 change the links of a registration. 1520 * Use GET to read the currently stored set of links in a 1521 registration resource. 1523 Those operations are out of scope of this document, and will require 1524 media types suitable for modifying sets of links. 1526 6. RD Lookup 1528 To discover the resources registered with the RD, a lookup interface 1529 must be provided. This lookup interface is defined as a default, and 1530 it is assumed that RDs may also support lookups to return resource 1531 descriptions in alternative formats (e.g. JSON or CBOR link format 1532 [I-D.ietf-core-links-json]) or using more advanced interfaces (e.g. 1533 supporting context or semantic based lookup) on different resources 1534 that are discovered independently. 1536 RD Lookup allows lookups for endpoints and resources using attributes 1537 defined in this document and for use with the CoRE Link Format. The 1538 result of a lookup request is the list of links (if any) 1539 corresponding to the type of lookup. Thus, an endpoint lookup MUST 1540 return a list of endpoints and a resource lookup MUST return a list 1541 of links to resources. 1543 The lookup type is selected by a URI endpoint, which is indicated by 1544 a Resource Type as per Table 1 below: 1546 +-------------+--------------------+-----------+ 1547 | Lookup Type | Resource Type | Mandatory | 1548 +=============+====================+===========+ 1549 | Resource | core.rd-lookup-res | Mandatory | 1550 +-------------+--------------------+-----------+ 1551 | Endpoint | core.rd-lookup-ep | Mandatory | 1552 +-------------+--------------------+-----------+ 1554 Table 1: Lookup Types 1556 6.1. Resource lookup 1558 Resource lookup results in links that are semantically equivalent to 1559 the links submitted to the RD. The links and link parameters 1560 returned by the lookup are equal to the submitted ones, except that 1561 the target and anchor references are fully resolved. 1563 Links that did not have an anchor attribute are therefore returned 1564 with the base URI of the registration as the anchor. Links of which 1565 href or anchor was submitted as a (full) URI are returned with these 1566 attributes unmodified. 1568 Above rules allow the client to interpret the response as links 1569 without any further knowledge of the storage conventions of the RD. 1570 The Resource Directory MAY replace the registration base URIs with a 1571 configured intermediate proxy, e.g. in the case of an HTTP lookup 1572 interface for CoAP endpoints. 1574 If the base URI of a registration contains a link-local address, the 1575 RD MUST NOT show its links unless the lookup was made from the same 1576 link. The RD MUST NOT include zone identifiers in the resolved URIs. 1578 6.2. Lookup filtering 1580 Using the Accept Option, the requester can control whether the 1581 returned list is returned in CoRE Link Format ("application/link- 1582 format", default) or in alternate content-formats (e.g. from 1583 [I-D.ietf-core-links-json]). 1585 The page and count parameters are used to obtain lookup results in 1586 specified increments using pagination, where count specifies how many 1587 links to return and page specifies which subset of links organized in 1588 sequential pages, each containing 'count' links, starting with link 1589 zero and page zero. Thus, specifying count of 10 and page of 0 will 1590 return the first 10 links in the result set (links 0-9). Count = 10 1591 and page = 1 will return the next 'page' containing links 10-19, and 1592 so on. 1594 Multiple search criteria MAY be included in a lookup. All included 1595 criteria MUST match for a link to be returned. The Resource 1596 Directory MUST support matching with multiple search criteria. 1598 A link matches a search criterion if it has an attribute of the same 1599 name and the same value, allowing for a trailing "*" wildcard 1600 operator as in Section 4.1 of [RFC6690]. Attributes that are defined 1601 as "link-type" match if the search value matches any of their values 1602 (see Section 4.1 of [RFC6690]; e.g. "?if=core.s" matches ";if="abc 1603 core.s";"). A resource link also matches a search criterion if its 1604 endpoint would match the criterion, and vice versa, an endpoint link 1605 matches a search criterion if any of its resource links matches it. 1607 Note that "href" is a valid search criterion and matches target 1608 references. Like all search criteria, on a resource lookup it can 1609 match the target reference of the resource link itself, but also the 1610 registration resource of the endpoint that registered it. Queries 1611 for resource link targets MUST be in URI form (i.e. not relative 1612 references) and are matched against a resolved link target. Queries 1613 for endpoints SHOULD be expressed in path-absolute form if possible 1614 and MUST be expressed in URI form otherwise; the RD SHOULD recognize 1615 either. The "anchor" attribute is usable for resource lookups, and, 1616 if queried, MUST be for in URI form as well. 1618 Endpoints that are interested in a lookup result repeatedly or 1619 continuously can use mechanisms like ETag caching, resource 1620 observation ([RFC7641]), or any future mechanism that might allow 1621 more efficient observations of collections. These are advertised, 1622 detected and used according to their own specifications and can be 1623 used with the lookup interface as with any other resource. 1625 When resource observation is used, every time the set of matching 1626 links changes, or the content of a matching link changes, the RD 1627 sends a notification with the matching link set. The notification 1628 contains the successful current response to the given request, 1629 especially with respect to representing zero matching links (see 1630 "Success" item below). 1632 The lookup interface is specified as follows: 1634 Interaction: Client -> RD 1636 Method: GET 1638 URI Template: {+type-lookup-location}{?page,count,search*} 1640 URI Template Variables: type-lookup-location := RD Lookup URI for a 1641 given lookup type (mandatory). The address is discovered as 1642 described in Section 4.3. 1644 search := Search criteria for limiting the 1645 number of results (optional). 1647 page := Page (optional). Parameter cannot 1648 be used without the count parameter. Results are returned from 1649 result set in pages that contain 'count' links starting from 1650 index (page * count). Page numbering starts with zero. 1652 count := Count (optional). Number of 1653 results is limited to this parameter value. If the page 1654 parameter is also present, the response MUST only include 1655 'count' links starting with the (page * count) link in the 1656 result set from the query. If the count parameter is not 1657 present, then the response MUST return all matching links in 1658 the result set. Link numbering starts with zero. 1660 Accept: absent, application/link-format or any other indicated media 1661 type representing web links 1663 The following responses codes are defined for this interface: 1665 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1666 format" or other web link payload containing matching entries for 1667 the lookup. The payload can contain zero links (which is an empty 1668 payload in [RFC6690] link format, but could also be "[]" in JSON 1669 based formats), indicating that no entities matched the request. 1671 6.3. Resource lookup examples 1673 The examples in this section assume the existence of CoAP hosts with 1674 a default CoAP port 61616. HTTP hosts are possible and do not change 1675 the nature of the examples. 1677 The following example shows a client performing a resource lookup 1678 with the example resource look-up locations discovered in Figure 5: 1680 Req: GET /rd-lookup/res?rt=temperature 1682 Res: 2.05 Content 1683 ;rt="temperature"; 1684 anchor="coap://[2001:db8:3::123]:61616" 1686 Figure 18: Example a resource lookup 1688 A client that wants to be notified of new resources as they show up 1689 can use observation: 1691 Req: GET /rd-lookup/res?rt=light 1692 Observe: 0 1694 Res: 2.05 Content 1695 Observe: 23 1696 Payload: empty 1698 (at a later point in time) 1700 Res: 2.05 Content 1701 Observe: 24 1702 Payload: 1703 ;rt="light"; 1704 anchor="coap://[2001:db8:3::124]", 1705 ;rt="light"; 1706 anchor="coap://[2001:db8:3::124]", 1707 ;rt="light"; 1708 anchor="coap://[2001:db8:3::124]" 1710 Figure 19: Example an observing resource lookup 1712 The following example shows a client performing a paginated resource 1713 lookup 1715 Req: GET /rd-lookup/res?page=0&count=5 1717 Res: 2.05 Content 1718 ;rt=sensor;ct=60; 1719 anchor="coap://[2001:db8:3::123]:61616", 1720 ;rt=sensor;ct=60; 1721 anchor="coap://[2001:db8:3::123]:61616", 1722 ;rt=sensor;ct=60; 1723 anchor="coap://[2001:db8:3::123]:61616", 1724 ;rt=sensor;ct=60; 1725 anchor="coap://[2001:db8:3::123]:61616", 1726 ;rt=sensor;ct=60; 1727 anchor="coap://[2001:db8:3::123]:61616" 1729 Req: GET /rd-lookup/res?page=1&count=5 1731 Res: 2.05 Content 1732 ;rt=sensor;ct=60; 1733 anchor="coap://[2001:db8:3::123]:61616", 1734 ;rt=sensor;ct=60; 1735 anchor="coap://[2001:db8:3::123]:61616", 1736 ;rt=sensor;ct=60; 1737 anchor="coap://[2001:db8:3::123]:61616", 1738 ;rt=sensor;ct=60; 1739 anchor="coap://[2001:db8:3::123]:61616", 1740 ;rt=sensor;ct=60; 1741 anchor="coap://[2001:db8:3::123]:61616" 1743 Figure 20: Examples of paginated resource lookup 1745 The following example shows a client performing a lookup of all 1746 resources of all endpoints of a given endpoint type. It assumes that 1747 two endpoints (with endpoint names "sensor1" and "sensor2") have 1748 previously registered with their respective addresses 1749 "coap://sensor1.example.com" and "coap://sensor2.example.com", and 1750 posted the very payload of the 6th request of section 5 of [RFC6690]. 1752 It demonstrates how absolute link targets stay unmodified, while 1753 relative ones are resolved: 1755 Req: GET /rd-lookup/res?et=oic.d.sensor 1757 ;ct=40;title="Sensor Index"; 1758 anchor="coap://sensor1.example.com", 1759 ;rt="temperature-c"; 1760 if="sensor"; anchor="coap://sensor1.example.com", 1761 ;rt="light-lux"; 1762 if="sensor"; anchor="coap://sensor1.example.com", 1763 ;rel="describedby"; 1764 anchor="coap://sensor1.example.com/sensors/temp", 1765 ;rel="alternate"; 1766 anchor="coap://sensor1.example.com/sensors/temp", 1767 ;ct=40;title="Sensor Index"; 1768 anchor="coap://sensor2.example.com", 1769 ;rt="temperature-c"; 1770 if="sensor"; anchor="coap://sensor2.example.com", 1771 ;rt="light-lux"; 1772 if="sensor"; anchor="coap://sensor2.example.com", 1773 ;rel="describedby"; 1774 anchor="coap://sensor2.example.com/sensors/temp", 1775 ;rel="alternate"; 1776 anchor="coap://sensor2.example.com/sensors/temp" 1778 Figure 21: Example of resource lookup from multiple endpoints 1780 6.4. Endpoint lookup 1782 The endpoint lookup returns registration resources which can only be 1783 manipulated by the registering endpoint. 1785 Endpoint registration resources are annotated with their endpoint 1786 names (ep), sectors (d, if present) and registration base URI (base; 1787 reports the registrant-ep's address if no explicit base was given) as 1788 well as a constant resource type (rt="core.rd-ep"); the lifetime (lt) 1789 is not reported. Additional endpoint attributes are added as target 1790 attributes to their endpoint link unless their specification says 1791 otherwise. 1793 Links to endpoints SHOULD be presented in path-absolute form or, if 1794 required, as (full) URIs. (This avoids the RFC6690 ambiguities.) 1796 Base addresses that contain link-local addresses MUST NOT include 1797 zone identifiers, and such registrations MUST NOT be shown unless the 1798 lookup was made from the same link from which the registration was 1799 made. 1801 While Endpoint Lookup does expose the registration resources, the RD 1802 does not need to make them accessible to clients. Clients SHOULD NOT 1803 attempt to dereference or manipulate them. 1805 A Resource Directory can report endpoints in lookup that are not 1806 hosted at the same address. Lookup clients MUST be prepared to see 1807 arbitrary URIs as registration resources in the results and treat 1808 them as opaque identifiers; the precise semantics of such links are 1809 left to future specifications. 1811 The following example shows a client performing an endpoint type (et) 1812 lookup with the value oic.d.sensor (which is currently a registered 1813 rt value): 1815 Req: GET /rd-lookup/ep?et=oic.d.sensor 1817 Res: 2.05 Content 1818 ;base="coap://[2001:db8:3::127]:61616";ep="node5"; 1819 et="oic.d.sensor";ct="40";rt="core.rd-ep", 1820 ;base="coap://[2001:db8:3::129]:61616";ep="node7"; 1821 et="oic.d.sensor";ct="40";d="floor-3";rt="core.rd-ep" 1823 Figure 22: Examples of endpoint lookup 1825 7. Security policies 1827 The Resource Directory (RD) provides assistance to applications 1828 situated on a selection of nodes to discover endpoints on connected 1829 nodes. This section discusses different security aspects of 1830 accessing the RD. 1832 The contents of the RD are inserted in two ways: 1834 1. The node hosting the discoverable endpoint fills the RD with the 1835 contents of /.well-known/core by: 1837 * Storing the contents directly into RD (see Section 5) 1839 * Requesting the RD to load the contents from /.well-known/core 1840 (see Section 5.1) 1842 2. A Commissioning Tool (CT) fills the RD with endpoint information 1843 for a set of discoverable nodes. (see Section 5 with 1844 base=authority parameter value) 1846 In both cases, the nodes filling the RD should be authenticated and 1847 authorized to change the contents of the RD. An Authorization Server 1848 (AS) is responsible to assign a token to the registering node to 1849 authorize the node to discover or register endpoints in a given RD 1850 [I-D.ietf-ace-oauth-authz]. 1852 It can be imagined that an installation is divided in a set of 1853 security regions, each one with its own RD(s) to discover the 1854 endpoints that are part of a given security region. An endpoint that 1855 wants to discover an RD, responsible for a given region, needs to be 1856 authorized to learn the contents of a given RD. Within a region, for 1857 a given RD, a more fine-grained security division is possible based 1858 on the values of the endpoint registration parameters. Authorization 1859 to discover endpoints with a given set of filter values is 1860 recommended for those cases. 1862 When a node registers its endpoints, criteria are needed to authorize 1863 the node to enter them. An important aspect is the uniqueness of the 1864 (endpoint name, and optional sector) pair within the RD. Consider 1865 the two cases separately: (1) CT registers endpoints, and (2) the 1866 registering node registers its own endpoint(s). 1868 * A CT needs authorization to register a set of endpoints. This 1869 authorization can be based on the region, i.e. a given CT is 1870 authorized to register any endpoint (endpoint name, sector) into a 1871 given RD, or to register an endpoint with (endpoint name, sector) 1872 value pairs assigned by the AS, or can be more fine-grained, 1873 including a subset of registration parameter values. 1875 * A given endpoint that registers itself, needs to proof its 1876 possession of its unique (endpoint name, sector) value pair. 1877 Alternatively, the AS can authorize the endpoint to register with 1878 an (endpoint name, sector) value pair assigned by the AS. 1880 A separate document needs to specify these aspects to ensure 1881 interoperability between registering nodes and RD. The subsections 1882 below give some hints how to handle a subset of the different 1883 aspects. 1885 7.1. Secure RD discovery 1887 The Resource Server (RS) discussed in [I-D.ietf-ace-oauth-authz] is 1888 equated to the RD. The client (C) needs to discover the RD as 1889 discussed in Section 4.1. C can discover the related AS by sending a 1890 request to the RD. The RD denies the request by sending the address 1891 of the related AS, as discussed in section 5.1 of 1892 [I-D.ietf-ace-oauth-authz]. The client MUST send an authorization 1893 request to the AS. When appropriate, the AS returns a token that 1894 specifies the authorization permission which needs to be specified in 1895 a separate document. 1897 7.2. Secure RD filtering 1899 The authorized parameter values for the queries by a given endpoint 1900 must be registered by the AS. The AS communicates the parameter 1901 values in the token. A separate document needs to specify the 1902 parameter value combinations and their storage in the token. The RD 1903 decodes the token and checks the validity of the queries of the 1904 client. 1906 7.3. Secure endpoint Name assignment 1908 This section only considers the assignment of a name to the endpoint 1909 based on an automatic mechanism without use of AS. More elaborate 1910 protocols are out of scope. The registering endpoint is authorized 1911 by the AS to discover the RD and add registrations. A token is 1912 provided by the AS and communicated from registering endpoint to RD. 1913 It is assumed that DTLS is used to secure the channel between 1914 registering endpoint and RD, where the registering endpoint is the 1915 DTLS client. Assuming that the client is provided by a certificate 1916 at manufacturing time, the certificate is uniquely identified by the 1917 CN field and the serial number (see [RFC5280] Section 4.1.2.2). The 1918 RD can assign a unique endpoint name by using the certificate 1919 identifier as endpoint name. Proof of possession of the endpoint 1920 name by the registering endpoint is checked by encrypting the 1921 certificate identifier with the private key of the registering 1922 endpoint, which the RD can decrypt with the public key stored in the 1923 certificate. Even simpler, the authorized registering endpoint can 1924 generate a random number (or string) that identifies the endpoint. 1925 The RD can check for the improbable replication of the random value. 1926 The RD MUST check that registering endpoint uses only one random 1927 value for each authorized endpoint. 1929 8. Security Considerations 1931 The security considerations as described in Section 5 of [RFC8288] 1932 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1933 may be protected e.g. using DTLS when hosted on a CoAP server as 1934 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1935 all resource directory interfaces defined in this document. 1937 8.1. Endpoint Identification and Authentication 1939 An Endpoint (name, sector) pair is unique within the et of endpoints 1940 registered by the RD. An Endpoint MUST NOT be identified by its 1941 protocol, port or IP address as these may change over the lifetime of 1942 an Endpoint. 1944 Every operation performed by an Endpoint on a resource directory 1945 SHOULD be mutually authenticated using Pre-Shared Key, Raw Public Key 1946 or Certificate based security. 1948 Consider the following threat: two devices A and B are registered at 1949 a single server. Both devices have unique, per-device credentials 1950 for use with DTLS to make sure that only parties with authorization 1951 to access A or B can do so. 1953 Now, imagine that a malicious device A wants to sabotage the device 1954 B. It uses its credentials during the DTLS exchange. Then, it 1955 specifies the endpoint name of device B as the name of its own 1956 endpoint in device A. If the server does not check whether the 1957 identifier provided in the DTLS handshake matches the identifier used 1958 at the CoAP layer then it may be inclined to use the endpoint name 1959 for looking up what information to provision to the malicious device. 1961 Section 7.3 specifies an example that removes this threat for 1962 endpoints that have a certificate installed. 1964 8.2. Access Control 1966 Access control SHOULD be performed separately for the RD registration 1967 and Lookup API paths, as different endpoints may be authorized to 1968 register with an RD from those authorized to lookup endpoints from 1969 the RD. Such access control SHOULD be performed in as fine-grained a 1970 level as possible. For example access control for lookups could be 1971 performed either at the sector, endpoint or resource level. 1973 8.3. Denial of Service Attacks 1975 Services that run over UDP unprotected are vulnerable to unknowingly 1976 become part of a DDoS attack as UDP does not require return 1977 routability check. Therefore, an attacker can easily spoof the 1978 source IP of the target entity and send requests to such a service 1979 which would then respond to the target entity. This can be used for 1980 large-scale DDoS attacks on the target. Especially, if the service 1981 returns a response that is order of magnitudes larger than the 1982 request, the situation becomes even worse as now the attack can be 1983 amplified. DNS servers have been widely used for DDoS amplification 1984 attacks. There is also a danger that NTP Servers could become 1985 implicated in denial-of-service (DoS) attacks since they run on 1986 unprotected UDP, there is no return routability check, and they can 1987 have a large amplification factor. The responses from the NTP server 1988 were found to be 19 times larger than the request. A Resource 1989 Directory (RD) which responds to wild-card lookups is potentially 1990 vulnerable if run with CoAP over UDP. Since there is no return 1991 routability check and the responses can be significantly larger than 1992 requests, RDs can unknowingly become part of a DDoS amplification 1993 attack. 1995 9. IANA Considerations 1997 9.1. Resource Types 1999 IANA is asked to enter the following values into the Resource Type 2000 (rt=) Link Target Attribute Values sub-registry of the Constrained 2001 Restful Environments (CoRE) Parameters registry defined in [RFC6690]: 2003 +--------------------+-----------------------------+-------------+ 2004 | Value | Description | Reference | 2005 +====================+=============================+=============+ 2006 | core.rd | Directory resource of an RD | RFCTHIS | 2007 | | | Section 4.3 | 2008 +--------------------+-----------------------------+-------------+ 2009 | core.rd-lookup-res | Resource lookup of an RD | RFCTHIS | 2010 | | | Section 4.3 | 2011 +--------------------+-----------------------------+-------------+ 2012 | core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS | 2013 | | | Section 4.3 | 2014 +--------------------+-----------------------------+-------------+ 2015 | core.rd-ep | Endpoint resource of an RD | RFCTHIS | 2016 | | | Section 6 | 2017 +--------------------+-----------------------------+-------------+ 2019 Table 2 2021 9.2. IPv6 ND Resource Directory Address Option 2023 This document registers one new ND option type under the sub-registry 2024 "IPv6 Neighbor Discovery Option Formats": 2026 * Resource Directory Address Option (TBD38) 2028 [ The RFC editor is asked to replace TBD38 with the assigned number 2029 in the document; the value 38 is suggested. ] 2031 9.3. RD Parameter Registry 2033 This specification defines a new sub-registry for registration and 2034 lookup parameters called "RD Parameters" under "CoRE Parameters". 2035 Although this specification defines a basic set of parameters, it is 2036 expected that other standards that make use of this interface will 2037 define new ones. 2039 Each entry in the registry must include 2040 * the human readable name of the parameter, 2042 * the short name as used in query parameters or target attributes, 2044 * indication of whether it can be passed as a query parameter at 2045 registration of endpoints, as a query parameter in lookups, or be 2046 expressed as a target attribute, 2048 * validity requirements if any, 2050 * a description, 2052 * and a link to reference documentation. 2054 The query parameter MUST be both a valid URI query key [RFC3986] and 2055 a token as used in [RFC8288]. 2057 The description must give details on whether the parameter can be 2058 updated, and how it is to be processed in lookups. 2060 The mechanisms around new RD parameters should be designed in such a 2061 way that they tolerate RD implementations that are unaware of the 2062 parameter and expose any parameter passed at registration or updates 2063 on in endpoint lookups. (For example, if a parameter used at 2064 registration were to be confidential, the registering endpoint should 2065 be instructed to only set that parameter if the RD advertises support 2066 for keeping it confidential at the discovery step.) 2068 Initial entries in this sub-registry are as follows: 2070 +--------------+-------+--------------+-----+---------------------+ 2071 | Full name | Short | Validity | Use | Description | 2072 +==============+=======+==============+=====+=====================+ 2073 | Endpoint | ep | Unicode* | RLA | Name of the | 2074 | Name | | | | endpoint | 2075 +--------------+-------+--------------+-----+---------------------+ 2076 | Lifetime | lt | 1-4294967295 | R | Lifetime of the | 2077 | | | | | registration in | 2078 | | | | | seconds | 2079 +--------------+-------+--------------+-----+---------------------+ 2080 | Sector | d | Unicode* | RLA | Sector to which | 2081 | | | | | this endpoint | 2082 | | | | | belongs | 2083 +--------------+-------+--------------+-----+---------------------+ 2084 | Registration | base | URI | RLA | The scheme, address | 2085 | Base URI | | | | and port and path | 2086 | | | | | at which this | 2087 | | | | | server is available | 2088 +--------------+-------+--------------+-----+---------------------+ 2089 | Page | page | Integer | L | Used for pagination | 2090 +--------------+-------+--------------+-----+---------------------+ 2091 | Count | count | Integer | L | Used for pagination | 2092 +--------------+-------+--------------+-----+---------------------+ 2093 | Endpoint | et | Section | RLA | Semantic type of | 2094 | Type | | 9.3.1 | | the endpoint (see | 2095 | | | | | Section 9.4) | 2096 +--------------+-------+--------------+-----+---------------------+ 2098 Table 3: RD Parameters 2100 (Short: Short name used in query parameters or target attributes. 2101 Validity: Unicode* = 63 Bytes of UTF-8 encoded Unicode, with no 2102 control characters as per Section 5. Use: R = used at registration, 2103 L = used at lookup, A = expressed in target attribute 2105 The descriptions for the options defined in this document are only 2106 summarized here. To which registrations they apply and when they are 2107 to be shown is described in the respective sections of this document. 2108 All their reference documentation entries point to this document. 2110 The IANA policy for future additions to the sub-registry is "Expert 2111 Review" as described in [RFC8126]. The evaluation should consider 2112 formal criteria, duplication of functionality (Is the new entry 2113 redundant with an existing one?), topical suitability (E.g. is the 2114 described property actually a property of the endpoint and not a 2115 property of a particular resource, in which case it should go into 2116 the payload of the registration and need not be registered?), and the 2117 potential for conflict with commonly used target attributes (For 2118 example, "if" could be used as a parameter for conditional 2119 registration if it were not to be used in lookup or attributes, but 2120 would make a bad parameter for lookup, because a resource lookup with 2121 an "if" query parameter could ambiguously filter by the registered 2122 endpoint property or the [RFC6690] target attribute). It is expected 2123 that the registry will receive between 5 and 50 registrations in 2124 total over the next years. 2126 9.3.1. Full description of the "Endpoint Type" Registration Parameter 2128 An endpoint registering at an RD can describe itself with endpoint 2129 types, similar to how resources are described with Resource Types in 2130 [RFC6690]. An endpoint type is expressed as a string, which can be 2131 either a URI or one of the values defined in the Endpoint Type sub- 2132 registry. Endpoint types can be passed in the "et" query parameter 2133 as part of extra-attrs at the Registration step, are shown on 2134 endpoint lookups using the "et" target attribute, and can be filtered 2135 for using "et" as a search criterion in resource and endpoint lookup. 2136 Multiple endpoint types are given as separate query parameters or 2137 link attributes. 2139 Note that Endpoint Type differs from Resource Type in that it uses 2140 multiple attributes rather than space separated values. As a result, 2141 Resource Directory implementations automatically support correct 2142 filtering in the lookup interfaces from the rules for unknown 2143 endpoint attributes. 2145 9.4. "Endpoint Type" (et=) RD Parameter values 2147 This specification establishes a new sub-registry under "CoRE 2148 Parameters" called '"Endpoint Type" (et=) RD Parameter values'. The 2149 registry properties (required policy, requirements, template) are 2150 identical to those of the Resource Type parameters in [RFC6690], in 2151 short: 2153 The review policy is IETF Review for values starting with "core", and 2154 Specification Required for others. 2156 The requirements to be enforced are: 2158 * The values MUST be related to the purpose described in 2159 Section 9.3.1. 2161 * The registered values MUST conform to the ABNF reg-rel-type 2162 definition of [RFC6690] and MUST NOT be a URI. 2164 * It is recommended to use the period "." character for 2165 segmentation. 2167 The registry initially contains one value: 2169 * "core.rd-group": An application group as described in Appendix A. 2171 9.5. Multicast Address Registration 2173 IANA is asked to assign the following multicast addresses for use by 2174 CoAP nodes: 2176 IPv4 - "all CoRE resource directories" address MCD2 (suggestion: 2177 224.0.1.189), from the "IPv4 Multicast Address Space Registry". As 2178 the address is used for discovery that may span beyond a single 2179 network, it has come from the Internetwork Control Block (224.0.1.x, 2180 RFC 5771). 2182 IPv6 - "all CoRE resource directories" address MCD1 (suggestions 2183 FF0X::FE), from the "IPv6 Multicast Address Space Registry", in the 2184 "Variable Scope Multicast Addresses" space (RFC 3307). Note that 2185 there is a distinct multicast address for each scope that interested 2186 CoAP nodes should listen to; CoAP needs the Link-Local and Site-Local 2187 scopes only. 2189 [ The RFC editor is asked to replace MCD1 and MCD2 with the assigned 2190 addresses throughout the document. ] 2192 9.6. Well-Kown URIs 2194 IANA is asked to extend the reference for the "core" URI suffix in 2195 the "Well-Known URIs" registry to reference this document next to 2196 [RFC6690], as this defines the resource's behavior for POST requests. 2198 9.7. Service Names and Transport Protocol Port Number Registry 2200 IANA is asked to enter four new items into the Service Names and 2201 Transport Protocol Port Number Registry: 2203 * Service name: "core-rd", Protocol: "udp", Description: "Resource 2204 Directory accessed using CoAP" 2206 * Service name "core-rd-dtls", Protocol: "udp", Description: 2207 "Resource Directory accedded using CoAP over DTLS" 2209 * Service name: "core-rd", Protocol: "tcp", Description: "Resource 2210 Directory accessed using CoAP over TCP" 2212 * Service name "core-rd-tls", Protocol: "tcp", Description: 2213 "Resource Directory accedded using CoAP over TLS" 2215 All in common have this document as their reference. 2217 10. Examples 2219 Two examples are presented: a Lighting Installation example in 2220 Section 10.1 and a LWM2M example in Section 10.2. 2222 10.1. Lighting Installation 2224 This example shows a simplified lighting installation which makes use 2225 of the Resource Directory (RD) with a CoAP interface to facilitate 2226 the installation and start-up of the application code in the lights 2227 and sensors. In particular, the example leads to the definition of a 2228 group and the enabling of the corresponding multicast address as 2229 described in Appendix A. No conclusions must be drawn on the 2230 realization of actual installation or naming procedures, because the 2231 example only "emphasizes" some of the issues that may influence the 2232 use of the RD and does not pretend to be normative. 2234 10.1.1. Installation Characteristics 2236 The example assumes that the installation is managed. That means 2237 that a Commissioning Tool (CT) is used to authorize the addition of 2238 nodes, name them, and name their services. The CT can be connected 2239 to the installation in many ways: the CT can be part of the 2240 installation network, connected by WiFi to the installation network, 2241 or connected via GPRS link, or other method. 2243 It is assumed that there are two naming authorities for the 2244 installation: (1) the network manager that is responsible for the 2245 correct operation of the network and the connected interfaces, and 2246 (2) the lighting manager that is responsible for the correct 2247 functioning of networked lights and sensors. The result is the 2248 existence of two naming schemes coming from the two managing 2249 entities. 2251 The example installation consists of one presence sensor, and two 2252 luminaries, luminary1 and luminary2, each with their own wireless 2253 interface. Each luminary contains three lamps: left, right and 2254 middle. Each luminary is accessible through one endpoint. For each 2255 lamp a resource exists to modify the settings of a lamp in a 2256 luminary. The purpose of the installation is that the presence 2257 sensor notifies the presence of persons to a group of lamps. The 2258 group of lamps consists of: middle and left lamps of luminary1 and 2259 right lamp of luminary2. 2261 Before commissioning by the lighting manager, the network is 2262 installed and access to the interfaces is proven to work by the 2263 network manager. 2265 At the moment of installation, the network under installation is not 2266 necessarily connected to the DNS infra structure. Therefore, SLAAC 2267 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 2268 Table 4 below: 2270 +--------------------+----------------+ 2271 | Name | IPv6 address | 2272 +====================+================+ 2273 | luminary1 | 2001:db8:4::1 | 2274 +--------------------+----------------+ 2275 | luminary2 | 2001:db8:4::2 | 2276 +--------------------+----------------+ 2277 | Presence sensor | 2001:db8:4::3 | 2278 +--------------------+----------------+ 2279 | Resource directory | 2001:db8:4::ff | 2280 +--------------------+----------------+ 2282 Table 4: interface SLAAC addresses 2284 In Section 10.1.2 the use of resource directory during installation 2285 is presented. 2287 10.1.2. RD entries 2289 It is assumed that access to the DNS infrastructure is not always 2290 possible during installation. Therefore, the SLAAC addresses are 2291 used in this section. 2293 For discovery, the resource types (rt) of the devices are important. 2294 The lamps in the luminaries have rt: light, and the presence sensor 2295 has rt: p-sensor. The endpoints have names which are relevant to the 2296 light installation manager. In this case luminary1, luminary2, and 2297 the presence sensor are located in room 2-4-015, where luminary1 is 2298 located at the window and luminary2 and the presence sensor are 2299 located at the door. The endpoint names reflect this physical 2300 location. The middle, left and right lamps are accessed via path 2301 /light/middle, /light/left, and /light/right respectively. The 2302 identifiers relevant to the Resource Directory are shown in Table 5 2303 below: 2305 +-----------+------------------+---------------+---------------+ 2306 | Name | endpoint | resource path | resource type | 2307 +===========+==================+===============+===============+ 2308 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 2309 +-----------+------------------+---------------+---------------+ 2310 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 2311 +-----------+------------------+---------------+---------------+ 2312 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 2313 +-----------+------------------+---------------+---------------+ 2314 | luminary2 | lm_R2-4-015_door | /light/left | light | 2315 +-----------+------------------+---------------+---------------+ 2316 | luminary2 | lm_R2-4-015_door | /light/middle | light | 2317 +-----------+------------------+---------------+---------------+ 2318 | luminary2 | lm_R2-4-015_door | /light/right | light | 2319 +-----------+------------------+---------------+---------------+ 2320 | Presence | ps_R2-4-015_door | /ps | p-sensor | 2321 | sensor | | | | 2322 +-----------+------------------+---------------+---------------+ 2324 Table 5: Resource Directory identifiers 2326 It is assumed that the CT knows the RD's address, and has performed 2327 URI discovery on it that returned a response like the one in the 2328 Section 4.3 example. 2330 The CT inserts the endpoints of the luminaries and the sensor in the 2331 RD using the registration base URI parameter (base) to specify the 2332 interface address: 2334 Req: POST coap://[2001:db8:4::ff]/rd 2335 ?ep=lm_R2-4-015_wndw&base=coap://[2001:db8:4::1]&d=R2-4-015 2336 Payload: 2337 ;rt="light", 2338 ;rt="light", 2339 ;rt="light" 2341 Res: 2.01 Created 2342 Location-Path: /rd/4521 2344 Req: POST coap://[2001:db8:4::ff]/rd 2345 ?ep=lm_R2-4-015_door&base=coap://[2001:db8:4::2]&d=R2-4-015 2346 Payload: 2347 ;rt="light", 2348 ;rt="light", 2349 ;rt="light" 2351 Res: 2.01 Created 2352 Location-Path: /rd/4522 2354 Req: POST coap://[2001:db8:4::ff]/rd 2355 ?ep=ps_R2-4-015_door&base=coap://[2001:db8:4::3]d&d=R2-4-015 2356 Payload: 2357 ;rt="p-sensor" 2359 Res: 2.01 Created 2360 Location-Path: /rd/4523 2362 Figure 23: Example of registrations a CT enters into an RD 2364 The sector name d=R2-4-015 has been added for an efficient lookup 2365 because filtering on "ep" name is more awkward. The same sector name 2366 is communicated to the two luminaries and the presence sensor by the 2367 CT. 2369 The group is specified in the RD. The base parameter is set to the 2370 site-local multicast address allocated to the group. In the POST in 2371 the example below, the resources supported by all group members are 2372 published. 2374 Req: POST coap://[2001:db8:4::ff]/rd 2375 ?ep=grp_R2-4-015&et=core.rd-group&base=coap://[ff05::1] 2376 Payload: 2377 ;rt="light", 2378 ;rt="light", 2379 ;rt="light" 2381 Res: 2.01 Created 2382 Location-Path: /rd/501 2384 Figure 24: Example of a multicast group a CT enters into an RD 2386 After the filling of the RD by the CT, the application in the 2387 luminaries can learn to which groups they belong, and enable their 2388 interface for the multicast address. 2390 The luminary, knowing its sector and being configured to join any 2391 group containing lights, searches for candidate groups and joins 2392 them: 2394 Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep 2395 ?d=R2-4-015&et=core.rd-group&rt=light 2397 Res: 2.05 Content 2398 ;ep="grp_R2-4-015";et="core.rd-group"; 2399 base="coap://[ff05::1]";rt="core.rd-ep" 2401 Figure 25: Example of a lookup exchange to find suitable 2402 multicast addresses 2404 From the returned base parameter value, the luminary learns the 2405 multicast address of the multicast group. 2407 Alternatively, the CT can communicate the multicast address directly 2408 to the luminaries by using the "coap-group" resource specified in 2409 [RFC7390]. 2411 Req: POST coap://[2001:db8:4::1]/coap-group 2412 Content-Format: application/coap-group+json 2413 Payload: 2414 { "a": "[ff05::1]", "n": "grp_R2-4-015"} 2416 Res: 2.01 Created 2417 Location-Path: /coap-group/1 2419 Figure 26: Example use of direct multicast address configuration 2421 Dependent on the situation, only the address, "a", or the name, "n", 2422 is specified in the coap-group resource. 2424 The presence sensor can learn the presence of groups that support 2425 resources with rt=light in its own sector by sending the same 2426 request, as used by the luminary. The presence sensor learns the 2427 multicast address to use for sending messages to the luminaries. 2429 10.2. OMA Lightweight M2M (LWM2M) Example 2431 This example shows how the OMA LWM2M specification makes use of 2432 Resource Directory (RD). 2434 OMA LWM2M is a profile for device services based on CoAP(OMA Name 2435 Authority). LWM2M defines a simple object model and a number of 2436 abstract interfaces and operations for device management and device 2437 service enablement. 2439 An LWM2M server is an instance of an LWM2M middleware service layer, 2440 containing a Resource Directory along with other LWM2M interfaces 2441 defined by the LWM2M specification. 2443 CoRE Resource Directory (RD) is used to provide the LWM2M 2444 Registration interface. 2446 LWM2M does not provide for registration sectors and does not 2447 currently use the rd-lookup interface. 2449 The LWM2M specification describes a set of interfaces and a resource 2450 model used between a LWM2M device and an LWM2M server. Other 2451 interfaces, proxies, and applications are currently out of scope for 2452 LWM2M. 2454 The location of the LWM2M Server and RD URI path is provided by the 2455 LWM2M Bootstrap process, so no dynamic discovery of the RD is used. 2456 LWM2M Servers and endpoints are not required to implement the /.well- 2457 known/core resource. 2459 10.2.1. The LWM2M Object Model 2461 The OMA LWM2M object model is based on a simple 2 level class 2462 hierarchy consisting of Objects and Resources. 2464 An LWM2M Resource is a REST endpoint, allowed to be a single value or 2465 an array of values of the same data type. 2467 An LWM2M Object is a resource template and container type that 2468 encapsulates a set of related resources. An LWM2M Object represents 2469 a specific type of information source; for example, there is a LWM2M 2470 Device Management object that represents a network connection, 2471 containing resources that represent individual properties like radio 2472 signal strength. 2474 Since there may potentially be more than one of a given type object, 2475 for example more than one network connection, LWM2M defines instances 2476 of objects that contain the resources that represent a specific 2477 physical thing. 2479 The URI template for LWM2M consists of a base URI followed by Object, 2480 Instance, and Resource IDs: 2482 {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- 2483 instance} 2485 The five variables given here are strings. base-uri can also have 2486 the special value "undefined" (sometimes called "null" in RFC 6570). 2487 Each of the variables object-instance, resource-id, and resource- 2488 instance can be the special value "undefined" only if the values 2489 behind it in this sequence also are "undefined". As a special case, 2490 object-instance can be "empty" (which is different from "undefined") 2491 if resource-id is not "undefined". 2493 base-uri := Base URI for LWM2M resources or "undefined" for default 2494 (empty) base URI 2496 object-id := OMNA (OMA Name Authority) registered object ID (0-65535) 2498 object-instance := Object instance identifier (0-65535) or 2499 "undefined"/"empty" (see above)) to refer to all instances of an 2500 object ID 2502 resource-id := OMNA (OMA Name Authority) registered resource ID 2503 (0-65535) or "undefined" to refer to all resources within an instance 2505 resource-instance := Resource instance identifier or "undefined" to 2506 refer to single instance of a resource 2508 LWM2M IDs are 16 bit unsigned integers represented in decimal (no 2509 leading zeroes except for the value 0) by URI format strings. For 2510 example, a LWM2M URI might be: 2512 /1/0/1 2514 The base uri is empty, the Object ID is 1, the instance ID is 0, the 2515 resource ID is 1, and the resource instance is "undefined". This 2516 example URI points to internal resource 1, which represents the 2517 registration lifetime configured, in instance 0 of a type 1 object 2518 (LWM2M Server Object). 2520 10.2.2. LWM2M Register Endpoint 2522 LWM2M defines a registration interface based on the REST API, 2523 described in Section 5. The RD registration URI path of the LWM2M 2524 Resource Directory is specified to be "/rd". 2526 LWM2M endpoints register object IDs, for example , to indicate 2527 that a particular object type is supported, and register object 2528 instances, for example , to indicate that a particular instance 2529 of that object type exists. 2531 Resources within the LWM2M object instance are not registered with 2532 the RD, but may be discovered by reading the resource links from the 2533 object instance using GET with a CoAP Content-Format of application/ 2534 link-format. Resources may also be read as a structured object by 2535 performing a GET to the object instance with a Content-Format of 2536 senml+json. 2538 When an LWM2M object or instance is registered, this indicates to the 2539 LWM2M server that the object and its resources are available for 2540 management and service enablement (REST API) operations. 2542 LWM2M endpoints may use the following RD registration parameters as 2543 defined in Table 3 : 2545 ep - Endpoint Name 2546 lt - registration lifetime 2548 Endpoint Name, Lifetime, and LWM2M Version are mandatory parameters 2549 for the register operation, all other registration parameters are 2550 optional. 2552 Additional optional LWM2M registration parameters are defined: 2554 +---------+-------+-------------------------------+-------------+ 2555 | Name | Query | Validity | Description | 2556 +=========+=======+===============================+=============+ 2557 | Binding | b | {"U",UQ","S","SQ","US","UQS"} | Available | 2558 | Mode | | | Protocols | 2559 +---------+-------+-------------------------------+-------------+ 2560 +---------+-------+-------------------------------+-------------+ 2561 | LWM2M | ver | 1.0 | Spec | 2562 | Version | | | Version | 2563 +---------+-------+-------------------------------+-------------+ 2564 +---------+-------+-------------------------------+-------------+ 2565 | SMS | sms | | MSISDN | 2566 | Number | | | | 2567 +---------+-------+-------------------------------+-------------+ 2569 Table 6: LWM2M Additional Registration Parameters 2571 The following RD registration parameters are not currently specified 2572 for use in LWM2M: 2574 et - Endpoint Type 2575 base - Registration Base URI 2577 The endpoint registration must include a payload containing links to 2578 all supported objects and existing object instances, optionally 2579 including the appropriate link-format relations. 2581 Here is an example LWM2M registration payload: 2583 ,,, 2585 This link format payload indicates that object ID 1 (LWM2M Server 2586 Object) is supported, with a single instance 0 existing, object ID 3 2587 (LWM2M Device object) is supported, with a single instance 0 2588 existing, and object 5 (LWM2M Firmware Object) is supported, with no 2589 existing instances. 2591 10.2.3. LWM2M Update Endpoint Registration 2593 The LwM2M update is really very similar to the registration update as 2594 described in Section 5.3.1, with the only difference that there are 2595 more parameters defined and available. All the parameters listed in 2596 that section are also available with the initial registration but are 2597 all optional: 2599 lt - Registration Lifetime 2600 b - Protocol Binding 2601 sms - MSISDN 2602 link payload - new or modified links 2604 A Registration update is also specified to be used to update the 2605 LWM2M server whenever the endpoint's UDP port or IP address are 2606 changed. 2608 10.2.4. LWM2M De-Register Endpoint 2610 LWM2M allows for de-registration using the delete method on the 2611 returned location from the initial registration operation. LWM2M de- 2612 registration proceeds as described in Section 5.3.2. 2614 11. Acknowledgments 2616 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2617 Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, 2618 Hannes Tschofenig, Sampo Ukkola, Linyi Tian, Jan Newmarch, Matthias 2619 Kovatsch, Jaime Jimenez and Ted Lemon have provided helpful comments, 2620 discussions and ideas to improve and shape this document. Zach would 2621 also like to thank his colleagues from the EU FP7 SENSEI project, 2622 where many of the resource directory concepts were originally 2623 developed. 2625 12. Changelog 2627 changes from -23 to -24 2629 * Discovery using DNS-SD added again 2631 * Minimum lifetime (lt) reduced from 60 to 1 2633 * References added 2635 * IANA considerations 2637 - added about .well-known/core resource 2639 - added DNS-SD service names 2641 - made RDAO option number a suggestion 2643 - added "reference" field to endpoint type registry 2645 * Lookup: mention that anchor is a legitimate lookup attribute 2646 * Terminology and example fixes 2648 * Layout fixes, esp. the use of non-ASCII characters in figures 2650 changes from -22 to -23 2652 * Explain that updates can not remove attributes 2654 * Typo fixes 2656 changes from -21 to -22 2658 * Request a dedicated IPv4 address from IANA (rather than sharing 2659 with All CoAP nodes) 2661 * Fix erroneous examples 2663 * Editorial changes 2665 - Add figure numbers to examples 2667 - Update RD parameters table to reflect changes of earlier 2668 versions in the text 2670 - Typos and minor wording 2672 changes from -20 to -21 2674 (Processing comments during WGLC) 2676 * Defer outdated description of using DNS-SD to find an RD to the 2677 defining document 2679 * Describe operational conditions in automation example 2681 * Recommend particular discovery mechanisms for some managed network 2682 scenarios 2684 changes from -19 to -20 2686 (Processing comments from the WG chair review) 2688 * Define the permissible characters in endpoint and sector names 2690 * Express requirements on NAT situations in more abstract terms 2692 * Shifted heading levels to have the interfaces on the same level 2693 * Group instructions for error handling into general section 2695 * Simple Registration: process reflowed into items list 2697 * Updated introduction to reflect state of CoRE in general, 2698 reference RFC7228 (defining "constrained") and use "IoT" term in 2699 addition to "M2M" 2701 * Update acknowledgements 2703 * Assorted editorial changes 2705 - Unify examples style 2707 - Terminology: RDAO defined and not only expanded 2709 - Add CT to Figure 1 2711 - Consistency in the use of the term "Content Format" 2713 changes from -18 to -19 2715 * link-local addresses: allow but prescribe split-horizon fashion 2716 when used, disallow zone identifiers 2718 * Remove informative references to documents not mentioned any more 2720 changes from -17 to -18 2722 * Rather than re-specifying link format (Modernized Link Format), 2723 describe a Limited Link Format that's the uncontested subset of 2724 Link Format 2726 * Acknowledging the -17 version as part of the draft 2728 * Move "Read endpoint links" operation to future specification like 2729 PATCH 2731 * Demote links-json to an informative reference, and removed them 2732 from exchange examples 2734 * Add note on unusability of link-local IP addresses, and describe 2735 mitigation. 2737 * Reshuffling of sections: Move additional operations and endpoint 2738 lookup back from appendix, and groups into one 2740 * Lookup interface tightened to not imply applicability for non 2741 link-format lookups (as those can have vastly different views on 2742 link cardinality) 2744 * Simple registration: Change sequence of GET and POST-response, 2745 ensuring unsuccessful registrations are reported as such, and 2746 suggest how devices that would have required the inverse behavior 2747 can still cope with it. 2749 * Abstract and introduction reworded to avoid the impression that 2750 resources are stored in full in the RD 2752 * Simplify the rules governing when a registration resource can or 2753 must be changed. 2755 * Drop a figure that has become useless due to the changes of and 2756 -13 and -17 2758 * Wording consistency fixes: Use "Registrations" and "target 2759 attributes" 2761 * Fix incorrect use of content negotiation in discovery interface 2762 description (Content-Format -> Accept) 2764 * State that the base attribute value is part of endpoint lookup 2765 even when implicit in the registration 2767 * Update references from RFC5988 to its update RFC8288 2769 * Remove appendix on protocol-negotiation (which had a note to be 2770 removed before publication) 2772 changes from -16 to -17 2774 (Note that -17 is published as a direct follow-up to -16, containing 2775 a single change to be discussed at IETF103) 2777 * Removed groups that are enumerations of registrations and have 2778 dedicated mechanism 2780 * Add groups that are enumerations of shared resources and are a 2781 special case of endpoint registrations 2783 changes from -15 to -16 2785 * Recommend a common set of resources for members of a group 2787 * Clarified use of multicast group in lighting example 2788 * Add note on concurrent registrations from one EP being possible 2789 but not expected 2791 * Refresh web examples appendix to reflect current use of Modernized 2792 Link Format 2794 * Add examples of URIs where Modernized Link Format matters 2796 * Editorial changes 2798 changes from -14 to -15 2800 * Rewrite of section "Security policies" 2802 * Clarify that the "base" parameter text applies both to relative 2803 references both in anchor and href 2805 * Renamed "Registree-EP" to Registrant-EP" 2807 * Talk of "relative references" and "URIs" rather than "relative" 2808 and "absolute" URIs. (The concept of "absolute URIs" of [RFC3986] 2809 is not needed in RD). 2811 * Fixed examples 2813 * Editorial changes 2815 changes from -13 to -14 2817 * Rename "registration context" to "registration base URI" (and 2818 "con" to "base") and "domain" to "sector" (where the abbreviation 2819 "d" stays for compatibility reasons) 2821 * Introduced resource types core.rd-ep and core.rd-gp 2823 * Registration management moved to appendix A, including endpoint 2824 and group lookup 2826 * Minor editorial changes 2828 - PATCH/iPATCH is clearly deferred to another document 2830 - Recommend against query / fragment identifier in con= 2832 - Interface description lists are described as illustrative 2834 - Rewording of Simple Registration 2836 * Simple registration carries no error information and succeeds 2837 immediately (previously, sequence was unspecified) 2839 * Lookup: href are matched against resolved values (previously, this 2840 was unspecified) 2842 * Lookup: lt are not exposed any more 2844 * con/base: Paths are allowed 2846 * Registration resource locations can not have query or fragment 2847 parts 2849 * Default life time extended to 25 hours 2851 * clarified registration update rules 2853 * lt-value semantics for lookup clarified. 2855 * added template for simple registration 2857 changes from -12 to -13 2859 * Added "all resource directory" nodes MC address 2861 * Clarified observation behavior 2863 * version identification 2865 * example rt= and et= values 2867 * domain from figure 2 2869 * more explanatory text 2871 * endpoints of a groups hosted by different RD 2873 * resolve RFC6690-vs-8288 resolution ambiguities: 2875 - require registered links not to be relative when using anchor 2877 - return absolute URIs in resource lookup 2879 changes from -11 to -12 2881 * added Content Model section, including ER diagram 2882 * removed domain lookup interface; domains are now plain attributes 2883 of groups and endpoints 2885 * updated chapter "Finding a Resource Directory"; now distinguishes 2886 configuration-provided, network-provided and heuristic sources 2888 * improved text on: atomicity, idempotency, lookup with multiple 2889 parameters, endpoint removal, simple registration 2891 * updated LWM2M description 2893 * clarified where relative references are resolved, and how context 2894 and anchor interact 2896 * new appendix on the interaction with RFCs 6690, 5988 and 3986 2898 * lookup interface: group and endpoint lookup return group and 2899 registration resources as link targets 2901 * lookup interface: search parameters work the same across all 2902 entities 2904 * removed all methods that modify links in an existing registration 2905 (POST with payload, PATCH and iPATCH) 2907 * removed plurality definition (was only needed for link 2908 modification) 2910 * enhanced IANA registry text 2912 * state that lookup resources can be observable 2914 * More examples and improved text 2916 changes from -09 to -10 2918 * removed "ins" and "exp" link-format extensions. 2920 * removed all text concerning DNS-SD. 2922 * removed inconsistency in RDAO text. 2924 * suggestions taken over from various sources 2926 * replaced "Function Set" with "REST API", "base URI", "base path" 2928 * moved simple registration to registration section 2929 changes from -08 to -09 2931 * clarified the "example use" of the base RD resource values /rd, 2932 /rd-lookup, and /rd-group. 2934 * changed "ins" ABNF notation. 2936 * various editorial improvements, including in examples 2938 * clarifications for RDAO 2940 changes from -07 to -08 2942 * removed link target value returned from domain and group lookup 2943 types 2945 * Maximum length of domain parameter 63 bytes for consistency with 2946 group 2948 * removed option for simple POST of link data, don't require a 2949 .well-known/core resource to accept POST data and handle it in a 2950 special way; we already have /rd for that 2952 * add IPv6 ND Option for discovery of an RD 2954 * clarify group configuration section 6.1 that endpoints must be 2955 registered before including them in a group 2957 * removed all superfluous client-server diagrams 2959 * simplified lighting example 2961 * introduced Commissioning Tool 2963 * RD-Look-up text is extended. 2965 changes from -06 to -07 2967 * added text in the discovery section to allow content format hints 2968 to be exposed in the discovery link attributes 2970 * editorial updates to section 9 2972 * update author information 2974 * minor text corrections 2976 Changes from -05 to -06 2977 * added note that the PATCH section is contingent on the progress of 2978 the PATCH method 2980 changes from -04 to -05 2982 * added Update Endpoint Links using PATCH 2984 * http access made explicit in interface specification 2986 * Added http examples 2988 Changes from -03 to -04: 2990 * Added http response codes 2992 * Clarified endpoint name usage 2994 * Add application/link-format+cbor content-format 2996 Changes from -02 to -03: 2998 * Added an example for lighting and DNS integration 3000 * Added an example for RD use in OMA LWM2M 3002 * Added Read Links operation for link inspection by endpoints 3004 * Expanded DNS-SD section 3006 * Added draft authors Peter van der Stok and Michael Koster 3008 Changes from -01 to -02: 3010 * Added a catalogue use case. 3012 * Changed the registration update to a POST with optional link 3013 format payload. Removed the endpoint type update from the update. 3015 * Additional examples section added for more complex use cases. 3017 * New DNS-SD mapping section. 3019 * Added text on endpoint identification and authentication. 3021 * Error code 4.04 added to Registration Update and Delete requests. 3023 * Made 63 bytes a SHOULD rather than a MUST for endpoint name and 3024 resource type parameters. 3026 Changes from -00 to -01: 3028 * Removed the ETag validation feature. 3030 * Place holder for the DNS-SD mapping section. 3032 * Explicitly disabled GET or POST on returned Location. 3034 * New registry for RD parameters. 3036 * Added support for the JSON Link Format. 3038 * Added reference to the Groupcomm WG draft. 3040 Changes from -05 to WG Document -00: 3042 * Updated the version and date. 3044 Changes from -04 to -05: 3046 * Restricted Update to parameter updates. 3048 * Added pagination support for the Lookup interface. 3050 * Minor editing, bug fixes and reference updates. 3052 * Added group support. 3054 * Changed rt to et for the registration and update interface. 3056 Changes from -03 to -04: 3058 * Added the ins= parameter back for the DNS-SD mapping. 3060 * Integrated the Simple Directory Discovery from Carsten. 3062 * Editorial improvements. 3064 * Fixed the use of ETags. 3066 * Fixed tickets 383 and 372 3068 Changes from -02 to -03: 3070 * Changed the endpoint name back to a single registration parameter 3071 ep= and removed the h= and ins= parameters. 3073 * Updated REST interface descriptions to use RFC6570 URI Template 3074 format. 3076 * Introduced an improved RD Lookup design as its own function set. 3078 * Improved the security considerations section. 3080 * Made the POST registration interface idempotent by requiring the 3081 ep= parameter to be present. 3083 Changes from -01 to -02: 3085 * Added a terminology section. 3087 * Changed the inclusion of an ETag in registration or update to a 3088 MAY. 3090 * Added the concept of an RD Domain and a registration parameter for 3091 it. 3093 * Recommended the Location returned from a registration to be 3094 stable, allowing for endpoint and Domain information to be changed 3095 during updates. 3097 * Changed the lookup interface to accept endpoint and Domain as 3098 query string parameters to control the scope of a lookup. 3100 13. References 3102 13.1. Normative References 3104 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3105 Requirement Levels", BCP 14, RFC 2119, 3106 DOI 10.17487/RFC2119, March 1997, 3107 . 3109 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3110 Resource Identifier (URI): Generic Syntax", STD 66, 3111 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3112 . 3114 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3115 and D. Orchard, "URI Template", RFC 6570, 3116 DOI 10.17487/RFC6570, March 2012, 3117 . 3119 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 3120 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 3121 . 3123 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 3124 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 3125 . 3127 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3128 Writing an IANA Considerations Section in RFCs", BCP 26, 3129 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3130 . 3132 13.2. Informative References 3134 [ER] Chen, P., "The entity-relationship model---toward a 3135 unified view of data", DOI 10.1145/320434.320440, ACM 3136 Transactions on Database Systems Vol. 1, pp. 9-36, March 3137 1976, . 3139 [I-D.bormann-t2trg-rel-impl] 3140 Bormann, C., "impl-info: A link relation type for 3141 disclosing implementation information", Work in Progress, 3142 Internet-Draft, draft-bormann-t2trg-rel-impl-00, 28 3143 January 2018, . 3146 [I-D.hartke-t2trg-coral] 3147 Hartke, K., "The Constrained RESTful Application Language 3148 (CoRAL)", Work in Progress, Internet-Draft, draft-hartke- 3149 t2trg-coral-09, 8 July 2019, . 3152 [I-D.ietf-ace-oauth-authz] 3153 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 3154 H. Tschofenig, "Authentication and Authorization for 3155 Constrained Environments (ACE) using the OAuth 2.0 3156 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 3157 draft-ietf-ace-oauth-authz-33, 6 February 2020, 3158 . 3161 [I-D.ietf-core-links-json] 3162 Li, K., Rahman, A., and C. Bormann, "Representing 3163 Constrained RESTful Environments (CoRE) Link Format in 3164 JSON and CBOR", Work in Progress, Internet-Draft, draft- 3165 ietf-core-links-json-10, 26 February 2018, 3166 . 3169 [I-D.ietf-core-rd-dns-sd] 3170 Stok, P., Koster, M., and C. Amsuess, "CoRE Resource 3171 Directory: DNS-SD mapping", Work in Progress, Internet- 3172 Draft, draft-ietf-core-rd-dns-sd-05, 7 July 2019, 3173 . 3176 [I-D.silverajan-core-coap-protocol-negotiation] 3177 Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation", 3178 Work in Progress, Internet-Draft, draft-silverajan-core- 3179 coap-protocol-negotiation-09, 2 July 2018, 3180 . 3183 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 3184 "Transmission of IPv6 Packets over IEEE 802.15.4 3185 Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007, 3186 . 3188 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3189 Housley, R., and W. Polk, "Internet X.509 Public Key 3190 Infrastructure Certificate and Certificate Revocation List 3191 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3192 . 3194 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 3195 Bormann, "Neighbor Discovery Optimization for IPv6 over 3196 Low-Power Wireless Personal Area Networks (6LoWPANs)", 3197 RFC 6775, DOI 10.17487/RFC6775, November 2012, 3198 . 3200 [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing 3201 IPv6 Zone Identifiers in Address Literals and Uniform 3202 Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, 3203 February 2013, . 3205 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3206 Constrained-Node Networks", RFC 7228, 3207 DOI 10.17487/RFC7228, May 2014, 3208 . 3210 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3211 Protocol (HTTP/1.1): Message Syntax and Routing", 3212 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3213 . 3215 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3216 Application Protocol (CoAP)", RFC 7252, 3217 DOI 10.17487/RFC7252, June 2014, 3218 . 3220 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 3221 the Constrained Application Protocol (CoAP)", RFC 7390, 3222 DOI 10.17487/RFC7390, October 2014, 3223 . 3225 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3226 Application Protocol (CoAP)", RFC 7641, 3227 DOI 10.17487/RFC7641, September 2015, 3228 . 3230 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 3231 FETCH Methods for the Constrained Application Protocol 3232 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 3233 . 3235 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names 3236 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, 3237 . 3239 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3240 DOI 10.17487/RFC8288, October 2017, 3241 . 3243 Appendix A. Groups Registration and Lookup 3245 The RD-Groups usage pattern allows announcing application groups 3246 inside a Resource Directory. 3248 Groups are represented by endpoint registrations. Their base address 3249 is a multicast address, and they SHOULD be entered with the endpoint 3250 type "core.rd-group". The endpoint name can also be referred to as a 3251 group name in this context. 3253 The registration is inserted into the RD by a Commissioning Tool, 3254 which might also be known as a group manager here. It performs third 3255 party registration and registration updates. 3257 The links it registers SHOULD be available on all members that join 3258 the group. Depending on the application, members that lack some 3259 resource MAY be permissible if requests to them fail gracefully. 3261 The following example shows a CT registering a group with the name 3262 "lights" which provides two resources. The directory resource path 3263 /rd is an example RD location discovered in a request similar to 3264 Figure 5. 3266 Req: POST coap://rd.example.com/rd?ep=lights&et=core.rd-group 3267 &base=coap://[ff35:30:2001:db8::1] 3268 Content-Format: 40 3269 Payload: 3270 ;rt="light";if="core.a", 3271 ;if="core.p";u="K" 3273 Res: 2.01 Created 3274 Location-Path: /rd/12 3276 Figure 27: Example registration of a group 3278 In this example, the group manager can easily permit devices that 3279 have no writable color-temperature to join, as they would still 3280 respond to brightness changing commands. Had the group instead 3281 contained a single resource that sets brightness and color 3282 temperature atomically, endpoints would need to support both 3283 properties. 3285 The resources of a group can be looked up like any other resource, 3286 and the group registrations (along with any additional registration 3287 parameters) can be looked up using the endpoint lookup interface. 3289 The following example shows a client performing and endpoint lookup 3290 for all groups. 3292 Req: GET /rd-lookup/ep?et=core.rd-group 3294 Res: 2.05 Content 3295 Payload: 3296 ;ep="GRP_R2-4-015";et="core.rd-group"; 3297 base="coap://[ff05::1]", 3298 ;ep=lights&et=core.rd-group; 3299 base="coap://[ff35:30:2001:db8::1]";rt="core.rd-ep" 3301 Figure 28: Example lookup of groups 3303 The following example shows a client performing a lookup of all 3304 resources of all endpoints (groups) with et=core.rd-group. 3306 Req: GET /rd-lookup/res?et=core.rd-group 3308 ;rt="light";if="core.a"; 3309 et="core.rd-group";anchor="coap://[ff35:30:2001:db8::1]", 3310 ;if="core.p";u="K"; 3311 et="core.rd-group"; 3312 anchor="coap://[ff35:30:2001:db8::1]" 3313 Figure 29: Example lookup of resources inside groups 3315 Appendix B. Web links and the Resource Directory 3317 Understanding the semantics of a link-format document and its URI 3318 references is a journey through different documents ([RFC3986] 3319 defining URIs, [RFC6690] defining link-format documents based on 3320 [RFC8288] which defines Link header fields, and [RFC7252] providing 3321 the transport). This appendix summarizes the mechanisms and 3322 semantics at play from an entry in ".well-known/core" to a resource 3323 lookup. 3325 This text is primarily aimed at people entering the field of 3326 Constrained Restful Environments from applications that previously 3327 did not use web mechanisms. 3329 The explanation of the steps makes some shortcuts in the more 3330 confusing details of [RFC6690], which are justified as all examples 3331 being in Limited Link Format. 3333 B.1. A simple example 3335 Let's start this example with a very simple host, "2001:db8:f0::1". 3336 A client that follows classical CoAP Discovery ([RFC7252] Section 7), 3337 sends the following multicast request to learn about neighbours 3338 supporting resources with resource-type "temperature". 3340 The client sends a link-local multicast: 3342 GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature 3344 RES 2.05 Content 3345 ;rt=temperature;ct=0 3347 Figure 30: Example of direct resource discovery 3349 where the response is sent by the server, "[2001:db8:f0::1]:5683". 3351 While the client - on the practical or implementation side - can just 3352 go ahead and create a new request to "[2001:db8:f0::1]:5683" with 3353 Uri-Path: "temp", the full resolution steps for insertion into and 3354 retrieval from the RD without any shortcuts are: 3356 B.1.1. Resolving the URIs 3358 The client parses the single returned record. The link's target 3359 (sometimes called "href") is ""/temp"", which is a relative URI that 3360 needs resolving. The base URI is used to resolve the reference /temp against. 3363 The Base URI of the requested resource can be composed from the 3364 options of the CoAP GET request by following the steps of [RFC7252] 3365 section 6.5 (with an addition at the end of 8.2) into 3366 ""coap://[2001:db8:f0::1]/.well-known/core"". 3368 Because ""/temp"" starts with a single slash, the record's target is 3369 resolved by replacing the path ""/.well-known/core"" from the Base 3370 URI (section 5.2 [RFC3986]) with the relative target URI ""/temp"" 3371 into ""coap://[2001:db8:f0::1]/temp"". 3373 B.1.2. Interpreting attributes and relations 3375 Some more information but the record's target can be obtained from 3376 the payload: the resource type of the target is "temperature", and 3377 its content format is text/plain (ct=0). 3379 A relation in a web link is a three-part statement that specifies a 3380 named relation between the so-called "context resource" and the 3381 target resource, like "_This page_ has _its table of contents_ at _/ 3382 toc.html_". In link format documents, there is an implicit "host 3383 relation" specified with default parameter: rel="hosts". 3385 In our example, the context resource of the link is the URI specified 3386 in the GET request "coap:://[2001:db8:f0::1]/.well-known/core". A 3387 full English expression of the "host relation" is: 3389 '"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource 3390 "coap://[2001:db8:f0::1]/temp", which is of the resource type 3391 "temperature" and can be accessed using the text/plain content 3392 format.' 3394 B.2. A slightly more complex example 3396 Omitting the "rt=temperature" filter, the discovery query would have 3397 given some more records in the payload: 3399 GET coap://[ff02::fd]:5683/.well-known/core 3401 RES 2.05 Content 3402 ;rt=temperature;ct=0, 3403 ;rt=light-lux;ct=0, 3404 ;anchor="/sensors/temp";rel=alternate, 3405 ;anchor="/temp"; 3406 rel="describedby" 3408 Figure 31: Extended example of direct resource discovery 3410 Parsing the third record, the client encounters the "anchor" 3411 parameter. It is a URI relative to the Base URI of the request and 3412 is thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That 3413 is the context resource of the link, so the "rel" statement is not 3414 about the target and the Base URI any more, but about the target and 3415 the resolved URI. Thus, the third record could be read as 3416 ""coap://[2001:db8:f0::1]/sensors/temp" has an alternate 3417 representation at "coap://[2001:db8:f0::1]/t"". 3419 Following the same resolution steps, the fourth record can be read as 3420 ""coap://[2001:db8:f0::1]/sensors/temp" is described by 3421 "http://www.example.com/sensors/t123"". 3423 B.3. Enter the Resource Directory 3425 The resource directory tries to carry the semantics obtainable by 3426 classical CoAP discovery over to the resource lookup interface as 3427 faithfully as possible. 3429 For the following queries, we will assume that the simple host has 3430 used Simple Registration to register at the resource directory that 3431 was announced to it, sending this request from its UDP port 3432 "[2001:db8:f0::1]:6553": 3434 POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1 3436 Figure 32: Example request starting a simple registration 3438 The resource directory would have accepted the registration, and 3439 queried the simple host's ".well-known/core" by itself. As a result, 3440 the host is registered as an endpoint in the RD with the name 3441 "simple-host1". The registration is active for 90000 seconds, and 3442 the endpoint registration Base URI is ""coap://[2001:db8:f0::1]"" 3443 following the resolution steps described in Appendix B.1.1. It 3444 should be remarked that the Base URI constructed that way always 3445 yields a URI of the form: scheme://authority without path suffix. 3447 If the client now queries the RD as it would previously have issued a 3448 multicast request, it would go through the RD discovery steps by 3449 fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- 3450 lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the 3451 resource lookup endpoint, and issue a request to 3452 "coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive 3453 the following data: 3455 ;rt=temperature;ct=0; 3456 anchor="coap://[2001:db8:f0::1]" 3458 Figure 33: Example payload of a response to a resource lookup 3460 This is not _literally_ the same response that it would have received 3461 from a multicast request, but it contains the equivalent statement: 3463 '"coap://[2001:db8:f0::1]" is hosting the resource 3464 "coap://[2001:db8:f0::1]/temp", which is of the resource type 3465 "temperature" and can be accessed using the text/plain content 3466 format.' 3468 (The difference is whether "/" or "/.well-known/core" hosts the 3469 resources, which does not matter in this application; if it did, the 3470 endpoint would have been more explicit. Actually, /.well-known/core 3471 does NOT host the resource but stores a URI reference to the 3472 resource.) 3474 To complete the examples, the client could also query all resources 3475 hosted at the endpoint with the known endpoint name "simple-host1". 3476 A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1" 3477 would return 3479 ;rt=temperature;ct=0; 3480 anchor="coap://[2001:db8:f0::1]", 3481 ;rt=light-lux;ct=0; 3482 anchor="coap://[2001:db8:f0::1]", 3483 ; 3484 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, 3485 ; 3486 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby" 3488 Figure 34: Extended example payload of a response to a resource 3489 lookup 3491 All the target and anchor references are already in absolute form 3492 there, which don't need to be resolved any further. 3494 Had the simple host done an equivalent full registration with a base= 3495 parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple- 3496 host1.example.com"), that context would have been used to resolve the 3497 relative anchor values instead, giving 3499 ;rt=temperature;ct=0; 3500 anchor="coap+tcp://simple-host1.example.com" 3502 Figure 35: Example payload of a response to a resource lookup 3503 with a dedicated base URI 3505 and analogous records. 3507 B.4. A note on differences between link-format and Link header fields 3509 While link-format and Link header fields look very similar and are 3510 based on the same model of typed links, there are some differences 3511 between [RFC6690] and [RFC8288], which are dealt with differently: 3513 * "Resolving the target against the anchor": [RFC6690] Section 2.1 3514 states that the anchor of a link is used as the Base URI against 3515 which the term inside the angle brackets (the target) is resolved, 3516 falling back to the resource's URI with paths stripped off (its 3517 "Origin"). In contrast to that, [RFC8288] Section B.2 describes 3518 that the anchor is immaterial to the resolution of the target 3519 reference. 3521 RFC6690, in the same section, also states that absent anchors set 3522 the context of the link to the target's URI with its path stripped 3523 off, while according to [RFC8288] Section 3.2, the context is the 3524 resource's base URI. 3526 The rules introduced in Appendix C ensure that an RD does not need 3527 to deal with those differences when processing input data. Lookup 3528 results are required to be absolute references for the same 3529 reason. 3531 * There is no percent encoding in link-format documents. 3533 A link-format document is a UTF-8 encoded string of Unicode 3534 characters and does not have percent encoding, while Link header 3535 fields are practically ASCII strings that use percent encoding for 3536 non-ASCII characters, stating the encoding explicitly when 3537 required. 3539 For example, while a Link header field in a page about a Swedish 3540 city might read 3541 Link: ;rel="live-environment-data" 3543 a link-format document from the same source might describe the 3544 link as 3546 ;rel="live-environment-data" 3548 Parsers and producers of link-format and header fields need to be 3549 aware of this difference. 3551 Appendix C. Limited Link Format 3553 The CoRE Link Format as described in [RFC6690] has been interpreted 3554 differently by implementers, and a strict implementation rules out 3555 some use cases of a Resource Directory (e.g. base values with path 3556 components). 3558 This appendix describes a subset of link format documents called 3559 Limited Link Format. The rules herein are not very limiting in 3560 practice - all examples in RFC6690, and all deployments the authors 3561 are aware of already stick to them - but ease the implementation of 3562 resource directory servers. 3564 It is applicable to representations in the application/link-format 3565 media type, and any other media types that inherit [RFC6690] 3566 Section 2.1. 3568 A link format representation is in Limited Link format if, for each 3569 link in it, the following applies: 3571 * All URI references either follow the URI or the path-absolute ABNF 3572 rule of RFC3986 (i.e. target and anchor each either start with a 3573 scheme or with a single slash), 3575 * if the anchor reference starts with a scheme, the target reference 3576 starts with a scheme as well (i.e. relative references in target 3577 cannot be used when the anchor is a full URI), and 3579 * the application does not care whether links without an explicitly 3580 given anchor have the origin's "/" or "/.well-known/core" resource 3581 as their link context. 3583 Authors' Addresses 3585 Zach Shelby 3586 ARM 3587 150 Rose Orchard 3588 San Jose, 95134 3589 United States of America 3591 Phone: +1-408-203-9434 3592 Email: zach.shelby@arm.com 3594 Michael Koster 3595 SmartThings 3596 665 Clyde Avenue 3597 Mountain View, 94043 3598 United States of America 3600 Phone: +1-707-502-5136 3601 Email: Michael.Koster@smartthings.com 3603 Carsten Bormann 3604 Universitaet Bremen TZI 3605 Postfach 330440 3606 D-28359 Bremen 3607 Germany 3609 Phone: +49-421-218-63921 3610 Email: cabo@tzi.org 3612 Peter van der Stok 3613 consultant 3615 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 3616 Email: consultancy@vanderstok.org 3617 URI: www.vanderstok.org 3619 Christian Amsüss (editor) 3620 Hollandstr. 12/4 3621 1020 3622 Austria 3624 Phone: +43-664-9790639 3625 Email: christian@amsuess.com