idnits 2.17.1 draft-ietf-core-resource-directory-28.txt: -(2): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(3467): 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 5 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == 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 4 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 393 has weird spacing: '... target o----...' == Line 395 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 (7 March 2021) is 1118 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3849' is defined on line 3582, but no explicit reference was found in the text == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-12 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-37 Summary: 1 error (**), 0 flaws (~~), 13 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE C. Amsüss, Ed. 3 Internet-Draft 4 Intended status: Standards Track Z. Shelby 5 Expires: 8 September 2021 ARM 6 M. Koster 7 SmartThings 8 C. Bormann 9 Universitaet Bremen TZI 10 P. van der Stok 11 consultant 12 7 March 2021 14 CoRE Resource Directory 15 draft-ietf-core-resource-directory-28 17 Abstract 19 In many IoT applications, direct discovery of resources is not 20 practical due to sleeping nodes, or networks where multicast traffic 21 is inefficient. These problems can be solved by employing an entity 22 called a Resource Directory (RD), which contains information about 23 resources held on other servers, allowing lookups to be performed for 24 those resources. The input to an RD is composed of links and the 25 output is composed of links constructed from the information stored 26 in the RD. This document specifies the web interfaces that an RD 27 supports for web servers to discover the RD and to register, 28 maintain, lookup and remove information on resources. Furthermore, 29 new target attributes useful 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 8 September 2021. 59 Copyright Notice 61 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . . . 27 93 5.2. Third-party registration . . . . . . . . . . . . . . . . 29 94 5.3. Operations on the Registration Resource . . . . . . . . . 30 95 5.3.1. Registration Update . . . . . . . . . . . . . . . . . 30 96 5.3.2. Registration Removal . . . . . . . . . . . . . . . . 34 97 5.3.3. Further operations . . . . . . . . . . . . . . . . . 34 98 5.3.4. Request freshness . . . . . . . . . . . . . . . . . . 35 99 6. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 37 100 6.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 37 101 6.2. Lookup filtering . . . . . . . . . . . . . . . . . . . . 38 102 6.3. Resource lookup examples . . . . . . . . . . . . . . . . 40 103 6.4. Endpoint lookup . . . . . . . . . . . . . . . . . . . . . 42 104 7. Security policies . . . . . . . . . . . . . . . . . . . . . . 43 105 7.1. Endpoint name . . . . . . . . . . . . . . . . . . . . . . 44 106 7.1.1. Random endpoint names . . . . . . . . . . . . . . . . 44 107 7.2. Entered resources . . . . . . . . . . . . . . . . . . . . 44 108 7.3. Link confidentiality . . . . . . . . . . . . . . . . . . 45 109 7.4. Segmentation . . . . . . . . . . . . . . . . . . . . . . 46 110 7.5. First-Come-First-Remembered: A default policy . . . . . . 46 111 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 112 8.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 48 113 8.2. Endpoint Identification and Authentication . . . . . . . 48 114 8.3. Access Control . . . . . . . . . . . . . . . . . . . . . 49 115 8.4. Denial of Service Attacks . . . . . . . . . . . . . . . . 49 116 8.5. Skipping freshness checks . . . . . . . . . . . . . . . . 50 117 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 118 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 50 119 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 51 120 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 51 121 9.3.1. Full description of the "Endpoint Type" RD 122 Parameter . . . . . . . . . . . . . . . . . . . . . . 54 123 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 54 124 9.5. Multicast Address Registration . . . . . . . . . . . . . 55 125 9.6. Well-Known URIs . . . . . . . . . . . . . . . . . . . . . 55 126 9.7. Service Names and Transport Protocol Port Number 127 Registry . . . . . . . . . . . . . . . . . . . . . . . . 55 128 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 56 129 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 56 130 10.1.1. Installation Characteristics . . . . . . . . . . . . 56 131 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 57 132 10.2. OMA Lightweight M2M (LwM2M) . . . . . . . . . . . . . . 60 133 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 61 134 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 61 135 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 136 13.1. Normative References . . . . . . . . . . . . . . . . . . 76 137 13.2. Informative References . . . . . . . . . . . . . . . . . 77 138 Appendix A. Groups Registration and Lookup . . . . . . . . . . . 80 139 Appendix B. Web links and the Resource Directory . . . . . . . . 82 140 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 82 141 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 82 142 B.1.2. Interpreting attributes and relations . . . . . . . . 83 144 B.2. A slightly more complex example . . . . . . . . . . . . . 83 145 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 84 146 B.4. A note on differences between link-format and Link header 147 fields . . . . . . . . . . . . . . . . . . . . . . . . . 86 148 Appendix C. Limited Link Format . . . . . . . . . . . . . . . . 86 149 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 87 151 1. Introduction 153 In the work on Constrained RESTful Environments (CoRE), a REST 154 architecture suitable for constrained nodes (e.g. with limited RAM 155 and ROM [RFC7228]) and networks (e.g. 6LoWPAN [RFC4944]) has been 156 established and is used in Internet-of-Things (IoT) or machine-to- 157 machine (M2M) applications such as smart energy and building 158 automation. 160 The discovery of resources offered by a constrained server is very 161 important in machine-to-machine applications where there are no 162 humans in the loop and static interfaces result in fragility. The 163 discovery of resources provided by an HTTP Web Server is typically 164 called Web Linking [RFC8288]. The use of Web Linking for the 165 description and discovery of resources hosted by constrained web 166 servers is specified by the CoRE Link Format [RFC6690]. However, 167 [RFC6690] only describes how to discover resources from the web 168 server that hosts them by querying "/.well-known/core". In many 169 constrained scenarios, direct discovery of resources is not practical 170 due to sleeping nodes, or networks where multicast traffic is 171 inefficient. These problems can be solved by employing an entity 172 called a Resource Directory (RD), which contains information about 173 resources held on other servers, allowing lookups to be performed for 174 those resources. 176 This document specifies the web interfaces that an RD supports for 177 web servers to discover the RD and to register, maintain, lookup and 178 remove information on resources. Furthermore, new target attributes 179 useful in conjunction with an RD are defined. Although the examples 180 in this document show the use of these interfaces with CoAP 181 [RFC7252], they can be applied in an equivalent manner to HTTP 182 [RFC7230]. 184 2. Terminology 186 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 187 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 188 "OPTIONAL" in this document are to be interpreted as described in BCP 189 14 [RFC2119] [RFC8174] when, and only when, they appear in all 190 capitals, as shown here. 192 The term "byte" is used in its now customary sense as a synonym for 193 "octet". 195 This specification requires readers to be familiar with all the terms 196 and concepts that are discussed in [RFC3986], [RFC8288] and 197 [RFC6690]. Readers should also be familiar with the terms and 198 concepts discussed in [RFC7252]. To describe the REST interfaces 199 defined in this specification, the URI Template format is used 200 [RFC6570]. 202 This specification makes use of the following additional terminology: 204 resolve against 205 The expression "a URI-reference is _resolved against_ a base URI" 206 is used to describe the process of [RFC3986] Section 5.2. 207 Noteworthy corner cases are that if the URI-reference is a (full) 208 URI and resolved against any base URI, that gives the original 209 full URI, and that resolving an empty URI reference gives the base 210 URI without any fragment identifier. 212 Resource Directory (RD) 213 A web entity that stores information about web resources and 214 implements the REST interfaces defined in this specification for 215 discovery, for the creation, maintenance and removal of 216 registrations, and for lookup of the registered resources. 218 Sector 219 In the context of an RD, a sector is a logical grouping of 220 endpoints. 222 The abbreviation "d=" is used for the sector in query parameters 223 for compatibility with deployed implementations. 225 Endpoint 226 Endpoint (EP) is a term used to describe a web server or client in 227 [RFC7252]. In the context of this specification an endpoint is 228 used to describe a web server that registers resources to the RD. 229 An endpoint is identified by its endpoint name, which is included 230 during registration, and has a unique name within the associated 231 sector of the registration. 233 Registration Base URI 234 The Base URI of a Registration is a URI that typically gives 235 scheme and authority information about an Endpoint. The 236 Registration Base URI is provided at registration time, and is 237 used by the RD to resolve relative references of the registration 238 into URIs. 240 Target 241 The target of a link is the destination address (URI) of the link. 242 It is sometimes identified with "href=", or displayed as 243 "". Relative targets need resolving with respect to the 244 Base URI (section 5.2 of [RFC3986]). 246 This use of the term Target is consistent with [RFC8288]'s use of 247 the term. 249 Context 250 The context of a link is the source address (URI) of the link, and 251 describes which resource is linked to the target. A link's 252 context is made explicit in serialized links as the "anchor=" 253 attribute. 255 This use of the term Context is consistent with [RFC8288]'s use of 256 the term. 258 Directory Resource 259 A resource in the RD containing registration resources. 261 Registration Resource 262 A resource in the RD that contains information about an Endpoint 263 and its links. 265 Commissioning Tool 266 Commissioning Tool (CT) is a device that assists during 267 installation events by assigning values to parameters, naming 268 endpoints and groups, or adapting the installation to the needs of 269 the applications. 271 Registrant-ep 272 Registrant-ep is the endpoint that is registered into the RD. The 273 registrant-ep can register itself, or a CT registers the 274 registrant-ep. 276 RDAO 277 Resource Directory Address Option. A new IPv6 Neighbor Discovery 278 option defined for announcing an RD's address. 280 3. Architecture and Use Cases 282 3.1. Principles 284 The RD is primarily a tool to make discovery operations more 285 efficient than querying /.well-known/core on all connected devices, 286 or across boundaries that would limit those operations. 288 It provides information about resources hosted by other devices that 289 could otherwise only be obtained by directly querying the /.well- 290 known/core resource on these other devices, either by a unicast 291 request or a multicast request. 293 Information SHOULD only be stored in the RD if it can be obtained by 294 querying the described device's /.well-known/core resource directly. 296 Data in the RD can only be provided by the device which hosts those 297 data or a dedicated Commissioning Tool (CT). These CTs act on behalf 298 of endpoints too constrained, or generally unable, to present that 299 information themselves. No other client can modify data in the RD. 300 Changes to the information in the RD do not propagate automatically 301 back to the web servers from where the information originated. 303 3.2. Architecture 305 The RD architecture is illustrated in Figure 1. An RD is used as a 306 repository of registrations describing resources hosted on other web 307 servers, also called endpoints (EP). An endpoint is a web server 308 associated with a scheme, IP address and port. A physical node may 309 host one or more endpoints. The RD implements a set of REST 310 interfaces for endpoints to register and maintain RD registrations, 311 and for endpoints to lookup resources from the RD. An RD can be 312 logically segmented by the use of Sectors. 314 A mechanism to discover an RD using CoRE Link Format [RFC6690] is 315 defined. 317 Registrations in the RD are soft state and need to be periodically 318 refreshed. 320 An endpoint uses specific interfaces to register, update and remove a 321 registration. It is also possible for an RD to fetch Web Links from 322 endpoints and add their contents to its registrations. 324 At the first registration of an endpoint, a "registration resource" 325 is created, the location of which is returned to the registering 326 endpoint. The registering endpoint uses this registration resource 327 to manage the contents of registrations. 329 A lookup interface for discovering any of the Web Links stored in the 330 RD is provided using the CoRE Link Format. 332 Registration Lookup 333 Interface Interface 334 +----+ | | 335 | EP |---- | | 336 +----+ ---- | | 337 --|- +------+ | 338 +----+ | ----| | | +--------+ 339 | EP | ---------|-----| RD |----|-----| Client | 340 +----+ | ----| | | +--------+ 341 --|- +------+ | 342 +----+ ---- | | 343 | CT |---- | | 344 +----+ 346 Figure 1: The RD architecture. 348 A Registrant-EP MAY keep concurrent registrations to more than one RD 349 at the same time if explicitly configured to do so, but that is not 350 expected to be supported by typical EP implementations. Any such 351 registrations are independent of each other. The usual expectation 352 when multiple discovery mechanisms or addresses are configured is 353 that they constitute a fall-back path for a single registration. 355 3.3. RD Content Model 357 The Entity-Relationship (ER) models shown in Figure 2 and Figure 3 358 model the contents of /.well-known/core and the RD respectively, with 359 entity-relationship diagrams [ER]. Entities (rectangles) are used 360 for concepts that exist independently. Attributes (ovals) are used 361 for concepts that exist only in connection with a related entity. 362 Relations (diamonds) give a semantic meaning to the relation between 363 entities. Numbers specify 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 an RD. They cover the concepts, but not 372 necessarily all details of an RD's operation; they are meant to give 373 an overview, and not be a template for implementations. 375 +----------------------+ 376 | /.well-known/core | 377 +----------------------+ 378 | 379 | 1 380 ////////\\\\\\\ 381 < contains > 382 \\\\\\\\/////// 383 | 384 | 0+ 385 +--------------------+ 386 | link | 387 +--------------------+ 388 | 389 | 1 oooooooo 390 +-----o target o 391 | oooooooo 392 oooooooooooo 0+ | 393 o target o--------+ 394 o attribute o | 0+ oooooo 395 oooooooooooo +-----o rel o 396 | oooooo 397 | 398 | 1 ooooooooo 399 +-----o context o 400 ooooooooo 402 Figure 2: ER Model of the content of /.well-known/core 404 The model shown in Figure 2 models the contents of /.well-known/core 405 which contains: 407 * a set of links belonging to the hosting web server 409 The web server is free to choose links it deems appropriate to be 410 exposed in its "/.well-known/core". Typically, the links describe 411 resources that are served by the host, but the set can also contain 412 links to resources on other servers (see examples in [RFC6690] page 413 14). The set does not necessarily contain links to all resources 414 served by the host. 416 A link has the following attributes (see [RFC8288]): 418 * Zero or more link relations: They describe relations between the 419 link context and the link target. 421 In link-format serialization, they are expressed as space- 422 separated values in the "rel" attribute, and default to "hosts". 424 * A link context URI: It defines the source of the relation, e.g. 425 _who_ "hosts" something. 427 In link-format serialization, it is expressed in the "anchor" 428 attribute and defaults to the Origin of the target (practically: 429 the target with its path and later components removed) 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 + RD + 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: ER Model of the content of the RD 485 The model shown in Figure 3 models the contents of the RD which 486 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 cannot 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 cannot 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. The ambition in such 536 systems is to build them from reusable components. These speed up 537 development and deployment, and enable shared use of machines across 538 different applications. One crucial component of such systems is the 539 discovery of resources (and thus the endpoints they are hosted on) 540 capable of providing required information at a given time or acting 541 on instructions from the end users. 543 Imagine a scenario where endpoints installed on vehicles enable 544 tracking of the position of these vehicles for fleet management 545 purposes and allow monitoring of environment parameters. During the 546 boot-up process endpoints register with an RD, which is hosted by the 547 mobile operator or somewhere in the cloud. Periodically, these 548 endpoints update their registration and may modify resources they 549 offer. 551 When endpoints are not always connected, for example because they 552 enter a sleep mode, a remote server is usually used to provide proxy 553 access to the endpoints. Mobile apps or web applications for 554 environment monitoring contact the RD, look up the endpoints capable 555 of providing information about the environment using an appropriate 556 set of link parameters, obtain information on how to contact them 557 (URLs of the proxy server), and then initiate interaction to obtain 558 information that is finally processed, displayed on the screen and 559 usually stored in a database. Similarly, fleet management systems 560 provide the appropriate link parameters to the RD to look up for EPs 561 deployed on the vehicles the application is responsible for. 563 3.6. Use Case: Home and Building Automation 565 Home and commercial building automation systems can benefit from the 566 use of IoT web services. The discovery requirements of these 567 applications are demanding. Home automation usually relies on run- 568 time discovery to commission the system, whereas in building 569 automation a combination of professional commissioning and run-time 570 discovery is used. Both home and building automation involve peer- 571 to-peer interactions between endpoints, and involve battery-powered 572 sleeping devices. Both can use the common RD infrastructure to 573 establish device interactions efficiently, but can pick security 574 policies suitable for their needs. 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 (e.g. a 579 6LoWPAN Border Router (6LBR), see [RFC6775]) and the nodes connected 580 to the network can use the Internet services that are provided by the 581 Internet Provider or the network administrator. During the 582 installation phase, the network is completely stand-alone, no Border 583 Router is connected, and the network only supports the IP 584 communication between the connected nodes. The installation phase is 585 usually followed by the operational phase. As an RD's operations 586 work without hard dependencies on names or addresses, it can be used 587 for discovery across both phases. 589 3.7. Use Case: Link Catalogues 591 Resources may be shared through data brokers that have no knowledge 592 beforehand of who is going to consume the data. An RD can be used to 593 hold links about resources and services hosted anywhere to make them 594 discoverable by a general class of applications. 596 For example, environmental and weather sensors that generate data for 597 public consumption may provide data to an intermediary server, or 598 broker. Sensor data are published to the intermediary upon changes 599 or at regular intervals. Descriptions of the sensors that resolve to 600 links to sensor data may be published to an RD. Applications wishing 601 to consume the data can use RD Lookup to discover and resolve links 602 to the desired resources and endpoints. The RD service need not be 603 coupled with the data intermediary service. Mapping of RDs to data 604 intermediaries may be many-to-many. 606 Metadata in web link formats like [RFC6690] which may be internally 607 stored as triples, or relation/attribute pairs providing metadata 608 about resource links, need to be supported by RDs. External 609 catalogues that are represented in other formats may be converted to 610 common web linking formats for storage and access by RDs. Since it 611 is common practice for these to be encoded in URNs [RFC8141], simple 612 and lossless structural transforms should generally be sufficient to 613 store external metadata in RDs. 615 The additional features of an RD allow sectors to be defined to 616 enable access to a particular set of resources from particular 617 applications. This provides isolation and protection of sensitive 618 data when needed. Application groups with multicast addresses may be 619 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 an RD, endpoints and lookup clients. Although the 625 examples throughout these sections assume the use of CoAP [RFC7252], 626 these REST interfaces can also be realized using HTTP [RFC7230]. The 627 multicast discovery and simple registration operations are exceptions 628 to that, as they rely on mechanisms unavailable in HTTP. In all 629 definitions in these sections, both CoAP response codes (with dot 630 notation) and HTTP response codes (without dot notation) are shown. 631 An RD implementing this specification MUST support the discovery, 632 registration, update, lookup, and removal interfaces. 634 All operations on the contents of the RD MUST be atomic and 635 idempotent. 637 For several operations, interface templates are given in list form; 638 those describe the operation participants, request codes, URIs, 639 content formats and outcomes. Sections of those templates contain 640 normative content about Interaction, Method, URI Template and URI 641 Template Variables as well as the details of the Success condition. 642 The additional sections on options like Content-Format and on Failure 643 codes give typical cases that an implementation of the RD should deal 644 with. Those serve to illustrate the typical responses to readers who 645 are not yet familiar with all the details of CoAP based interfaces; 646 they do not limit what a server may respond under atypical 647 circumstances. 649 REST clients (registrant-EPs and CTs during registration and 650 maintenance, lookup clients, RD servers during simple registrations) 651 must be prepared to receive any unsuccessful code and act upon it 652 according to its definition, options and/or payload to the best of 653 their capabilities, falling back to failing the operation if recovery 654 is not possible. In particular, they SHOULD retry the request upon 655 5.03 (Service Unavailable; 503 in HTTP) according to the Max-Age 656 (Retry-After in HTTP) option, and SHOULD fall back to link-format 657 when receiving 4.15 (Unsupported Content-Format; 415 in HTTP). 659 An RD MAY make the information submitted to it available to further 660 directories (subject to security policies on link confidentiality), 661 if it can ensure that a loop does not form. The protocol used 662 between directories to ensure loop-free operation is outside the 663 scope of this document. 665 4.1. Finding a Resource Directory 667 A (re-)starting device may want to find one or more RDs before it can 668 discover their URIs. Dependent on the operational conditions, one or 669 more of the techniques below apply. 671 The device may be pre-configured to exercise specific mechanisms for 672 finding the RD: 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 an RD, the network may want to provide a suitable default. 695 1. The IPv6 Neighbor Discovery option RDAO Section 4.1.1 can do 696 that. 698 2. When DHCP is in use, this could be provided via a DHCP option (no 699 such option is defined at the time of writing). 701 Finally, if neither the device nor the network offers any specific 702 configuration, the device may want to employ heuristics to find a 703 suitable RD. 705 The present specification does not fully define these heuristics, but 706 suggests a number of candidates: 708 1. In a 6LoWPAN, just assume the Border Router (6LBR) can act as an 709 RD (using the ABRO option to find that [RFC6775]). Confirmation 710 can be obtained by sending a unicast to "coap://[6LBR]/.well- 711 known/core?rt=core.rd*". 713 2. In a network that supports multicast well, discovering the RD 714 using a multicast query for /.well-known/core as specified in 715 CoRE Link Format [RFC6690]: Sending a Multicast GET to 716 "coap://[MCD1]/.well-known/core?rt=core.rd*". RDs within the 717 multicast scope will answer the query. 719 When answering a multicast request directed at a link-local group, 720 the RD may want to respond from a routable address; this makes it 721 easier for registrants to use one of their own routable addresses for 722 registration. When [RFC6724] is used for source address selection, 723 this can be achieved by applying the changes of its Section 10.4, 724 picking public addresses in its Section 5 Rule 7, and superseding 725 rule 8 with preferring the source address's precedence. 727 As some of the RD addresses obtained by the methods listed here are 728 just (more or less educated) guesses, endpoints MUST make use of any 729 error messages to very strictly rate-limit requests to candidate IP 730 addresses that don't work out. For example, an ICMP Destination 731 Unreachable message (and, in particular, the port unreachable code 732 for this message) may indicate the lack of a CoAP server on the 733 candidate host, or a CoAP error response code such as 4.05 "Method 734 Not Allowed" may indicate unwillingness of a CoAP server to act as a 735 directory server. 737 The following RD discovery mechanisms are recommended: 739 * In managed networks with border routers that need stand-alone 740 operation, the RDAO option is recommended (e.g. operational phase 741 described in Section 3.6). 743 * In managed networks without border router (no Internet services 744 available), the use of a preconfigured anycast address is 745 recommended (e.g. installation phase described in Section 3.6). 747 * In networks managed using DNS-SD, the use of DNS-SD for discovery 748 as described in Section 4.1.2 is recommended. 750 The use of multicast discovery in mesh networks is NOT RECOMMENDED. 752 4.1.1. Resource Directory Address Option (RDAO) 754 The Resource Directory Address Option (RDAO) carries information 755 about the address of the RD in RAs (Router Advertisements) of IPv6 756 Neighbor Discovery (ND), similar to how RDNSS options [RFC8106] are 757 sent. This information is needed when endpoints cannot discover the 758 RD with a link-local or realm-local scope multicast address, for 759 instance because the endpoint and the RD are separated by a Border 760 Router (6LBR). In many circumstances the availability of DHCP cannot 761 be guaranteed either during commissioning of the network. The 762 presence and the use of the RD is essential during commissioning. 764 It is possible to send multiple RDAO options in one message, 765 indicating as many RD addresses. 767 The RDAO format is: 769 0 1 2 3 770 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 771 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 772 | Type | Length = 3 | Reserved | 773 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 774 | Valid Lifetime | 775 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 776 | | 777 + + 778 | | 779 + RD Address + 780 | | 781 + + 782 | | 783 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 785 Fields: 787 Type: TBD38 789 Length: 8-bit unsigned integer. The length of 790 the option in units of 8 bytes. 791 Always 3. 793 Reserved: This field is unused. It MUST be 794 initialized to zero by the sender and 795 MUST be ignored by the receiver. 797 Valid Lifetime: 32-bit unsigned integer. The length of 798 time in seconds (relative to 799 the time the packet is received) that 800 this RD address is valid. 801 A value of all zero bits (0x0) indicates 802 that this RD address 803 is not valid anymore. 805 RD Address: IPv6 address of the RD. 807 Figure 4: Resource Directory Address Option 809 4.1.2. Using DNS-SD to discover a Resource Directory 811 An RD can advertise its presence in DNS-SD [RFC6763] using the 812 service name "_core-rd._udp" (for CoAP), "_core-rd-dtls._udp" (for 813 CoAP over DTLS), "_core-rd._tcp" (for CoAP over TCP) or "_core-rd- 814 tls._tcp" (for CoAP over TLS) defined in this document. (For the 815 WebSocket transports of CoAP, no service is defined as DNS-SD is 816 typically unavailable in environments where CoAP over WebSockets is 817 used). 819 The selection of the service indicates the protocol used, and the SRV 820 record points the client to a host name and port to use as a starting 821 point for the URI discovery steps of Section 4.3. 823 This section is a simplified concrete application of the more generic 824 mechanism specified in [I-D.ietf-core-rd-dns-sd]. 826 4.2. Payload Content Formats 828 RDs implementing this specification MUST support the application/ 829 link-format content format (ct=40). 831 RDs implementing this specification MAY support additional content 832 formats. 834 Any additional content format supported by an RD implementing this 835 specification SHOULD be able to express all the information 836 expressible in link-format. It MAY be able to express information 837 that is inexpressible in link-format, but those expressions SHOULD be 838 avoided where possible. 840 4.3. URI Discovery 842 Before an endpoint can make use of an RD, it must first know the RD's 843 address and port, and the URI path information for its REST APIs. 844 This section defines discovery of the RD and its URIs using the well- 845 known interface of the CoRE Link Format [RFC6690] after having 846 discovered a host as described in Section 4.1. 848 Discovery of the RD registration URI is performed by sending either a 849 multicast or unicast GET request to "/.well-known/core" and including 850 a Resource Type (rt) parameter [RFC6690] with the value "core.rd" in 851 the query string. Likewise, a Resource Type parameter value of 852 "core.rd-lookup*" is used to discover the URIs for RD Lookup 853 operations, core.rd* is used to discover all URIs for RD operations. 854 Upon success, the response will contain a payload with a link format 855 entry for each RD function discovered, indicating the URI of the RD 856 function returned and the corresponding Resource Type. When 857 performing multicast discovery, the multicast IP address used will 858 depend on the scope required and the multicast capabilities of the 859 network (see Section 9.5). 861 An RD MAY provide hints about the content-formats it supports in the 862 links it exposes or registers, using the "ct" target attribute, as 863 shown in the example below. Clients MAY use these hints to select 864 alternate content-formats for interaction with the RD. 866 HTTP does not support multicast and consequently only unicast 867 discovery can be supported at the using the HTTP "/.well-known/core" 868 resource. 870 RDs implementing this specification MUST support query filtering for 871 the rt parameter as defined in [RFC6690]. 873 While the link targets in this discovery step are often expressed in 874 path-absolute form, this is not a requirement. Clients of the RD 875 SHOULD therefore accept URIs of all schemes they support, both as 876 URIs and relative references, and not limit the set of discovered 877 URIs to those hosted at the address used for URI discovery. 879 With security policies where the client requires the RD to be 880 authorized to act as an RD, that authorization may be limited to 881 resources on which the authorized RD advertises the adequate resource 882 types. Clients that have obtained links they can not rely on yet can 883 repeat the URI discovery step at the /.well-known/core resource of 884 the indicated host to obtain the resource type information from an 885 authorized source. 887 The URI Discovery operation can yield multiple URIs of a given 888 resource type. The client of the RD can use any of the discovered 889 addresses initially. 891 The discovery request interface is specified as follows (this is 892 exactly the Well-Known Interface of [RFC6690] Section 4, with the 893 additional requirement that the server MUST support query filtering): 895 Interaction: EP, CT or Client -> RD 897 Method: GET 899 URI Template: /.well-known/core{?rt} 901 URI Template Variables: rt := Resource Type. SHOULD contain one of 902 the values "core.rd", "core.rd-lookup*", "core.rd-lookup-res", 903 "core.rd-lookup-ep", or "core.rd*" 905 Accept: absent, application/link-format or any other media type 906 representing web links 908 The following response is expected on this interface: 910 Success: 2.05 "Content" or 200 "OK" with an application/link-format 911 or other web link payload containing one or more matching entries 912 for the RD resource. 914 The following example shows an endpoint discovering an RD using this 915 interface, thus learning that the directory resource location, in 916 this example, is /rd, and that the content-format delivered by the 917 server hosting the resource is application/link-format (ct=40). Note 918 that it is up to the RD to choose its RD locations. 920 Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* 922 Res: 2.05 Content 923 Payload: 924 ;rt=core.rd;ct=40, 925 ;rt=core.rd-lookup-ep;ct=40, 926 ;rt=core.rd-lookup-res;ct=40 928 Figure 5: Example discovery exchange 930 The following example shows the way of indicating that a client may 931 request alternate content-formats. The Content-Format code attribute 932 "ct" MAY include a space-separated sequence of Content-Format codes 933 as specified in Section 7.2.1 of [RFC7252], indicating that multiple 934 content-formats are available. The example below shows the required 935 Content-Format 40 (application/link-format) indicated as well as a 936 CBOR and JSON representation from [I-D.ietf-core-links-json] (which 937 have no numeric values assigned yet, so they are shown as TBD64 and 938 TBD504 as in that draft). The RD resource locations /rd, and /rd- 939 lookup are example values. The server in this example also indicates 940 that it is capable of providing observation on resource lookups. 942 Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* 944 Res: 2.05 Content 945 Payload: 946 ;rt=core.rd;ct="40 65225", 947 ;rt=core.rd-lookup-res;ct="40 TBD64 TBD504";obs, 948 ;rt=core.rd-lookup-ep;ct="40 TBD64 TBD504" 950 Figure 6: Example discovery exchange indicating additional 951 content-formats 953 For maintenance, management and debugging, it can be useful to 954 identify the components that constitute the RD server. The 955 identification can be used to find client-server incompatibilities, 956 supported features, required updates and other aspects. The Well- 957 Known interface described in Section 4 of [RFC6690] can be used to 958 find such data. 960 It would typically be stored in an implementation information link 961 (as described in [I-D.bormann-t2trg-rel-impl]): 963 Req: GET /.well-known/core?rel=impl-info 965 Res: 2.05 Content 966 Payload: 967 ; 968 rel=impl-info 970 Figure 7: Example exchange of obtaining implementation 971 information, using the relation type currently proposed in the 972 work-in-progress document 974 Note that depending on the particular server's architecture, such a 975 link could be anchored at the RD server's root (as in this example), 976 or at individual RD components. The latter is to be expected when 977 different applications are run on the same server. 979 5. Registration 981 After discovering the location of an RD, a registrant-ep or CT MAY 982 register the resources of the registrant-ep using the registration 983 interface. This interface accepts a POST from an endpoint containing 984 the list of resources to be added to the directory as the message 985 payload in the CoRE Link Format [RFC6690] or other representations of 986 web links, along with query parameters indicating the name of the 987 endpoint, and optionally the sector, lifetime and base URI of the 988 registration. It is expected that other specifications will define 989 further parameters (see Section 9.3). The RD then creates a new 990 registration resource in the RD and returns its location. The 991 receiving endpoint MUST use that location when refreshing 992 registrations using this interface. Registration resources in the RD 993 are kept active for the period indicated by the lifetime parameter. 994 The creating endpoint is responsible for refreshing the registration 995 resource within this period using either the registration or update 996 interface. The registration interface MUST be implemented to be 997 idempotent, so that registering twice with the same endpoint 998 parameters ep and d (sector) does not create multiple registration 999 resources. 1001 The following rules apply for a registration request targeting a 1002 given (ep, d) value pair: 1004 * When the (ep, d) value pair of the registration-request is 1005 different from any existing registration, a new registration is 1006 generated. 1008 * When the (ep, d) value pair of the registration-request is equal 1009 to an existing registration, the content and parameters of the 1010 existing registration are replaced with the content of the 1011 registration request. Like the later changes to registration 1012 resources, security policies (Section 7) usually require such 1013 requests to come from the same device. 1015 The posted link-format document can (and typically does) contain 1016 relative references both in its link targets and in its anchors, or 1017 contain empty anchors. The RD server needs to resolve these 1018 references in order to faithfully represent them in lookups. They 1019 are resolved against the base URI of the registration, which is 1020 provided either explicitly in the "base" parameter or constructed 1021 implicitly from the requester's URI as constructed from its network 1022 address and scheme. 1024 For media types to which Appendix C applies (i.e. documents in 1025 application/link-format), request bodies MUST be expressed in Limited 1026 Link Format. 1028 The registration request interface is specified as follows: 1030 Interaction: EP or CT -> RD 1032 Method: POST 1034 URI Template: {+rd}{?ep,d,lt,base,extra-attrs*} 1036 URI Template Variables: rd := RD registration URI (mandatory). 1037 This is the location of the RD, as obtained from discovery. 1039 ep := Endpoint name (mostly mandatory). 1040 The endpoint name is an identifier that MUST be unique within a 1041 sector. 1043 As the endpoint name is a Unicode string, it is encoded in 1044 UTF-8 (and possibly pct-encoded) during variable expansion (see 1045 [RFC6570] Section 3.2.1). The endpoint name MUST NOT contain 1046 any character in the inclusive ranges 0-31 or 127-159. 1048 The maximum length of this parameter is 63 UTF-8 encoded bytes. 1050 If the RD is configured to recognize the endpoint to be 1051 authorized to use exactly one endpoint name, the RD assigns 1052 that name. In that case, giving the endpoint name becomes 1053 optional for the client; if the client gives any other endpoint 1054 name, it is not authorized to perform the registration. 1056 d := Sector (optional). The sector to 1057 which this endpoint belongs. When this parameter is not 1058 present, the RD MAY associate the endpoint with a configured 1059 default sector (possibly based on the endpoint's authorization) 1060 or leave it empty. 1062 The sector is encoded like the ep parameter, and is limited to 1063 63 UTF-8 encoded bytes as well. 1065 lt := Lifetime (optional). Lifetime of the 1066 registration in seconds. Range of 1-4294967295. If no 1067 lifetime is included in the initial registration, a default 1068 value of 90000 (25 hours) SHOULD be assumed. 1070 base := Base URI (optional). This 1071 parameter sets the base URI of the registration, under which 1072 the relative links in the payload are to be interpreted. The 1073 specified URI typically does not have a path component of its 1074 own, and MUST be suitable as a base URI to resolve any relative 1075 references given in the registration. The parameter is 1076 therefore usually of the shape "scheme://authority" for HTTP 1077 and CoAP URIs. The URI SHOULD NOT have a query or fragment 1078 component as any non-empty relative part in a reference would 1079 remove those parts from the resulting URI. 1081 In the absence of this parameter the scheme of the protocol, 1082 source address and source port of the registration request are 1083 assumed. The Base URI is consecutively constructed by 1084 concatenating the used protocol's scheme with the characters 1085 "://", the requester's source address as an address literal and 1086 ":" followed by its port (if it was not the protocol's default 1087 one) in analogy to [RFC7252] Section 6.5. 1089 This parameter is mandatory when the directory is filled by a 1090 third party such as an commissioning tool. 1092 If the registrant-ep uses an ephemeral port to register with, 1093 it MUST include the base parameter in the registration to 1094 provide a valid network path. 1096 A registrant that cannot be reached by potential lookup clients 1097 at the address it registers from (e.g. because it is behind 1098 some form of Network Address Translation (NAT)) MUST provide a 1099 reachable base address with its registration. 1101 If the Base URI contains a link-local IP literal, it MUST NOT 1102 contain a Zone Identifier, and MUST be local to the link on 1103 which the registration request is received. 1105 Endpoints that register with a base that contains a path 1106 component cannot efficiently express their registrations in 1107 Limited Link Format (Appendix C). Those applications should 1108 use different representations of links to which Appendix C is 1109 not applicable (e.g. [I-D.hartke-t2trg-coral]). 1111 extra-attrs := Additional registration 1112 attributes (optional). The endpoint can pass any parameter 1113 registered at Section 9.3 to the directory. If the RD is aware 1114 of the parameter's specified semantics, it processes it 1115 accordingly. Otherwise, it MUST store the unknown key and its 1116 value(s) as an endpoint attribute for further lookup. 1118 Content-Format: application/link-format or any other indicated media 1119 type representing web links 1121 The following response is expected on this interface: 1123 Success: 2.01 "Created" or 201 "Created". The Location-Path option 1124 or Location header field MUST be included in the response. This 1125 location MUST be a stable identifier generated by the RD as it is 1126 used for all subsequent operations on this registration resource. 1127 The registration resource location thus returned is for the 1128 purpose of updating the lifetime of the registration and for 1129 maintaining the content of the registered links, including 1130 updating and deleting links. 1132 A registration with an already registered ep and d value pair 1133 responds with the same success code and location as the original 1134 registration; the set of links registered with the endpoint is 1135 replaced with the links from the payload. 1137 The location MUST NOT have a query or fragment component, as that 1138 could conflict with query parameters during the Registration 1139 Update operation. Therefore, the Location-Query option MUST NOT 1140 be present in a successful response. 1142 If the registration fails, including request timeouts, or if delays 1143 from Service Unavailable responses with Max-Age or Retry-After 1144 accumulate to exceed the registrant's configured timeouts, it SHOULD 1145 pick another registration URI from the "URI Discovery" step and if 1146 there is only one or the list is exhausted, pick other choices from 1147 the "Finding a Resource Directory" step. Care has to be taken to 1148 consider the freshness of results obtained earlier, e.g. of the 1149 result of a "/.well-known/core" response, the lifetime of an RDAO 1150 option and of DNS responses. Any rate limits and persistent errors 1151 from the "Finding a Resource Directory" step must be considered for 1152 the whole registration time, not only for a single operation. 1154 The following example shows a registrant-ep with the name "node1" 1155 registering two resources to an RD using this interface. The 1156 location "/rd" is an example RD location discovered in a request 1157 similar to Figure 5. 1159 Req: POST coap://rd.example.com/rd?ep=node1 1160 Content-Format: 40 1161 Payload: 1162 ;rt=temperature-c;if=sensor, 1163 ; 1164 anchor="/sensors/temp";rel=describedby 1166 Res: 2.01 Created 1167 Location-Path: /rd/4521 1169 Figure 8: Example registration payload 1171 An RD may optionally support HTTP. Here is an example of almost the 1172 same registration operation above, when done using HTTP. 1174 Req: 1175 POST /rd?ep=node1&base=http://[2001:db8:1::1] HTTP/1.1 1176 Host: rd.example.com 1177 Content-Type: application/link-format 1179 ;rt=temperature-c;if=sensor, 1180 ; 1181 anchor="/sensors/temp";rel=describedby 1183 Res: 1184 HTTP/1.1 201 Created 1185 Location: /rd/4521 1187 Figure 9: Example registration payload as expressed using HTTP 1189 5.1. Simple Registration 1191 Not all endpoints hosting resources are expected to know how to 1192 upload links to an RD as described in Section 5. Instead, simple 1193 endpoints can implement the Simple Registration approach described in 1194 this section. An RD implementing this specification MUST implement 1195 Simple Registration. However, there may be security reasons why this 1196 form of directory discovery would be disabled. 1198 This approach requires that the registrant-ep makes available the 1199 hosted resources that it wants to be discovered, as links on its 1200 "/.well-known/core" interface as specified in [RFC6690]. The links 1201 in that document are subject to the same limitations as the payload 1202 of a registration (with respect to Appendix C). 1204 * The registrant-ep finds one or more addresses of the directory 1205 server as described in Section 4.1. 1207 * The registrant-ep sends (and regularly refreshes with) a POST 1208 request to the "/.well-known/rd" URI of the directory server of 1209 choice. The body of the POST request is empty, and triggers the 1210 resource directory server to perform GET requests at the 1211 requesting registrant-ep's /.well-known/core to obtain the link- 1212 format payload to register. 1214 The registrant-ep includes the same registration parameters in the 1215 POST request as it would with a regular registration per 1216 Section 5. The registration base URI of the registration is taken 1217 from the registrant-ep's network address (as is default with 1218 regular registrations). 1220 Example request from registrant-EP to RD (unanswered until the 1221 next step): 1223 Req: POST /.well-known/rd?lt=6000&ep=node1 1224 (No payload) 1226 Figure 10: First half example exchange of a simple registration 1228 * The RD queries the registrant-ep's discovery resource to determine 1229 the success of the operation. It SHOULD keep a cache of the 1230 discovery resource and not query it again as long as it is fresh. 1232 Example request from the RD to the registrant-EP: 1234 Req: GET /.well-known/core 1235 Accept: 40 1237 Res: 2.05 Content 1238 Content-Format: 40 1239 Payload: 1240 1242 Figure 11: Example exchange of the RD querying the simple endpoint 1244 With this response, the RD would answer the previous step's request: 1246 Res: 2.04 Changed 1248 Figure 12: Second half example exchange of a simple registration 1250 The sequence of fetching the registration content before sending a 1251 successful response was chosen to make responses reliable, and the 1252 point about caching was chosen to still allow very constrained 1253 registrants. Registrants MUST be able to serve a GET request to 1254 "/.well-known/core" after having requested registration. Constrained 1255 devices MAY regard the initial request as temporarily failed when 1256 they need RAM occupied by their own request to serve the RD's GET, 1257 and retry later when the RD already has a cached representation of 1258 their discovery resources. Then, the RD can reply immediately and 1259 the registrant can receive the response. 1261 The simple registration request interface is specified as follows: 1263 Interaction: EP -> RD 1265 Method: POST 1267 URI Template: /.well-known/rd{?ep,d,lt,extra-attrs*} 1269 URI Template Variables are as they are for registration in Section 5. 1270 The base attribute is not accepted to keep the registration interface 1271 simple; that rules out registration over CoAP-over-TCP or HTTP that 1272 would need to specify one. For some time during this document's 1273 development, the URI template "/.well-known/core{?ep,...}" has been 1274 in use instead. 1276 The following response is expected on this interface: 1278 Success: 2.04 "Changed". 1280 For the second interaction triggered by the above, the registrant-ep 1281 takes the role of server and the RD the role of client. (Note that 1282 this is exactly the Well-Known Interface of [RFC6690] Section 4): 1284 Interaction: RD -> EP 1286 Method: GET 1288 URI Template: /.well-known/core 1290 The following response is expected on this interface: 1292 Success: 2.05 "Content". 1294 When the RD uses any authorization credentials to access the 1295 endpoint's discovery resource, or when it is deployed in a location 1296 where third parties might reach it but not the endpoint, it SHOULD 1297 verify that the apparent registrant-ep intends to register with the 1298 given registration parameters before revealing the obtained discovery 1299 information to lookup clients. An easy way to do that is to verify 1300 the simple registration request's sender address using the Echo 1301 option as described in [I-D.ietf-core-echo-request-tag] Section 2.4. 1303 The RD MUST delete registrations created by simple registration after 1304 the expiration of their lifetime. Additional operations on the 1305 registration resource cannot be executed because no registration 1306 location is returned. 1308 5.2. Third-party registration 1310 For some applications, even Simple Registration may be too taxing for 1311 some very constrained devices, in particular if the security 1312 requirements become too onerous. 1314 In a controlled environment (e.g. building control), the RD can be 1315 filled by a third party device, called a Commissioning Tool (CT). 1316 The commissioning tool can fill the RD from a database or other 1317 means. For that purpose scheme, IP address and port of the URI of 1318 the registered device is the value of the "base" parameter of the 1319 registration described in Section 5. 1321 It should be noted that the value of the "base" parameter applies to 1322 all the links of the registration and has consequences for the anchor 1323 value of the individual links as exemplified in Appendix B. An 1324 eventual (currently non-existing) "base" attribute of the link is not 1325 affected by the value of "base" parameter in the registration. 1327 5.3. Operations on the Registration Resource 1329 This section describes how the registering endpoint can maintain the 1330 registrations that it created. The registering endpoint can be the 1331 registrant-ep or the CT. The registrations are resources of the RD. 1333 An endpoint should not use this interface for registrations that it 1334 did not create. This is usually enforced by security policies, which 1335 in general require equivalent credentials for creation of and 1336 operations on a registration. 1338 After the initial registration, the registering endpoint retains the 1339 returned location of the registration resource for further 1340 operations, including refreshing the registration in order to extend 1341 the lifetime and "keep-alive" the registration. When the lifetime of 1342 the registration has expired, the RD SHOULD NOT respond to discovery 1343 queries concerning this endpoint. The RD SHOULD continue to provide 1344 access to the registration resource after a registration time-out 1345 occurs in order to enable the registering endpoint to eventually 1346 refresh the registration. The RD MAY eventually remove the 1347 registration resource for the purpose of garbage collection. If the 1348 registration resource is removed, the corresponding endpoint will 1349 need to be re-registered. 1351 The registration resource may also be used cancel the registration 1352 using DELETE, and to perform further operations beyond the scope of 1353 this specification. 1355 Operations on the registration resource are sensitive to reordering; 1356 Section 5.3.4 describes how order is restored. 1358 The operations on the registration resource are described below. 1360 5.3.1. Registration Update 1362 The update interface is used by the registering endpoint to refresh 1363 or update its registration with an RD. To use the interface, the 1364 registering endpoint sends a POST request to the registration 1365 resource returned by the initial registration operation. 1367 An update MAY update registration parameters like lifetime, base URI 1368 or others. Parameters that are not being changed should not be 1369 included in an update. Adding parameters that have not changed 1370 increases the size of the message but does not have any other 1371 implications. Parameters are included as query parameters in an 1372 update operation as in Section 5. 1374 A registration update resets the timeout of the registration to the 1375 (possibly updated) lifetime of the registration, independent of 1376 whether a "lt" parameter was given. 1378 If the base URI of the registration is changed in an update, relative 1379 references submitted in the original registration or later updates 1380 are resolved anew against the new base. 1382 The registration update operation only describes the use of POST with 1383 an empty payload. Future standards might describe the semantics of 1384 using content formats and payloads with the POST method to update the 1385 links of a registration (see Section 5.3.3). 1387 The update registration request interface is specified as follows: 1389 Interaction: EP or CT -> RD 1391 Method: POST 1393 URI Template: {+location}{?lt,base,extra-attrs*} 1395 URI Template Variables: location := This is the Location returned 1396 by the RD as a result of a successful earlier registration. 1398 lt := Lifetime (optional). Lifetime of the 1399 registration in seconds. Range of 1-4294967295. If no 1400 lifetime is included, the previous last lifetime set on a 1401 previous update or the original registration (falling back to 1402 90000) SHOULD be used. 1404 base := Base URI (optional). This 1405 parameter updates the Base URI established in the original 1406 registration to a new value, and is subject to the same 1407 restrictions as in the registration. 1409 If the parameter is set in an update, it is stored by the RD as 1410 the new Base URI under which to interpret the relative links 1411 present in the payload of the original registration. 1413 If the parameter is not set in the request but was set before, 1414 the previous Base URI value is kept unmodified. 1416 If the parameter is not set in the request and was not set 1417 before either, the source address and source port of the update 1418 request are stored as the Base URI. 1420 extra-attrs := Additional registration 1422 attributes (optional). As with the registration, the RD 1423 processes them if it knows their semantics. Otherwise, unknown 1424 attributes are stored as endpoint attributes, overriding any 1425 previously stored endpoint attributes of the same key. 1427 Note that this default behavior does not allow removing an 1428 endpoint attribute in an update. For attributes whose 1429 functionality depends on the endpoints' ability to remove them 1430 in an update, it can make sense to define a value whose 1431 presence is equivalent to the absence of a value. As an 1432 alternative, an extension can define different updating rules 1433 for their attributes. That necessitates either discovery of 1434 whether the RD is aware of that extension, or tolerating the 1435 default behavior. 1437 Content-Format: none (no payload) 1439 The following responses are expected on this interface: 1441 Success: 2.04 "Changed" or 204 "No Content" if the update was 1442 successfully processed. 1444 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1445 exist (e.g. may have been removed). 1447 If the registration update fails in any way, including "Not Found" 1448 and request timeouts, or if the time indicated in a Service 1449 Unavailable Max-Age/Retry-After exceeds the remaining lifetime, the 1450 registering endpoint SHOULD attempt registration again. 1452 The following example shows how the registering endpoint resets the 1453 timeout on its registration resource at an RD using this interface 1454 with the example location value: /rd/4521. 1456 Req: POST /rd/4521 1458 Res: 2.04 Changed 1460 Figure 13: Example update of a registration 1462 The following example shows the registering endpoint updating its 1463 registration resource at an RD using this interface with the example 1464 location value: /rd/4521. The initial registration by the 1465 registering endpoint set the following values: 1467 * endpoint name (ep)=endpoint1 1469 * lifetime (lt)=500 1470 * Base URI (base)=coap://local-proxy-old.example.com 1472 * payload of Figure 8 1474 The initial state of the RD is reflected in the following request: 1476 Req: GET /rd-lookup/res?ep=endpoint1 1478 Res: 2.05 Content 1479 Payload: 1480 ; 1481 rt=temperature-c;if=sensor, 1482 ; 1483 anchor="coap://local-proxy-old.example.com/sensors/temp"; 1484 rel=describedby 1486 Figure 14: Example lookup before a change to the base address 1488 The following example shows the registering endpoint changing the 1489 Base URI to "coaps://new.example.com:5684": 1491 Req: POST /rd/4521?base=coaps://new.example.com 1493 Res: 2.04 Changed 1495 Figure 15: Example registration update that changes the base address 1497 The consecutive query returns: 1499 Req: GET /rd-lookup/res?ep=endpoint1 1501 Res: 2.05 Content 1502 Payload: 1503 ; 1504 rt=temperature-c;if=sensor, 1505 ; 1506 anchor="coaps://new.example.com/sensors/temp"; 1507 rel=describedby 1509 Figure 16: Example lookup after a change to the base address 1511 5.3.2. Registration Removal 1513 Although RD registrations have soft state and will eventually timeout 1514 after their lifetime, the registering endpoint SHOULD explicitly 1515 remove an entry from the RD if it knows it will no longer be 1516 available (for example on shut-down). This is accomplished using a 1517 removal interface on the RD by performing a DELETE on the endpoint 1518 resource. 1520 The removal request interface is specified as follows: 1522 Interaction: EP or CT -> RD 1524 Method: DELETE 1526 URI Template: {+location} 1528 URI Template Variables: location := This is the Location returned 1529 by the RD as a result of a successful earlier registration. 1531 The following responses are expected on this interface: 1533 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1535 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1536 exist (e.g. may already have been removed). 1538 The following examples shows successful removal of the endpoint from 1539 the RD with example location value /rd/4521. 1541 Req: DELETE /rd/4521 1543 Res: 2.02 Deleted 1545 Figure 17: Example of a registration removal 1547 5.3.3. Further operations 1549 Additional operations on the registration can be specified in future 1550 documents, for example: 1552 * Send iPATCH (or PATCH) updates ([RFC8132]) to add, remove or 1553 change the links of a registration. 1555 * Use GET to read the currently stored set of links in a 1556 registration resource. 1558 Those operations are out of scope of this document, and will require 1559 media types suitable for modifying sets of links. 1561 5.3.4. Request freshness 1563 Some security mechanisms usable with an RD allow out of order request 1564 processing, or do not even mandate replay protection at all. The RD 1565 needs to ensure that operations on the registration resource are 1566 executed in an order that does not distort the client's intentions. 1568 This ordering of operations is expressed in terms of freshness as 1569 defined in [I-D.ietf-core-echo-request-tag]. Requests that alter a 1570 resource's state need to be fresh relative to the latest request that 1571 altered that state in a conflicting way. 1573 An RD SHOULD determine a request's freshness, and MUST use the Echo 1574 option if it requires request freshness and can not determine the it 1575 in any other way. An endpoint MUST support the use of the Echo 1576 option. (One reason why an RD would not require freshness is when no 1577 relevant registration properties are covered by is security 1578 policies.) 1580 5.3.4.1. Efficient use of Echo by an RD 1582 To keep latency and traffic added by the freshness requirements to a 1583 minimum, RDs should avoid naive (sufficient but inefficient) 1584 freshness criteria. 1586 Some simple mechanisms the RD can employ are: 1588 * State counter. The RD can keep a monotonous counter that 1589 increments whenever a registration changes. For every 1590 registration resource, it stores the post-increment value of that 1591 resource's last change. Requests altering them need to have at 1592 least that value encoded in their Echo option, and are otherwise 1593 rejected with a 4.01 Unauthorized and the current counter value as 1594 the Echo value. If other applications on the same server use Echo 1595 as well, that encoding may include a prefix indicating that it 1596 pertains to the RD's counter. 1598 The value associated with a resource needs to be kept across the 1599 removal of registrations if the same registration resource is to 1600 be reused. 1602 The counter can be reset (and the values of removed resources 1603 forgotten) when all previous security associations are reset. 1605 This is the "Persistent Counter" method of 1606 [I-D.ietf-core-echo-request-tag] Appendix A. 1608 * Preemptive Echo values. The current state counter can be sent in 1609 an Echo option not only when requests are rejected with 4.01 1610 Unauthorized, but also with successful responses. Thus, clients 1611 can be provided with Echo values sufficient for their next request 1612 on a regular basis. 1614 While endpoints may discard received Echo values at leisure 1615 between requests, they are encouraged to retain these values for 1616 the next request to avoid additional round trips. 1618 * If the RD can ensure that only one security association has 1619 modifying access to any registration at any given time, and that 1620 security association provides order on the requests, that order is 1621 sufficient to show request freshness. 1623 5.3.4.2. Examples of Echo usage 1625 Figure 18 shows the interactions of an endpoint that has forgotten 1626 the server's latest Echo value and temporarily reduces its 1627 registration lifetime: 1629 Req: POST /rd/4521?lt=7200 1631 Res: 4.01 Unauthorized 1632 Echo: 0x0123 1634 (EP tries again immediately) 1636 Req: POST /rd/4521?lt=7200 1637 Echo: 0x0123 1639 Res: 2.04 Changed 1640 Echo: 0x0124 1642 (Later the EP regains its confidence in its long-term reachability) 1644 Req: POST /rd/4521?lt=90000 1645 Echo: 0x0124 1647 Res: 2.04 Changed 1648 Echo: 0x0247 1650 Figure 18: Example update of a registration 1652 The other examples do not show Echo options for simplicity, and 1653 because they lack the context for any example values to have meaning. 1655 6. RD Lookup 1657 To discover the resources registered with the RD, a lookup interface 1658 must be provided. This lookup interface is defined as a default, and 1659 it is assumed that RDs may also support lookups to return resource 1660 descriptions in alternative formats (e.g. JSON or CBOR link format 1661 [I-D.ietf-core-links-json]) or using more advanced interfaces (e.g. 1662 supporting context or semantic based lookup) on different resources 1663 that are discovered independently. 1665 RD Lookup allows lookups for endpoints and resources using attributes 1666 defined in this document and for use with the CoRE Link Format. The 1667 result of a lookup request is the list of links (if any) 1668 corresponding to the type of lookup. Thus, an endpoint lookup MUST 1669 return a list of endpoints and a resource lookup MUST return a list 1670 of links to resources. 1672 The lookup type is selected by a URI endpoint, which is indicated by 1673 a Resource Type as per Table 1 below: 1675 +=============+====================+===========+ 1676 | Lookup Type | Resource Type | Mandatory | 1677 +=============+====================+===========+ 1678 | Resource | core.rd-lookup-res | Mandatory | 1679 +-------------+--------------------+-----------+ 1680 | Endpoint | core.rd-lookup-ep | Mandatory | 1681 +-------------+--------------------+-----------+ 1683 Table 1: Lookup Types 1685 6.1. Resource lookup 1687 Resource lookup results in links that are semantically equivalent to 1688 the links submitted to the RD by the registrant. The links and link 1689 parameters returned by the lookup are equal to the originally 1690 submitted ones, except that the target reference is fully resolved, 1691 and that the anchor reference is fully resolved if it is present in 1692 the lookup result at all. 1694 Links that did not have an anchor attribute in the registration are 1695 returned without an anchor attribute. Links of which href or anchor 1696 was submitted as a (full) URI are returned with the respective 1697 attribute unmodified. 1699 The above rules allow the client to interpret the response as links 1700 without any further knowledge of the storage conventions of the RD. 1701 The RD MAY replace the registration base URIs with a configured 1702 intermediate proxy, e.g. in the case of an HTTP lookup interface for 1703 CoAP endpoints. 1705 If the base URI of a registration contains a link-local address, the 1706 RD MUST NOT show its links unless the lookup was made from the link 1707 on which the registered endpoint can be reached. The RD MUST NOT 1708 include zone identifiers in the resolved URIs. 1710 6.2. Lookup filtering 1712 Using the Accept Option, the requester can control whether the 1713 returned list is returned in CoRE Link Format ("application/link- 1714 format", default) or in alternate content-formats (e.g. from 1715 [I-D.ietf-core-links-json]). 1717 Multiple search criteria MAY be included in a lookup. All included 1718 criteria MUST match for a link to be returned. The RD MUST support 1719 matching with multiple search criteria. 1721 A link matches a search criterion if it has an attribute of the same 1722 name and the same value, allowing for a trailing "*" wildcard 1723 operator as in Section 4.1 of [RFC6690]. Attributes that are defined 1724 as "relation-types" (in the link-format ABNF) match if the search 1725 value matches any of their values (see Section 4.1 of [RFC6690]; e.g. 1726 "?if=tag:example.net,2020:sensor" matches ";if="example.regname 1727 tag:example.net,2020:sensor";"). A resource link also matches a 1728 search criterion if its endpoint would match the criterion, and vice 1729 versa, an endpoint link matches a search criterion if any of its 1730 resource links matches it. 1732 Note that "href" is a valid search criterion and matches target 1733 references. Like all search criteria, on a resource lookup it can 1734 match the target reference of the resource link itself, but also the 1735 registration resource of the endpoint that registered it. Queries 1736 for resource link targets MUST be in URI form (i.e. not relative 1737 references) and are matched against a resolved link target. Queries 1738 for endpoints SHOULD be expressed in path-absolute form if possible 1739 and MUST be expressed in URI form otherwise; the RD SHOULD recognize 1740 either. The "anchor" attribute is usable for resource lookups, and, 1741 if queried, MUST be in URI form as well. 1743 Additional query parameters "page" and "count" are used to obtain 1744 lookup results in specified increments using pagination, where count 1745 specifies how many links to return and page specifies which subset of 1746 links organized in sequential pages, each containing 'count' links, 1747 starting with link zero and page zero. Thus, specifying count of 10 1748 and page of 0 will return the first 10 links in the result set (links 1749 0-9). Count = 10 and page = 1 will return the next 'page' containing 1750 links 10-19, and so on. Unlike block-wise transfer of a compelte 1751 result set, these parameters ensure that each chunk of results can be 1752 interpreted on its own. This simplifies the processing, but can 1753 result in duplicate or missed items when coinciding with changes from 1754 the registration interface. 1756 Endpoints that are interested in a lookup result repeatedly or 1757 continuously can use mechanisms like ETag caching, resource 1758 observation ([RFC7641]), or any future mechanism that might allow 1759 more efficient observations of collections. These are advertised, 1760 detected and used according to their own specifications and can be 1761 used with the lookup interface as with any other resource. 1763 When resource observation is used, every time the set of matching 1764 links changes, or the content of a matching link changes, the RD 1765 sends a notification with the matching link set. The notification 1766 contains the successful current response to the given request, 1767 especially with respect to representing zero matching links (see 1768 "Success" item below). 1770 The lookup interface is specified as follows: 1772 Interaction: Client -> RD 1774 Method: GET 1776 URI Template: {+type-lookup-location}{?page,count,search*} 1778 URI Template Variables: type-lookup-location := RD Lookup URI for a 1779 given lookup type (mandatory). The address is discovered as 1780 described in Section 4.3. 1782 search := Search criteria for limiting the 1783 number of results (optional). 1785 The search criteria are an associative array, expressed in a 1786 form-style query as per the URI template (see [RFC6570] 1787 Sections 2.4.2 and 3.2.8) 1789 page := Page (optional). Parameter cannot 1790 be used without the count parameter. Results are returned from 1791 result set in pages that contain 'count' links starting from 1792 index (page * count). Page numbering starts with zero. 1794 count := Count (optional). Number of 1796 results is limited to this parameter value. If the page 1797 parameter is also present, the response MUST only include 1798 'count' links starting with the (page * count) link in the 1799 result set from the query. If the count parameter is not 1800 present, then the response MUST return all matching links in 1801 the result set. Link numbering starts with zero. 1803 Accept: absent, application/link-format or any other indicated media 1804 type representing web links 1806 The following responses codes are defined for this interface: 1808 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1809 format" or other web link payload containing matching entries for 1810 the lookup. 1812 The payload can contain zero links (which is an empty payload in 1813 [RFC6690] link format, but could also be "[]" in JSON based 1814 formats), indicating that no entities matched the request. 1816 6.3. Resource lookup examples 1818 The examples in this section assume the existence of CoAP hosts with 1819 a default CoAP port 61616. HTTP hosts are possible and do not change 1820 the nature of the examples. 1822 The following example shows a client performing a resource lookup 1823 with the example resource look-up locations discovered in Figure 5: 1825 Req: GET /rd-lookup/res?rt=tag:example.org,2020:temperature 1827 Res: 2.05 Content 1828 Payload: 1829 ; 1830 rt="tag:example.org,2020:temperature" 1832 Figure 19: Example a resource lookup 1834 A client that wants to be notified of new resources as they show up 1835 can use observation: 1837 Req: GET /rd-lookup/res?rt=tag:example.org,2020:light 1838 Observe: 0 1840 Res: 2.05 Content 1841 Observe: 23 1842 Payload: empty 1844 (at a later point in time) 1846 Res: 2.05 Content 1847 Observe: 24 1848 Payload: 1849 ;rt="tag:example.org,2020:light", 1850 ;rt="tag:example.org,2020:light", 1851 ;rt="tag:example.org,2020:light" 1853 Figure 20: Example an observing resource lookup 1855 The following example shows a client performing a paginated resource 1856 lookup 1858 Req: GET /rd-lookup/res?page=0&count=5 1860 Res: 2.05 Content 1861 Payload: 1862 ;ct=60, 1863 ;ct=60, 1864 ;ct=60, 1865 ;ct=60, 1866 ;ct=60 1868 Req: GET /rd-lookup/res?page=1&count=5 1870 Res: 2.05 Content 1871 Payload: 1872 ;ct=60, 1873 ;ct=60, 1874 ;ct=60, 1875 ;ct=60, 1876 ;ct=60 1878 Figure 21: Examples of paginated resource lookup 1880 The following example shows a client performing a lookup of all 1881 resources of all endpoints of a given endpoint type. It assumes that 1882 two endpoints (with endpoint names "sensor1" and "sensor2") have 1883 previously registered with their respective addresses 1884 "coap://sensor1.example.com" and "coap://sensor2.example.com", and 1885 posted the very payload of the 6th response of section 5 of 1886 [RFC6690]. 1888 It demonstrates how absolute link targets stay unmodified, while 1889 relative ones are resolved: 1891 Req: GET /rd-lookup/res?et=tag:example.com,2020:platform 1893 Res: 2.05 Content 1894 Payload: 1895 ;ct=40;title="Sensor Index", 1896 ;rt=temperature-c;if=sensor, 1897 ;rt=light-lux;if=sensor, 1898 ;rel=describedby; 1899 anchor="coap://sensor1.example.com/sensors/temp", 1900 ;rel=alternate; 1901 anchor="coap://sensor1.example.com/sensors/temp", 1902 ;ct=40;title="Sensor Index", 1903 ;rt=temperature-c;if=sensor, 1904 ;rt=light-lux;if=sensor, 1905 ;rel=describedby; 1906 anchor="coap://sensor2.example.com/sensors/temp", 1907 ;rel=alternate; 1908 anchor="coap://sensor2.example.com/sensors/temp" 1910 Figure 22: Example of resource lookup from multiple endpoints 1912 6.4. Endpoint lookup 1914 The endpoint lookup returns links to and information about 1915 registration resources, which themselves can only be manipulated by 1916 the registering endpoint. 1918 Endpoint registration resources are annotated with their endpoint 1919 names (ep), sectors (d, if present) and registration base URI (base; 1920 reports the registrant-ep's address if no explicit base was given) as 1921 well as a constant resource type (rt="core.rd-ep"); the lifetime (lt) 1922 is not reported. Additional endpoint attributes are added as target 1923 attributes to their endpoint link unless their specification says 1924 otherwise. 1926 Links to endpoints SHOULD be presented in path-absolute form or, if 1927 required, as (full) URIs. (This ensures that the output conforms to 1928 Limited Link Format as described in Appendix C.) 1930 Base addresses that contain link-local addresses MUST NOT include 1931 zone identifiers, and such registrations MUST NOT be shown unless the 1932 lookup was made from the same link from which the registration was 1933 made. 1935 While Endpoint Lookup does expose the registration resources, the RD 1936 does not need to make them accessible to clients. Clients SHOULD NOT 1937 attempt to dereference or manipulate them. 1939 An RD can report registrations in lookup whose URI scheme and 1940 authority differ from the lookup resource's. Lookup clients MUST be 1941 prepared to see arbitrary URIs as registration resources in the 1942 results and treat them as opaque identifiers; the precise semantics 1943 of such links are left to future specifications. 1945 The following example shows a client performing an endpoint lookup 1946 limited to endpoints of endpoint type 1947 "tag:example.com,2020:platform": 1949 Req: GET /rd-lookup/ep?et=tag:example.com,2020:platform 1951 Res: 2.05 Content 1952 Payload: 1953 ;base="coap://[2001:db8:3::127]:61616";ep=node5; 1954 et="tag:example.com,2020:platform";ct=40;rt=core.rd-ep, 1955 ;base="coap://[2001:db8:3::129]:61616";ep=node7; 1956 et="tag:example.com,2020:platform";ct=40;d=floor-3; 1957 rt=core.rd-ep 1959 Figure 23: Examples of endpoint lookup 1961 7. Security policies 1963 The security policies that are applicable to an RD strongly depend on 1964 the application, and are not set out normatively here. 1966 This section provides a list of aspects that applications should 1967 consider when describing their use of the RD, without claiming to 1968 cover all cases. It is using terminology of 1969 [I-D.ietf-ace-oauth-authz], in which the RD acts as the Resource 1970 Server (RS), and both registrant-eps and lookup clients act as 1971 Clients (C) with support from an Authorization Server (AS), without 1972 the intention of ruling out other (e.g. certificate / public-key 1973 infrastructure (PKI) based) schemes. 1975 Any, all or none of the below can apply to an application. Which are 1976 relevant depends on its protection objectives. 1978 Security policies are set by configuration of the RD, or by choice of 1979 the implementation. Lookup clients (and, where relevant, endpoints) 1980 can only trust an RD to uphold them if it is authenticated, and 1981 authorized to serve as an RD according to the application's 1982 requirements. 1984 7.1. Endpoint name 1986 Whenever an RD needs to provide trustworthy results to clients doing 1987 endpoint lookup, or resource lookup with filtering on the endpoint 1988 name, the RD must ensure that the registrant is authorized to use the 1989 given endpoint name. This applies both to registration and later to 1990 operations on the registration resource. It is immaterial whether 1991 the client is the registrant-ep itself or a CT is doing the 1992 registration: The RD cannot tell the difference, and CTs may use 1993 authorization credentials authorizing only operations on that 1994 particular endpoint name, or a wider range of endpoint names. 1996 It is up to the concrete security policy to describe how endpoint 1997 name and sector are transported when certificates are used. For 1998 example, it may describe how SubjectAltName dNSName entries are 1999 mapped to endpoint and domain names. 2001 7.1.1. Random endpoint names 2003 Conversely, in applications where the RD does not check the endpoint 2004 name, the authorized registering endpoint can generate a random 2005 number (or string) that identifies the endpoint. The RD should then 2006 remember unique properties of the registrant, associate them with the 2007 registration for as long as its registration resource is active 2008 (which may be longer than the registration's lifetime), and require 2009 the same properties for operations on the registration resource. 2011 Registrants that are prepared to pick a different identifier when 2012 their initial attempt (or attempts, in the unlikely case of two 2013 subsequent collisions) at registration is unauthorized should pick an 2014 identifier at least twice as long as the expected number of 2015 registrants; registrants without such a recovery options should pick 2016 significantly longer endpoint names (e.g. using UUID URNs [RFC4122]). 2018 7.2. Entered resources 2020 When lookup clients expect that certain types of links can only 2021 originate from certain endpoints, then the RD needs to apply 2022 filtering to the links an endpoint may register. 2024 For example, if clients use an RD to find a server that provides 2025 firmware updates, then any registrant that wants to register (or 2026 update) links to firmware sources will need to provide suitable 2027 credentials to do so, independently of its endpoint name. 2029 Note that the impact of having undesirable links in the RD depends on 2030 the application: if the client requires the firmware server to 2031 present credentials as a firmware server, a fraudulent link's impact 2032 is limited to the client revealing its intention to obtain updates 2033 and slowing down the client until it finds a legitimate firmware 2034 server; if the client accepts any credentials from the server as long 2035 as they fit the provided URI, the impact is larger. 2037 An RD may also require that links are only registered if the 2038 registrant is authorized to publish information about the anchor (or 2039 even target) of the link. One way to do this is to demand that the 2040 registrant present the same credentials as a client that they'd need 2041 to present if contacted as a server at the resources' URI, which may 2042 include using the address and port that are part of the URI. Such a 2043 restriction places severe practical limitations on the links that can 2044 be registered. 2046 As above, the impact of undesirable links depends on the extent to 2047 which the lookup client relies on the RD. To avoid the limitations, 2048 RD applications should consider prescribing that lookup clients only 2049 use the discovered information as hints, and describe which pieces of 2050 information need to be verified because they impact the application's 2051 security. A straightforward way to verify such information is to 2052 request it again from an authorized server, typically the one that 2053 hosts the target resource. That similar to what happens in 2054 Section 4.3 when the URI discovery step is repeated. 2056 7.3. Link confidentiality 2058 When registrants publish information in the RD that is not available 2059 to any client that would query the registrant's /.well-known/core 2060 interface, or when lookups to that interface are subject so stricter 2061 firewalling than lookups to the RD, the RD may need to limit which 2062 lookup clients may access the information. 2064 In this case, the endpoint (and not the lookup clients) needs to be 2065 careful to check the RD's authorization. The RD needs to check any 2066 lookup client's authorization before revealing information directly 2067 (in resource lookup) or indirectly (when using it to satisfy a 2068 resource lookup search criterion). 2070 7.4. Segmentation 2072 Within a single RD, different security policies can apply. 2074 One example of this are multi-tenant deployments separated by the 2075 sector (d) parameter. Some sectors might apply limitations on the 2076 endpoint names available, while others use a random identifier 2077 approach to endpoint names and place limits on the entered links 2078 based on their attributes instead. 2080 Care must be taken in such setups to determine the applicable access 2081 control measures to each operation. One easy way to do that is to 2082 mandate the use of the sector parameter on all operations, as no 2083 credentials are suitable for operations across sector borders anyway. 2085 7.5. First-Come-First-Remembered: A default policy 2087 The First-Come-First-Remembered policy is provided both as a 2088 reference example for a security policy definition, and as a policy 2089 that implementations may choose to use as default policy in absence 2090 of other configuration. It is designed to enable efficient discovery 2091 operations even in ad-hoc settings. 2093 Under this policy, the RD accepts registrations for any endpoint name 2094 that is not assigned to an active registration resource, and only 2095 accepts registration updates from the same endpoint. The policy is 2096 minimal in that towards lookup clients it does not make any of the 2097 claims of Section 7.2 and Section 7.3, and its claims on Section 7.1 2098 are limited to the lifetime of that endpoint's registration. It 2099 does, however, guarantee towards any endpoint that for the duration 2100 of its registration, its links will be discoverable on the RD. 2102 When a registration or operation is attempted, the RD MUST determine 2103 the client's subject name or public key: 2105 * If the client's credentials indicate any subject name that is 2106 certified by any authority which the RD recognizes (which may be 2107 the system's trust anchor store), all such subject names are 2108 stored. With CWT or JWT based credentials (as common with ACE), 2109 the Subject (sub) claim is stored as a single name, if it exists. 2110 With X.509 certificates, the Common Name (CN) and the complete 2111 list of SubjectAltName entries are stored. In both cases, the 2112 authority that certified the claim is stored along with the 2113 subject, as the latter may only be locally unique. 2115 * Otherwise, if the client proves possession of a private key, the 2116 matching public key is stored. This applies both to raw public 2117 keys and to the public keys indicated in certificates that failed 2118 the above authority check. 2120 * If neither is present, a reference to the security session itself 2121 is stored. With (D)TLS, that is the connection itself, or the 2122 session resumption information if available. With OSCORE, that is 2123 the security context. 2125 As part of the registration operation, that information is stored 2126 along with the registration resource. 2128 The RD MUST accept all registrations whose registration resource is 2129 not already active, as long as they are made using a security layer 2130 supported by the RD. 2132 Any operation on a registration resource, including registrations 2133 that lead to an existing registration resource, MUST be rejected by 2134 the RD unless all the stored information is found in the new 2135 request's credentials. 2137 Note that even though subject names are compared in this policy, they 2138 are never directly compared to endpoint names, and an endpoint can 2139 not expect to "own" any particular endpoint name outside of an active 2140 registration -- even if a certificate says so. It is an accepted 2141 shortcoming of this approach that the endpoint has no indication of 2142 whether the RD remembers it by its subject name or public key; 2143 recognition by subject happens on a best-effort base (given the RD 2144 may not recognize any authority). Clients MUST be prepared to pick a 2145 different endpoint name when rejected by the RD initially or after a 2146 change in their credentials; picking an endpoint name as per 2147 Section 7.1.1 is an easy option for that. 2149 For this policy to be usable without configuration, clients should 2150 not set a sector name in their registrations. An RD can set a 2151 default sector name for registrations accepted under this policy, 2152 which is useful especially in a segmented setup where different 2153 policies apply to different sectors. The configuration of such a 2154 behavior, as well as any other configuration applicable to such an RD 2155 (i.e. the set of recognized authorities) is out of scope for this 2156 document. 2158 8. Security Considerations 2160 The security considerations as described in Section 5 of [RFC8288] 2161 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 2162 may be protected e.g. using DTLS when hosted on a CoAP server as 2163 described in [RFC7252]. 2165 Access that is limited or affects sensitive data SHOULD be protected, 2166 e.g. using (D)TLS or OSCORE ([RFC8613]; which aspects of the RD this 2167 affects depends on the security policies of the application (see 2168 Section 7). 2170 8.1. Discovery 2172 Most steps in discovery of the RD, and possibly its resources, are 2173 not covered by CoAP's security mechanisms. This will not endanger 2174 the security properties of the registrations and lookup itself (where 2175 the client requires authorization of the RD if it expects any 2176 security properties of the operation), but may leak the client's 2177 intention to third parties, and allow them to slow down the process. 2179 To mitigate that, clients can retain the RD's address, use secure 2180 discovery options like configured addresses, and send queries for RDs 2181 in a very general form ("?rt=core.rd*" rather than "?rt=core.rd- 2182 lookup-ep"). 2184 8.2. Endpoint Identification and Authentication 2186 An Endpoint (name, sector) pair is unique within the set of endpoints 2187 registered by the RD. An Endpoint MUST NOT be identified by its 2188 protocol, port or IP address as these may change over the lifetime of 2189 an Endpoint. 2191 Every operation performed by an Endpoint on an RD SHOULD be mutually 2192 authenticated using Pre-Shared Key, Raw Public Key or Certificate 2193 based security. 2195 Consider the following threat: two devices A and B are registered at 2196 a single server. Both devices have unique, per-device credentials 2197 for use with DTLS to make sure that only parties with authorization 2198 to access A or B can do so. 2200 Now, imagine that a malicious device A wants to sabotage the device 2201 B. It uses its credentials during the DTLS exchange. Then, it 2202 specifies the endpoint name of device B as the name of its own 2203 endpoint in device A. If the server does not check whether the 2204 identifier provided in the DTLS handshake matches the identifier used 2205 at the CoAP layer then it may be inclined to use the endpoint name 2206 for looking up what information to provision to the malicious device. 2208 Endpoint authorization needs to be checked on registration and 2209 registration resource operations independently of whether there are 2210 configured requirements on the credentials for a given endpoint name 2211 (and sector; Section 7.1) or whether arbitrary names are accepted 2212 (Section 7.1.1). 2214 Simple registration could be used to circumvent address-based access 2215 control: An attacker would send a simple registration request with 2216 the victim's address as source address, and later look up the 2217 victim's /.well-known/core content in the RD. Mitigation for this is 2218 recommended in Section 5.1. 2220 The registration resource path is visible to any client that is 2221 allowed endpoint lookup, and can be extracted by resource lookup 2222 clients as well. The same goes for registration attributes that are 2223 shown as target attributes or lookup attributes. The RD needs to 2224 consider this in the choice of registration resource paths, and 2225 administrators or endpoint in their choice of attributes. 2227 8.3. Access Control 2229 Access control SHOULD be performed separately for the RD registration 2230 and Lookup API paths, as different endpoints may be authorized to 2231 register with an RD from those authorized to lookup endpoints from 2232 the RD. Such access control SHOULD be performed in as fine-grained a 2233 level as possible. For example access control for lookups could be 2234 performed either at the sector, endpoint or resource level. 2236 The precise access controls necessary (and the consequences of 2237 failure to enforce them) depend on the protection objectives of the 2238 application and the security policies (Section 7) derived from them. 2240 8.4. Denial of Service Attacks 2242 Services that run over UDP unprotected are vulnerable to unknowingly 2243 amplify and distribute a DoS attack as UDP does not require return 2244 routability check. Since RD lookup responses can be significantly 2245 larger than requests, RDs are prone to this. 2247 [RFC7252] describes this at length in its Section 11.3, including 2248 some mitigation by using small block sizes in responses. The 2249 upcoming [I-D.ietf-core-echo-request-tag] updates that by describing 2250 a source address verification mechanism using the Echo option. 2252 [ If this document is published together with or after I-D.ietf-core- 2253 echo-request-tag, the above paragraph is replaced with the following: 2255 [RFC7252] describes this at length in its Section 11.3, and 2256 [I-D.ietf-core-echo-request-tag] (which updates the former) 2257 recommends using the Echo option to verify the request's source 2258 address. 2260 ] 2262 8.5. Skipping freshness checks 2264 When RD based applications are built in which request freshness 2265 checks are not performed, these concerns need to be balanced: 2267 * When alterations to registration attributes are reordered, an 2268 attacker may create any combination of attributes ever set, with 2269 the attack difficulty determined by the security layer's replay 2270 properties. 2272 For example, if Figure 18 were conducted without freshness 2273 assurances, an attacker could later reset the lifetime back to 2274 7200. Thus, the device is made unreachable to lookup clients. 2276 * When registration updates without query parameters (which just 2277 serve to restart the lifetime) can be reordered, an attacker can 2278 use intercepted messages to give the appearance of the device 2279 being alive to the RD. 2281 This is unacceptable when when the RD's security policy promises 2282 reachability of endpoints (e.g. when disappearing devices would 2283 trigger further investigation), but may be acceptable with other 2284 policies. 2286 9. IANA Considerations 2288 9.1. Resource Types 2290 IANA is asked to enter the following values into the Resource Type 2291 (rt=) Link Target Attribute Values sub-registry of the Constrained 2292 Restful Environments (CoRE) Parameters registry defined in [RFC6690]: 2294 +====================+=============================+=============+ 2295 | Value | Description | Reference | 2296 +====================+=============================+=============+ 2297 | core.rd | Directory resource of an RD | RFCTHIS | 2298 | | | Section 4.3 | 2299 +--------------------+-----------------------------+-------------+ 2300 | core.rd-lookup-res | Resource lookup of an RD | RFCTHIS | 2301 | | | Section 4.3 | 2302 +--------------------+-----------------------------+-------------+ 2303 | core.rd-lookup-ep | Endpoint lookup of an RD | RFCTHIS | 2304 | | | Section 4.3 | 2305 +--------------------+-----------------------------+-------------+ 2306 | core.rd-ep | Endpoint resource of an RD | RFCTHIS | 2307 | | | Section 6 | 2308 +--------------------+-----------------------------+-------------+ 2310 Table 2 2312 9.2. IPv6 ND Resource Directory Address Option 2314 This document registers one new ND option type under the sub-registry 2315 "IPv6 Neighbor Discovery Option Formats" of the "Internet Control 2316 Message Protocol version 6 (ICMPv6) Parameters" registry: 2318 * Resource Directory Address Option (TBD38) 2320 [ The RFC editor is asked to replace TBD38 with the assigned number 2321 in the document; the value 38 is suggested. ] 2323 9.3. RD Parameter Registry 2325 This specification defines a new sub-registry for registration and 2326 lookup parameters called "RD Parameters" under "CoRE Parameters". 2327 Although this specification defines a basic set of parameters, it is 2328 expected that other standards that make use of this interface will 2329 define new ones. 2331 Each entry in the registry must include 2333 * the human readable name of the parameter, 2335 * the short name as used in query parameters or target attributes, 2337 * indication of whether it can be passed as a query parameter at 2338 registration of endpoints, as a query parameter in lookups, or be 2339 expressed as a target attribute, 2341 * syntax and validity requirements if any, 2342 * a description, 2344 * and a link to reference documentation. 2346 The query parameter MUST be both a valid URI query key [RFC3986] and 2347 a token as used in [RFC8288]. 2349 The description must give details on whether the parameter can be 2350 updated, and how it is to be processed in lookups. 2352 The mechanisms around new RD parameters should be designed in such a 2353 way that they tolerate RD implementations that are unaware of the 2354 parameter and expose any parameter passed at registration or updates 2355 on in endpoint lookups. (For example, if a parameter used at 2356 registration were to be confidential, the registering endpoint should 2357 be instructed to only set that parameter if the RD advertises support 2358 for keeping it confidential at the discovery step.) 2360 Initial entries in this sub-registry are as follows: 2362 +==============+=======+==============+=====+=====================+ 2363 | Full name | Short | Validity | Use | Description | 2364 +==============+=======+==============+=====+=====================+ 2365 | Endpoint | ep | Unicode* | RLA | Name of the | 2366 | Name | | | | endpoint | 2367 +--------------+-------+--------------+-----+---------------------+ 2368 | Lifetime | lt | 1-4294967295 | R | Lifetime of the | 2369 | | | | | registration in | 2370 | | | | | seconds | 2371 +--------------+-------+--------------+-----+---------------------+ 2372 | Sector | d | Unicode* | RLA | Sector to which | 2373 | | | | | this endpoint | 2374 | | | | | belongs | 2375 +--------------+-------+--------------+-----+---------------------+ 2376 | Registration | base | URI | RLA | The scheme, address | 2377 | Base URI | | | | and port and path | 2378 | | | | | at which this | 2379 | | | | | server is available | 2380 +--------------+-------+--------------+-----+---------------------+ 2381 | Page | page | Integer | L | Used for pagination | 2382 +--------------+-------+--------------+-----+---------------------+ 2383 | Count | count | Integer | L | Used for pagination | 2384 +--------------+-------+--------------+-----+---------------------+ 2385 | Endpoint | et | Section | RLA | Semantic type of | 2386 | Type | | 9.3.1 | | the endpoint (see | 2387 | | | | | Section 9.4) | 2388 +--------------+-------+--------------+-----+---------------------+ 2390 Table 3: RD Parameters 2392 (Short: Short name used in query parameters or target attributes. 2393 Validity: Unicode* = 63 Bytes of UTF-8 encoded Unicode, with no 2394 control characters as per Section 5. Use: R = used at registration, 2395 L = used at lookup, A = expressed in target attribute.) 2397 The descriptions for the options defined in this document are only 2398 summarized here. To which registrations they apply and when they are 2399 to be shown is described in the respective sections of this document. 2400 All their reference documentation entries point to this document. 2402 The IANA policy for future additions to the sub-registry is "Expert 2403 Review" as described in [RFC8126]. The evaluation should consider 2404 formal criteria, duplication of functionality (Is the new entry 2405 redundant with an existing one?), topical suitability (E.g. is the 2406 described property actually a property of the endpoint and not a 2407 property of a particular resource, in which case it should go into 2408 the payload of the registration and need not be registered?), and the 2409 potential for conflict with commonly used target attributes (For 2410 example, "if" could be used as a parameter for conditional 2411 registration if it were not to be used in lookup or attributes, but 2412 would make a bad parameter for lookup, because a resource lookup with 2413 an "if" query parameter could ambiguously filter by the registered 2414 endpoint property or the [RFC6690] target attribute). 2416 9.3.1. Full description of the "Endpoint Type" RD Parameter 2418 An endpoint registering at an RD can describe itself with endpoint 2419 types, similar to how resources are described with Resource Types in 2420 [RFC6690]. An endpoint type is expressed as a string, which can be 2421 either a URI or one of the values defined in the Endpoint Type sub- 2422 registry. Endpoint types can be passed in the "et" query parameter 2423 as part of extra-attrs at the Registration step, are shown on 2424 endpoint lookups using the "et" target attribute, and can be filtered 2425 for using "et" as a search criterion in resource and endpoint lookup. 2426 Multiple endpoint types are given as separate query parameters or 2427 link attributes. 2429 Note that Endpoint Type differs from Resource Type in that it uses 2430 multiple attributes rather than space separated values. As a result, 2431 RDs implementing this specification automatically support correct 2432 filtering in the lookup interfaces from the rules for unknown 2433 endpoint attributes. 2435 9.4. "Endpoint Type" (et=) RD Parameter values 2437 This specification establishes a new sub-registry under "CoRE 2438 Parameters" called '"Endpoint Type" (et=) RD Parameter values'. The 2439 registry properties (required policy, requirements, template) are 2440 identical to those of the Resource Type parameters in [RFC6690], in 2441 short: 2443 The review policy is IETF Review for values starting with "core", and 2444 Specification Required for others. 2446 The requirements to be enforced are: 2448 * The values MUST be related to the purpose described in 2449 Section 9.3.1. 2451 * The registered values MUST conform to the ABNF reg-rel-type 2452 definition of [RFC6690] and MUST NOT be a URI. 2454 * It is recommended to use the period "." character for 2455 segmentation. 2457 The registry initially contains one value: 2459 * "core.rd-group": An application group as described in Appendix A. 2461 9.5. Multicast Address Registration 2463 IANA is asked to assign the following multicast addresses for use by 2464 CoAP nodes: 2466 IPv4 -- "all CoRE Resource Directories" address MCD2 (suggestion: 2467 224.0.1.189), from the "IPv4 Multicast Address Space Registry". As 2468 the address is used for discovery that may span beyond a single 2469 network, it has come from the Internetwork Control Block (224.0.1.x) 2470 [RFC5771]. 2472 IPv6 -- "all CoRE Resource Directories" address MCD1 (suggestions 2473 FF0X::FE), from the "IPv6 Multicast Address Space Registry", in the 2474 "Variable Scope Multicast Addresses" space (RFC 3307). Note that 2475 there is a distinct multicast address for each scope that interested 2476 CoAP nodes should listen to; CoAP needs the Link-Local and Site-Local 2477 scopes only. 2479 [ The RFC editor is asked to replace MCD1 and MCD2 with the assigned 2480 addresses throughout the document. ] 2482 9.6. Well-Known URIs 2484 IANA is asked to permanently register the URI suffix "rd" in the 2485 "Well-Known URIs" registry. The change controller is the IETF, this 2486 document is the reference. 2488 9.7. Service Names and Transport Protocol Port Number Registry 2490 IANA is asked to enter four new items into the Service Names and 2491 Transport Protocol Port Number Registry: 2493 * Service name: "core-rd", Protocol: "udp", Description: "Resource 2494 Directory accessed using CoAP" 2496 * Service name "core-rd-dtls", Protocol: "udp", Description: 2497 "Resource Directory accessed using CoAP over DTLS" 2499 * Service name: "core-rd", Protocol: "tcp", Description: "Resource 2500 Directory accessed using CoAP over TCP" 2502 * Service name "core-rd-tls", Protocol: "tcp", Description: 2503 "Resource Directory accessed using CoAP over TLS" 2505 All in common have this document as their reference. 2507 10. Examples 2509 Two examples are presented: a Lighting Installation example in 2510 Section 10.1 and a LwM2M example in Section 10.2. 2512 10.1. Lighting Installation 2514 This example shows a simplified lighting installation which makes use 2515 of the RD with a CoAP interface to facilitate the installation and 2516 start-up of the application code in the lights and sensors. In 2517 particular, the example leads to the definition of a group and the 2518 enabling of the corresponding multicast address as described in 2519 Appendix A. No conclusions must be drawn on the realization of 2520 actual installation or naming procedures, because the example only 2521 "emphasizes" some of the issues that may influence the use of the RD 2522 and does not pretend to be normative. 2524 10.1.1. Installation Characteristics 2526 The example assumes that the installation is managed. That means 2527 that a Commissioning Tool (CT) is used to authorize the addition of 2528 nodes, name them, and name their services. The CT can be connected 2529 to the installation in many ways: the CT can be part of the 2530 installation network, connected by WiFi to the installation network, 2531 or connected via GPRS link, or other method. 2533 It is assumed that there are two naming authorities for the 2534 installation: (1) the network manager that is responsible for the 2535 correct operation of the network and the connected interfaces, and 2536 (2) the lighting manager that is responsible for the correct 2537 functioning of networked lights and sensors. The result is the 2538 existence of two naming schemes coming from the two managing 2539 entities. 2541 The example installation consists of one presence sensor, and two 2542 luminaries, luminary1 and luminary2, each with their own wireless 2543 interface. Each luminary contains three lamps: left, right and 2544 middle. Each luminary is accessible through one endpoint. For each 2545 lamp a resource exists to modify the settings of a lamp in a 2546 luminary. The purpose of the installation is that the presence 2547 sensor notifies the presence of persons to a group of lamps. The 2548 group of lamps consists of: middle and left lamps of luminary1 and 2549 right lamp of luminary2. 2551 Before commissioning by the lighting manager, the network is 2552 installed and access to the interfaces is proven to work by the 2553 network manager. 2555 At the moment of installation, the network under installation is not 2556 necessarily connected to the DNS infrastructure. Therefore, SLAAC 2557 IPv6 addresses are assigned to CT, RD, luminaries and the sensor. 2558 The addresses shown in Table 4 below stand in for these in the 2559 following examples. 2561 +=================+================+ 2562 | Name | IPv6 address | 2563 +=================+================+ 2564 | luminary1 | 2001:db8:4::1 | 2565 +-----------------+----------------+ 2566 | luminary2 | 2001:db8:4::2 | 2567 +-----------------+----------------+ 2568 | Presence sensor | 2001:db8:4::3 | 2569 +-----------------+----------------+ 2570 | RD | 2001:db8:4::ff | 2571 +-----------------+----------------+ 2573 Table 4: Addresses used in the 2574 examples 2576 In Section 10.1.2 the use of RD during installation is presented. 2578 10.1.2. RD entries 2580 It is assumed that access to the DNS infrastructure is not always 2581 possible during installation. Therefore, the SLAAC addresses are 2582 used in this section. 2584 For discovery, the resource types (rt) of the devices are important. 2585 The lamps in the luminaries have rt=tag:example.com,2020:light, and 2586 the presence sensor has rt=tag:example.com,2020:p-sensor. The 2587 endpoints have names which are relevant to the light installation 2588 manager. In this case luminary1, luminary2, and the presence sensor 2589 are located in room 2-4-015, where luminary1 is located at the window 2590 and luminary2 and the presence sensor are located at the door. The 2591 endpoint names reflect this physical location. The middle, left and 2592 right lamps are accessed via path /light/middle, /light/left, and 2593 /light/right respectively. The identifiers relevant to the RD are 2594 shown in Table 5 below: 2596 +=========+================+========+===============================+ 2597 |Name |endpoint |resource| resource type | 2598 | | |path | | 2599 +=========+================+========+===============================+ 2600 |luminary1|lm_R2-4-015_wndw|/light/ | tag:example.com,2020:light | 2601 | | |left | | 2602 +---------+----------------+--------+-------------------------------+ 2603 |luminary1|lm_R2-4-015_wndw|/light/ | tag:example.com,2020:light | 2604 | | |middle | | 2605 +---------+----------------+--------+-------------------------------+ 2606 |luminary1|lm_R2-4-015_wndw|/light/ | tag:example.com,2020:light | 2607 | | |right | | 2608 +---------+----------------+--------+-------------------------------+ 2609 |luminary2|lm_R2-4-015_door|/light/ | tag:example.com,2020:light | 2610 | | |left | | 2611 +---------+----------------+--------+-------------------------------+ 2612 |luminary2|lm_R2-4-015_door|/light/ | tag:example.com,2020:light | 2613 | | |middle | | 2614 +---------+----------------+--------+-------------------------------+ 2615 |luminary2|lm_R2-4-015_door|/light/ | tag:example.com,2020:light | 2616 | | |right | | 2617 +---------+----------------+--------+-------------------------------+ 2618 |Presence |ps_R2-4-015_door|/ps | tag:example.com,2020:p-sensor | 2619 |sensor | | | | 2620 +---------+----------------+--------+-------------------------------+ 2622 Table 5: RD identifiers 2624 It is assumed that the CT has performed RD discovery and has received 2625 a response like the one in the Section 4.3 example. 2627 The CT inserts the endpoints of the luminaries and the sensor in the 2628 RD using the registration base URI parameter (base) to specify the 2629 interface address: 2631 Req: POST coap://[2001:db8:4::ff]/rd 2632 ?ep=lm_R2-4-015_wndw&base=coap://[2001:db8:4::1]&d=R2-4-015 2633 Payload: 2634 ;rt="tag:example.com,2020:light", 2635 ;rt="tag:example.com,2020:light", 2636 ;rt="tag:example.com,2020:light" 2638 Res: 2.01 Created 2639 Location-Path: /rd/4521 2641 Req: POST coap://[2001:db8:4::ff]/rd 2642 ?ep=lm_R2-4-015_door&base=coap://[2001:db8:4::2]&d=R2-4-015 2643 Payload: 2644 ;rt="tag:example.com,2020:light", 2645 ;rt="tag:example.com,2020:light", 2646 ;rt="tag:example.com,2020:light" 2648 Res: 2.01 Created 2649 Location-Path: /rd/4522 2651 Req: POST coap://[2001:db8:4::ff]/rd 2652 ?ep=ps_R2-4-015_door&base=coap://[2001:db8:4::3]&d=R2-4-015 2653 Payload: 2654 ;rt="tag:example.com,2020:p-sensor" 2656 Res: 2.01 Created 2657 Location-Path: /rd/4523 2659 Figure 24: Example of registrations a CT enters into an RD 2661 The sector name d=R2-4-015 has been added for an efficient lookup 2662 because filtering on "ep" name is more awkward. The same sector name 2663 is communicated to the two luminaries and the presence sensor by the 2664 CT. 2666 The group is specified in the RD. The base parameter is set to the 2667 site-local multicast address allocated to the group. In the POST in 2668 the example below, the resources supported by all group members are 2669 published. 2671 Req: POST coap://[2001:db8:4::ff]/rd 2672 ?ep=grp_R2-4-015&et=core.rd-group&base=coap://[ff05::1] 2673 Payload: 2674 ;rt="tag:example.com,2020:light", 2675 ;rt="tag:example.com,2020:light", 2676 ;rt="tag:example.com,2020:light" 2678 Res: 2.01 Created 2679 Location-Path: /rd/501 2681 Figure 25: Example of a multicast group a CT enters into an RD 2683 After the filling of the RD by the CT, the application in the 2684 luminaries can learn to which groups they belong, and enable their 2685 interface for the multicast address. 2687 The luminary, knowing its sector and being configured to join any 2688 group containing lights, searches for candidate groups and joins 2689 them: 2691 Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep 2692 ?d=R2-4-015&et=core.rd-group&rt=light 2694 Res: 2.05 Content 2695 Payload: 2696 ;ep=grp_R2-4-015;et=core.rd-group; 2697 base="coap://[ff05::1]";rt=core.rd-ep 2699 Figure 26: Example of a lookup exchange to find suitable 2700 multicast addresses 2702 From the returned base parameter value, the luminary learns the 2703 multicast address of the multicast group. 2705 The presence sensor can learn the presence of groups that support 2706 resources with rt=tag:example.com,2020:light in its own sector by 2707 sending the same request, as used by the luminary. The presence 2708 sensor learns the multicast address to use for sending messages to 2709 the luminaries. 2711 10.2. OMA Lightweight M2M (LwM2M) 2713 OMA LwM2M is a profile for device services based on CoAP, providing 2714 interfaces and operations for device management and device service 2715 enablement. 2717 An LwM2M server is an instance of an LwM2M middleware service layer, 2718 containing an RD ([LwM2M] page 36f). 2720 That RD only implements the registration interface, and no lookup is 2721 implemented. Instead, the LwM2M server provides access to the 2722 registered resources, in a similar way to a reverse proxy. 2724 The location of the LwM2M Server and RD URI path is provided by the 2725 LwM2M Bootstrap process, so no dynamic discovery of the RD is used. 2726 LwM2M Servers and endpoints are not required to implement the /.well- 2727 known/core resource. 2729 11. Acknowledgments 2731 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2732 Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, 2733 Hannes Tschofenig, Sampo Ukkola, Linyi Tian, Jan Newmarch, Matthias 2734 Kovatsch, Jaime Jimenez and Ted Lemon have provided helpful comments, 2735 discussions and ideas to improve and shape this document. Zach would 2736 also like to thank his colleagues from the EU FP7 SENSEI project, 2737 where many of the RD concepts were originally developed. 2739 12. Changelog 2741 changes from -27 to -28 2743 * Security policies / link confidentiality: Point out the RD's 2744 obligations that follow from such a policy. 2746 * Simple registration: clarify term "regular registration" by 2747 introducing it along with the reference to Section 5 2749 * Wording fix in first-come-first-remembered 2751 * Wording fixes in RD definition 2753 * Capitalization: Consistently using "registration resource" 2755 changes from -26 to -27 2757 * In general, this addresses the points that were pointed out in 2758 https://mailarchive.ietf.org/arch/msg/core/xWLomwwhovkU- 2759 CPGNxnvs40BhaM/ as having "evolved from the review comments being 2760 discussed in the interim meetings", and the review comments from 2761 Esko Dijk that were largely entangled in these points. 2763 * Relaxation of the serialization rules for link-format 2765 The interpretation of RFC6690 used in Appendix B.4 was shown to be 2766 faulty. Along with a correction, the common implementations of 2767 link-format were surveyed again and it was found that the only one 2768 that employed the faulty interpretation can still safely be 2769 upgraded. These were removed from the set considered for Limited 2770 Link Format, making the set of valid Limited Link Format documents 2771 larger. 2773 As a consequence, the prescribed serialization of RD output can be 2774 roughly halved in bytes. 2776 There might be additional usage patterns that are possible with 2777 the new set of constraints, but there is insufficient 2778 implementation and deployment experience with them to warrant a 2779 change changes on that front at this point. The specification can 2780 later be extended compatibly to allow these cases and drop the 2781 requirement of Limited Link Format. 2783 * Add Request freshness subsection 2785 It is now recommended (with security considerations on 2786 consequences of not doing it) to require ordering of RD 2787 operations. 2789 The Echo mechanism (previously suggested in various places but 2790 never exclusively) is the one prescribed way of getting this 2791 ordering, making the echo-request-tag reference normative. 2793 * Improved expression about when an RD needs to verify simple 2794 registration. 2796 The simple wording missed the authorization part, and did not 2797 emphasize that this is a per-deployment property. 2799 * Point out the non-atomic properties of paginated access. 2801 * Clarification around impl-info reference. 2803 * Inconsistencies and extraneous quotings removed from examples. 2805 changes from -25 to -26 2807 * Security policies: 2809 - The First-Come-First-Remembered policy is added as an example 2810 and a potential default behavior. 2812 - Clarify that the mapping between endpoint names and subject 2813 fields is up to a policy that defines reliance on names, and 2814 give an example. 2816 - Random EP names: Point that multiple collisions are possible 2817 but unlikely. 2819 - Add pointers to policies: 2821 o RD replication: Point out that policies may limit that. 2823 o Registration: Reword (ep, d) mapping to a previous 2824 registration's resource that could have been read as another 2825 endpoint taking over an existing registration. 2827 - Clarify that the security policy is a property of the RD the 2828 any client may need to verify by checking the RD's 2829 authorization. 2831 - Clarify how information from an untrusted RD can be verified 2833 - Remove speculation about how in detail ACE scopes are obtained. 2835 * Security considerations: 2837 - Generalize to all current options for security layers usable 2838 with CoAP (OSCORE was missing as the text predated RFC8613) 2840 - Relax the previous SHOULD on secure access to SHOULD where 2841 protection is indicated by security policies (bringing the text 2842 in line with the -25 changes) 2844 - Point out that failure to follow the security considerations 2845 has implications depending on the protection objective 2846 described with the security policies 2848 - Shorten amplification mitigation 2850 - Add note about information in Registration Resource path. 2852 - Acknowledge that most host discovery operations are not 2853 secured; mention consequences and mitigation. 2855 * Abstract, introduction: removed "or disperse networks" 2857 * RD discovery: 2859 - Drop the previously stated assumption that RDAO and any DHCP 2860 options would only be used together with SLAAC and DHCP for 2861 address configuration, respectivly. 2863 - Give concrete guidance for address selection based on RFC6724 2864 when responding to multicasts 2866 - RDAO: 2868 o Clarify that it is an option for RAs and not other ND 2869 messages. 2871 o Change Lifetime from 16-bit minutes to 32-bit seconds and 2872 swap it with Reserved (aligning it with RDNSS which it 2873 shares other properties as well). 2875 - Point out that clients may need to check RD authorization 2876 already in last discovery step 2878 * Registration: 2880 - Wording around "mostly mandatory" has been improved, conflicts 2881 clarified and sector default selection adjusted. 2883 * Simple registration: Rather than coopting POSTs to /.well-known/ 2884 core, a new resource /.well-known/rd is registered. A historical 2885 note in the text documents the change. 2887 * Examples: 2889 - Use example URIs rather than unclear reg names (unless it's 2890 RFC6690 examples, which were kept for continuity) 2892 - The LwM2M example was reduced from an outdated explanation of 2893 the complete LwM2M model to a summary of how RD is used in 2894 there, with a reference to the current specification. 2896 - Luminary example: Explain example addresses 2898 - Luminary example: Drop reference to coap-group mechanism that's 2899 becoming obsolete, and thus also to RFC7390 2901 - Multicast addresses in the examples were changed from 2902 ff35:30:2001:db8::x to ff35:30:2001:db8:f1::8000:x; the 8000 is 2903 to follow RFC 3307, and the f1 is for consistency with all the 2904 other example addresses where 2001:db8::/32 is subnetted to 2905 2001:db8:x::/48 by groups of internally consistent examples. 2907 * Use case text enhancements 2909 - Home and building automation: Tie in with RD 2910 - M2M: Move system design paragraph towards the topic of 2911 reusability. 2913 * Various editorial fixes in response to Gen-ART and IESG reviews. 2915 * Rename 'Full description of the "Endpoint Type" Registration 2916 Parameter' section to '... RD Parameter' 2918 * Error handling: Place a SHOULD around the likely cases, and make 2919 the previous "MUST to the best of their capabilities" a "must". 2921 * impl-info: Add note about the type being WIP 2923 * Interaction tables: list CTs as possible initiators where 2924 applicable 2926 * Registration update: Relax requirement to not send parameters 2927 needlessly 2929 * Terminology: Clarify that the CTs' installation events can occur 2930 multiple times. 2932 * Promote RFCs 7252, 7230 and 8288 to normative references 2934 * Moved Christian Amsuess to first author 2936 changes from -24 to -25 2938 * Large rework of section 7 (Security policies) 2940 Rather than prescribing which data in the RD _is_ authenticated 2941 (and how), it now describes what applications built on an RD _can_ 2942 choose to authenticate, show possibilities on how to do it and 2943 outline what it means for clients. 2945 This addresses Russ' Genart review points on details in the text 2946 in a rather broad fashion. That is because the discussion on the 2947 topic inside the WG showed that that text on security has been 2948 driven more review-by-review than by an architectural plan of the 2949 authors and WG. 2951 * Add concrete suggestions (twice as long as registrant number with 2952 retries, or UUIDs without) for random endpoint names 2954 * Point out that simple registration can have faked origins, 2955 RECOMMEND mitigation when applicable and suggest the Echo 2956 mechanism to implement it. 2958 * Reference existing and upcoming specifications for DDOS mitigation 2959 in CoAP. 2961 * Explain the provenance of the example's multicast address. 2963 * Make "SHOULD" of not manipulating foreign registrations a "should" 2964 and explain how it is enforced 2966 * Clarify application of RFC6570 to search parameters 2968 * Syntactic fixes in examples 2970 * IANA: 2972 - Don't announce expected number of registrations (goes to write- 2973 up) 2975 - Include syntax as part of a field's validity in entry 2976 requirements 2978 * Editorial changes 2980 - Align wording between abstract and introduction 2982 - Abbreviation normalization: "ER model", "RD" 2984 - RFC8174 boilerplate update 2986 - Minor clarity fixes 2988 - Markup and layouting 2990 changes from -23 to -24 2992 * Discovery using DNS-SD added again 2994 * Minimum lifetime (lt) reduced from 60 to 1 2996 * References added 2998 * IANA considerations 3000 - added about .well-known/core resource 3002 - added DNS-SD service names 3004 - made RDAO option number a suggestion 3005 - added "reference" field to endpoint type registry 3007 * Lookup: mention that anchor is a legitimate lookup attribute 3009 * Terminology and example fixes 3011 * Layout fixes, esp. the use of non-ASCII characters in figures 3013 changes from -22 to -23 3015 * Explain that updates can not remove attributes 3017 * Typo fixes 3019 changes from -21 to -22 3021 * Request a dedicated IPv4 address from IANA (rather than sharing 3022 with All CoAP nodes) 3024 * Fix erroneous examples 3026 * Editorial changes 3028 - Add figure numbers to examples 3030 - Update RD parameters table to reflect changes of earlier 3031 versions in the text 3033 - Typos and minor wording 3035 changes from -20 to -21 3037 (Processing comments during WGLC) 3039 * Defer outdated description of using DNS-SD to find an RD to the 3040 defining document 3042 * Describe operational conditions in automation example 3044 * Recommend particular discovery mechanisms for some managed network 3045 scenarios 3047 changes from -19 to -20 3049 (Processing comments from the WG chair review) 3051 * Define the permissible characters in endpoint and sector names 3052 * Express requirements on NAT situations in more abstract terms 3054 * Shifted heading levels to have the interfaces on the same level 3056 * Group instructions for error handling into general section 3058 * Simple Registration: process reflowed into items list 3060 * Updated introduction to reflect state of CoRE in general, 3061 reference RFC7228 (defining "constrained") and use "IoT" term in 3062 addition to "M2M" 3064 * Update acknowledgements 3066 * Assorted editorial changes 3068 - Unify examples style 3070 - Terminology: RDAO defined and not only expanded 3072 - Add CT to Figure 1 3074 - Consistency in the use of the term "Content Format" 3076 changes from -18 to -19 3078 * link-local addresses: allow but prescribe split-horizon fashion 3079 when used, disallow zone identifiers 3081 * Remove informative references to documents not mentioned any more 3083 changes from -17 to -18 3085 * Rather than re-specifying link format (Modernized Link Format), 3086 describe a Limited Link Format that's the uncontested subset of 3087 Link Format 3089 * Acknowledging the -17 version as part of the draft 3091 * Move "Read endpoint links" operation to future specification like 3092 PATCH 3094 * Demote links-json to an informative reference, and removed them 3095 from exchange examples 3097 * Add note on unusability of link-local IP addresses, and describe 3098 mitigation. 3100 * Reshuffling of sections: Move additional operations and endpoint 3101 lookup back from appendix, and groups into one 3103 * Lookup interface tightened to not imply applicability for non 3104 link-format lookups (as those can have vastly different views on 3105 link cardinality) 3107 * Simple registration: Change sequence of GET and POST-response, 3108 ensuring unsuccessful registrations are reported as such, and 3109 suggest how devices that would have required the inverse behavior 3110 can still cope with it. 3112 * Abstract and introduction reworded to avoid the impression that 3113 resources are stored in full in the RD 3115 * Simplify the rules governing when a registration resource can or 3116 must be changed. 3118 * Drop a figure that has become useless due to the changes of and 3119 -13 and -17 3121 * Wording consistency fixes: Use "Registrations" and "target 3122 attributes" 3124 * Fix incorrect use of content negotiation in discovery interface 3125 description (Content-Format -> Accept) 3127 * State that the base attribute value is part of endpoint lookup 3128 even when implicit in the registration 3130 * Update references from RFC5988 to its update RFC8288 3132 * Remove appendix on protocol-negotiation (which had a note to be 3133 removed before publication) 3135 changes from -16 to -17 3137 (Note that -17 is published as a direct follow-up to -16, containing 3138 a single change to be discussed at IETF103) 3140 * Removed groups that are enumerations of registrations and have 3141 dedicated mechanism 3143 * Add groups that are enumerations of shared resources and are a 3144 special case of endpoint registrations 3146 changes from -15 to -16 3147 * Recommend a common set of resources for members of a group 3149 * Clarified use of multicast group in lighting example 3151 * Add note on concurrent registrations from one EP being possible 3152 but not expected 3154 * Refresh web examples appendix to reflect current use of Modernized 3155 Link Format 3157 * Add examples of URIs where Modernized Link Format matters 3159 * Editorial changes 3161 changes from -14 to -15 3163 * Rewrite of section "Security policies" 3165 * Clarify that the "base" parameter text applies both to relative 3166 references both in anchor and href 3168 * Renamed "Registree-EP" to Registrant-EP" 3170 * Talk of "relative references" and "URIs" rather than "relative" 3171 and "absolute" URIs. (The concept of "absolute URIs" of [RFC3986] 3172 is not needed in RD). 3174 * Fixed examples 3176 * Editorial changes 3178 changes from -13 to -14 3180 * Rename "registration context" to "registration base URI" (and 3181 "con" to "base") and "domain" to "sector" (where the abbreviation 3182 "d" stays for compatibility reasons) 3184 * Introduced resource types core.rd-ep and core.rd-gp 3186 * Registration management moved to appendix A, including endpoint 3187 and group lookup 3189 * Minor editorial changes 3191 - PATCH/iPATCH is clearly deferred to another document 3193 - Recommend against query / fragment identifier in con= 3194 - Interface description lists are described as illustrative 3196 - Rewording of Simple Registration 3198 * Simple registration carries no error information and succeeds 3199 immediately (previously, sequence was unspecified) 3201 * Lookup: href are matched against resolved values (previously, this 3202 was unspecified) 3204 * Lookup: lt are not exposed any more 3206 * con/base: Paths are allowed 3208 * Registration resource locations can not have query or fragment 3209 parts 3211 * Default life time extended to 25 hours 3213 * clarified registration update rules 3215 * lt-value semantics for lookup clarified. 3217 * added template for simple registration 3219 changes from -12 to -13 3221 * Added "all resource directory" nodes MC address 3223 * Clarified observation behavior 3225 * version identification 3227 * example rt= and et= values 3229 * domain from figure 2 3231 * more explanatory text 3233 * endpoints of a groups hosted by different RD 3235 * resolve RFC6690-vs-8288 resolution ambiguities: 3237 - require registered links not to be relative when using anchor 3239 - return absolute URIs in resource lookup 3241 changes from -11 to -12 3242 * added Content Model section, including ER diagram 3244 * removed domain lookup interface; domains are now plain attributes 3245 of groups and endpoints 3247 * updated chapter "Finding a Resource Directory"; now distinguishes 3248 configuration-provided, network-provided and heuristic sources 3250 * improved text on: atomicity, idempotency, lookup with multiple 3251 parameters, endpoint removal, simple registration 3253 * updated LWM2M description 3255 * clarified where relative references are resolved, and how context 3256 and anchor interact 3258 * new appendix on the interaction with RFCs 6690, 5988 and 3986 3260 * lookup interface: group and endpoint lookup return group and 3261 registration resources as link targets 3263 * lookup interface: search parameters work the same across all 3264 entities 3266 * removed all methods that modify links in an existing registration 3267 (POST with payload, PATCH and iPATCH) 3269 * removed plurality definition (was only needed for link 3270 modification) 3272 * enhanced IANA registry text 3274 * state that lookup resources can be observable 3276 * More examples and improved text 3278 changes from -09 to -10 3280 * removed "ins" and "exp" link-format extensions. 3282 * removed all text concerning DNS-SD. 3284 * removed inconsistency in RDAO text. 3286 * suggestions taken over from various sources 3288 * replaced "Function Set" with "REST API", "base URI", "base path" 3289 * moved simple registration to registration section 3291 changes from -08 to -09 3293 * clarified the "example use" of the base RD resource values /rd, 3294 /rd-lookup, and /rd-group. 3296 * changed "ins" ABNF notation. 3298 * various editorial improvements, including in examples 3300 * clarifications for RDAO 3302 changes from -07 to -08 3304 * removed link target value returned from domain and group lookup 3305 types 3307 * Maximum length of domain parameter 63 bytes for consistency with 3308 group 3310 * removed option for simple POST of link data, don't require a 3311 .well-known/core resource to accept POST data and handle it in a 3312 special way; we already have /rd for that 3314 * add IPv6 ND Option for discovery of an RD 3316 * clarify group configuration section 6.1 that endpoints must be 3317 registered before including them in a group 3319 * removed all superfluous client-server diagrams 3321 * simplified lighting example 3323 * introduced Commissioning Tool 3325 * RD-Look-up text is extended. 3327 changes from -06 to -07 3329 * added text in the discovery section to allow content format hints 3330 to be exposed in the discovery link attributes 3332 * editorial updates to section 9 3334 * update author information 3336 * minor text corrections 3337 Changes from -05 to -06 3339 * added note that the PATCH section is contingent on the progress of 3340 the PATCH method 3342 changes from -04 to -05 3344 * added Update Endpoint Links using PATCH 3346 * http access made explicit in interface specification 3348 * Added http examples 3350 Changes from -03 to -04: 3352 * Added http response codes 3354 * Clarified endpoint name usage 3356 * Add application/link-format+cbor content-format 3358 Changes from -02 to -03: 3360 * Added an example for lighting and DNS integration 3362 * Added an example for RD use in OMA LWM2M 3364 * Added Read Links operation for link inspection by endpoints 3366 * Expanded DNS-SD section 3368 * Added draft authors Peter van der Stok and Michael Koster 3370 Changes from -01 to -02: 3372 * Added a catalogue use case. 3374 * Changed the registration update to a POST with optional link 3375 format payload. Removed the endpoint type update from the update. 3377 * Additional examples section added for more complex use cases. 3379 * New DNS-SD mapping section. 3381 * Added text on endpoint identification and authentication. 3383 * Error code 4.04 added to Registration Update and Delete requests. 3385 * Made 63 bytes a SHOULD rather than a MUST for endpoint name and 3386 resource type parameters. 3388 Changes from -00 to -01: 3390 * Removed the ETag validation feature. 3392 * Place holder for the DNS-SD mapping section. 3394 * Explicitly disabled GET or POST on returned Location. 3396 * New registry for RD parameters. 3398 * Added support for the JSON Link Format. 3400 * Added reference to the Groupcomm WG draft. 3402 Changes from -05 to WG Document -00: 3404 * Updated the version and date. 3406 Changes from -04 to -05: 3408 * Restricted Update to parameter updates. 3410 * Added pagination support for the Lookup interface. 3412 * Minor editing, bug fixes and reference updates. 3414 * Added group support. 3416 * Changed rt to et for the registration and update interface. 3418 Changes from -03 to -04: 3420 * Added the ins= parameter back for the DNS-SD mapping. 3422 * Integrated the Simple Directory Discovery from Carsten. 3424 * Editorial improvements. 3426 * Fixed the use of ETags. 3428 * Fixed tickets 383 and 372 3430 Changes from -02 to -03: 3432 * Changed the endpoint name back to a single registration parameter 3433 ep= and removed the h= and ins= parameters. 3435 * Updated REST interface descriptions to use RFC6570 URI Template 3436 format. 3438 * Introduced an improved RD Lookup design as its own function set. 3440 * Improved the security considerations section. 3442 * Made the POST registration interface idempotent by requiring the 3443 ep= parameter to be present. 3445 Changes from -01 to -02: 3447 * Added a terminology section. 3449 * Changed the inclusion of an ETag in registration or update to a 3450 MAY. 3452 * Added the concept of an RD Domain and a registration parameter for 3453 it. 3455 * Recommended the Location returned from a registration to be 3456 stable, allowing for endpoint and Domain information to be changed 3457 during updates. 3459 * Changed the lookup interface to accept endpoint and Domain as 3460 query string parameters to control the scope of a lookup. 3462 13. References 3464 13.1. Normative References 3466 [I-D.ietf-core-echo-request-tag] 3467 Amsüss, C., Mattsson, J. P., and G. Selander, "CoAP: Echo, 3468 Request-Tag, and Token Processing", Work in Progress, 3469 Internet-Draft, draft-ietf-core-echo-request-tag-12, 1 3470 February 2021, . 3473 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3474 Requirement Levels", BCP 14, RFC 2119, 3475 DOI 10.17487/RFC2119, March 1997, 3476 . 3478 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3479 Resource Identifier (URI): Generic Syntax", STD 66, 3480 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3481 . 3483 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3484 and D. Orchard, "URI Template", RFC 6570, 3485 DOI 10.17487/RFC6570, March 2012, 3486 . 3488 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 3489 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 3490 . 3492 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 3493 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 3494 . 3496 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3497 Protocol (HTTP/1.1): Message Syntax and Routing", 3498 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3499 . 3501 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3502 Application Protocol (CoAP)", RFC 7252, 3503 DOI 10.17487/RFC7252, June 2014, 3504 . 3506 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3507 Writing an IANA Considerations Section in RFCs", BCP 26, 3508 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3509 . 3511 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3512 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3513 May 2017, . 3515 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3516 DOI 10.17487/RFC8288, October 2017, 3517 . 3519 13.2. Informative References 3521 [ER] Chen, P., "The entity-relationship model--toward a unified 3522 view of data", DOI 10.1145/320434.320440, ACM Transactions 3523 on Database Systems Vol. 1, pp. 9-36, March 1976, 3524 . 3526 [I-D.bormann-t2trg-rel-impl] 3527 Bormann, C., "impl-info: A link relation type for 3528 disclosing implementation information", Work in Progress, 3529 Internet-Draft, draft-bormann-t2trg-rel-impl-02, 27 3530 September 2020, . 3533 [I-D.hartke-t2trg-coral] 3534 Hartke, K., "The Constrained RESTful Application Language 3535 (CoRAL)", Work in Progress, Internet-Draft, draft-hartke- 3536 t2trg-coral-09, 8 July 2019, 3537 . 3540 [I-D.ietf-ace-oauth-authz] 3541 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 3542 H. Tschofenig, "Authentication and Authorization for 3543 Constrained Environments (ACE) using the OAuth 2.0 3544 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 3545 draft-ietf-ace-oauth-authz-37, 4 February 2021, 3546 . 3549 [I-D.ietf-core-links-json] 3550 LI, K., Rahman, A., and C. Bormann, "Representing 3551 Constrained RESTful Environments (CoRE) Link Format in 3552 JSON and CBOR", Work in Progress, Internet-Draft, draft- 3553 ietf-core-links-json-10, 26 February 2018, 3554 . 3557 [I-D.ietf-core-rd-dns-sd] 3558 Stok, P. V. D., Koster, M., and C. Amsüss, "CoRE Resource 3559 Directory: DNS-SD mapping", Work in Progress, Internet- 3560 Draft, draft-ietf-core-rd-dns-sd-05, 7 July 2019, 3561 . 3564 [I-D.silverajan-core-coap-protocol-negotiation] 3565 Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation", 3566 Work in Progress, Internet-Draft, draft-silverajan-core- 3567 coap-protocol-negotiation-09, 2 July 2018, 3568 . 3571 [LwM2M] Open Mobile Alliance, "Lightweight Machine to Machine 3572 Technical Specification: Transport Bindings (Candidate 3573 Version 1.1)", 12 June 2018, 3574 . 3578 [RFC3306] Haberman, B. and D. Thaler, "Unicast-Prefix-based IPv6 3579 Multicast Addresses", RFC 3306, DOI 10.17487/RFC3306, 3580 August 2002, . 3582 [RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix 3583 Reserved for Documentation", RFC 3849, 3584 DOI 10.17487/RFC3849, July 2004, 3585 . 3587 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3588 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3589 DOI 10.17487/RFC4122, July 2005, 3590 . 3592 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 3593 "Transmission of IPv6 Packets over IEEE 802.15.4 3594 Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007, 3595 . 3597 [RFC5771] Cotton, M., Vegoda, L., and D. Meyer, "IANA Guidelines for 3598 IPv4 Multicast Address Assignments", BCP 51, RFC 5771, 3599 DOI 10.17487/RFC5771, March 2010, 3600 . 3602 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 3603 "Default Address Selection for Internet Protocol Version 6 3604 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 3605 . 3607 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 3608 Bormann, "Neighbor Discovery Optimization for IPv6 over 3609 Low-Power Wireless Personal Area Networks (6LoWPANs)", 3610 RFC 6775, DOI 10.17487/RFC6775, November 2012, 3611 . 3613 [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing 3614 IPv6 Zone Identifiers in Address Literals and Uniform 3615 Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, 3616 February 2013, . 3618 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3619 Constrained-Node Networks", RFC 7228, 3620 DOI 10.17487/RFC7228, May 2014, 3621 . 3623 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3624 Application Protocol (CoAP)", RFC 7641, 3625 DOI 10.17487/RFC7641, September 2015, 3626 . 3628 [RFC8106] Jeong, J., Park, S., Beloeil, L., and S. Madanapalli, 3629 "IPv6 Router Advertisement Options for DNS Configuration", 3630 RFC 8106, DOI 10.17487/RFC8106, March 2017, 3631 . 3633 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 3634 FETCH Methods for the Constrained Application Protocol 3635 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 3636 . 3638 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names 3639 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, 3640 . 3642 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 3643 "Object Security for Constrained RESTful Environments 3644 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 3645 . 3647 Appendix A. Groups Registration and Lookup 3649 The RD-Groups usage pattern allows announcing application groups 3650 inside an RD. 3652 Groups are represented by endpoint registrations. Their base address 3653 is a multicast address, and they SHOULD be entered with the endpoint 3654 type "core.rd-group". The endpoint name can also be referred to as a 3655 group name in this context. 3657 The registration is inserted into the RD by a Commissioning Tool, 3658 which might also be known as a group manager here. It performs third 3659 party registration and registration updates. 3661 The links it registers SHOULD be available on all members that join 3662 the group. Depending on the application, members that lack some 3663 resource MAY be permissible if requests to them fail gracefully. 3665 The following example shows a CT registering a group with the name 3666 "lights" which provides two resources. The directory resource path 3667 /rd is an example RD location discovered in a request similar to 3668 Figure 5. The group address in the example is constructed from 3669 [RFC3849]'s reserved 2001:db8:: prefix as a unicast-prefix based 3670 site-local address (see [RFC3306]. 3672 Req: POST coap://rd.example.com/rd?ep=lights&et=core.rd-group 3673 &base=coap://[ff35:30:2001:db8:f1::8000:1] 3674 Content-Format: 40 3675 Payload: 3676 ;rt="tag:example.com,2020:light"; 3677 if="tag:example.net,2020:actuator", 3678 ;if="tag:example.net,2020:parameter";u=K 3680 Res: 2.01 Created 3681 Location-Path: /rd/12 3683 Figure 27: Example registration of a group 3685 In this example, the group manager can easily permit devices that 3686 have no writable color-temperature to join, as they would still 3687 respond to brightness changing commands. Had the group instead 3688 contained a single resource that sets brightness and color 3689 temperature atomically, endpoints would need to support both 3690 properties. 3692 The resources of a group can be looked up like any other resource, 3693 and the group registrations (along with any additional registration 3694 parameters) can be looked up using the endpoint lookup interface. 3696 The following example shows a client performing an endpoint lookup 3697 for all groups. 3699 Req: GET /rd-lookup/ep?et=core.rd-group 3701 Res: 2.05 Content 3702 Payload: 3703 ;ep=lights&et=core.rd-group; 3704 base="coap://[ff35:30:2001:f1:db8::8000:1]";rt=core.rd-ep 3706 Figure 28: Example lookup of groups 3708 The following example shows a client performing a lookup of all 3709 resources of all endpoints (groups) with et=core.rd-group. 3711 Req: GET /rd-lookup/res?et=core.rd-group 3713 Res: 2.05 Content 3714 Payload: 3715 ; 3716 rt="tag:example.com,2020:light"; 3717 if="tag:example.net,2020:actuator", 3718 ; 3719 if="tag:example.net,2020:parameter";u=K, 3720 Figure 29: Example lookup of resources inside groups 3722 Appendix B. Web links and the Resource Directory 3724 Understanding the semantics of a link-format document and its URI 3725 references is a journey through different documents ([RFC3986] 3726 defining URIs, [RFC6690] defining link-format documents based on 3727 [RFC8288] which defines Link header fields, and [RFC7252] providing 3728 the transport). This appendix summarizes the mechanisms and 3729 semantics at play from an entry in "/.well-known/core" to a resource 3730 lookup. 3732 This text is primarily aimed at people entering the field of 3733 Constrained Restful Environments from applications that previously 3734 did not use web mechanisms. 3736 B.1. A simple example 3738 Let's start this example with a very simple host, "2001:db8:f0::1". 3739 A client that follows classical CoAP Discovery ([RFC7252] Section 7), 3740 sends the following multicast request to learn about neighbours 3741 supporting resources with resource-type "temperature". 3743 The client sends a link-local multicast: 3745 Req: GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature 3747 Res: 2.05 Content 3748 Payload: 3749 ;rt=temperature;ct=0 3751 Figure 30: Example of direct resource discovery 3753 where the response is sent by the server, "[2001:db8:f0::1]:5683". 3755 While the client -- on the practical or implementation side -- can 3756 just go ahead and create a new request to "[2001:db8:f0::1]:5683" 3757 with Uri-Path: "sensors" and "temp", the full resolution steps for 3758 insertion into and retrieval from the RD without any shortcuts are: 3760 B.1.1. Resolving the URIs 3762 The client parses the single returned record. The link's target 3763 (sometimes called "href") is ""/sensors/temp"", which is a relative 3764 URI that needs resolving. The base URI 3765 is used to resolve the 3766 reference /sensors/temp against. 3768 The Base URI of the requested resource can be composed from the 3769 options of the CoAP GET request by following the steps of [RFC7252] 3770 section 6.5 (with an addition at the end of 8.2) into 3771 ""coap://[2001:db8:f0::1]/.well-known/core"". 3773 Because ""/sensors/temp"" starts with a single slash, the record's 3774 target is resolved by replacing the path ""/.well-known/core"" from 3775 the Base URI (section 5.2 [RFC3986]) with the relative target URI 3776 ""/sensors/temp"" into ""coap://[2001:db8:f0::1]/sensors/temp"". 3778 B.1.2. Interpreting attributes and relations 3780 Some more information but the record's target can be obtained from 3781 the payload: the resource type of the target is "temperature", and 3782 its content format is text/plain (ct=0). 3784 A relation in a web link is a three-part statement that specifies a 3785 named relation between the so-called "context resource" and the 3786 target resource, like "_This page_ has _its table of contents_ at _/ 3787 toc.html_". In link format documents, there is an implicit "host 3788 relation" specified with default parameter: rel="hosts". 3790 In our example, the context resource of the link is implied to be 3791 "coap:://[2001:db8:f0::1]" by the default value of the anchor (see 3792 Appendix B.4). A full English expression of the "host relation" is: 3794 '"coap://[2001:db8:f0::1]" is hosting the resource 3795 "coap://[2001:db8:f0::1]/sensors/temp", which is of the resource type 3796 "temperature" and can be accessed using the text/plain content 3797 format.' 3799 B.2. A slightly more complex example 3801 Omitting the "rt=temperature" filter, the discovery query would have 3802 given some more records in the payload: 3804 Req: GET coap://[ff02::fd]:5683/.well-known/core 3806 Res: 2.05 Content 3807 Payload: 3808 ;rt=temperature;ct=0, 3809 ;rt=light-lux;ct=0, 3810 ;anchor="/sensors/temp";rel=alternate, 3811 ;anchor="/sensors/temp"; 3812 rel=describedby 3814 Figure 31: Extended example of direct resource discovery 3816 Parsing the third record, the client encounters the "anchor" 3817 parameter. It is a URI relative to the Base URI of the request and 3818 is thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That 3819 is the context resource of the link, so the "rel" statement is not 3820 about the target and the Base URI any more, but about the target and 3821 the resolved URI. Thus, the third record could be read as 3822 ""coap://[2001:db8:f0::1]/sensors/temp" has an alternate 3823 representation at "coap://[2001:db8:f0::1]/t"". 3825 Following the same resolution steps, the fourth record can be read as 3826 ""coap://[2001:db8:f0::1]/sensors/temp" is described by 3827 "http://www.example.com/sensors/t123"". 3829 B.3. Enter the Resource Directory 3831 The RD tries to carry the semantics obtainable by classical CoAP 3832 discovery over to the resource lookup interface as faithfully as 3833 possible. 3835 For the following queries, we will assume that the simple host has 3836 used Simple Registration to register at the RD that was announced to 3837 it, sending this request from its UDP port "[2001:db8:f0::1]:6553": 3839 Req: POST coap://[2001:db8:f01::ff]/.well-known/rd?ep=simple-host1 3841 Res: 2.04 Changed 3843 Figure 32: Example of a simple registration 3845 The RD would have accepted the registration, and queried the simple 3846 host's "/.well-known/core" by itself. As a result, the host is 3847 registered as an endpoint in the RD with the name "simple-host1". 3848 The registration is active for 90000 seconds, and the endpoint 3849 registration Base URI is ""coap://[2001:db8:f0::1]"" following the 3850 resolution steps described in Appendix B.1.1. It should be remarked 3851 that the Base URI constructed that way always yields a URI of the 3852 form: scheme://authority without path suffix. 3854 If the client now queries the RD as it would previously have issued a 3855 multicast request, it would go through the RD discovery steps by 3856 fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- 3857 lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the 3858 resource lookup endpoint, and ask it for all temperature resources: 3860 Req: GET coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature 3862 Res: 2.05 Content 3863 Payload: 3864 ;rt=temperature;ct=0 3866 Figure 33: Example exchange performing resource lookup 3868 This is not _literally_ the same response that it would have received 3869 from a multicast request, but it contains the equivalent statement: 3871 '"coap://[2001:db8:f0::1]" is hosting the resource 3872 "coap://[2001:db8:f0::1]/sensors/temp", which is of the resource type 3873 "temperature" and can be accessed using the text/plain content 3874 format.' 3876 To complete the examples, the client could also query all resources 3877 hosted at the endpoint with the known endpoint name "simple-host1": 3879 Req: GET coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1 3881 Res: 2.05 Content 3882 Payload: 3883 ;rt=temperature;ct=0, 3884 ;rt=light-lux;ct=0, 3885 ; 3886 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, 3887 ; 3888 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=describedby 3890 Figure 34: Extended example exchange performing resource lookup 3892 All the target and anchor references are already in absolute form 3893 there, which don't need to be resolved any further. 3895 Had the simple host done an equivalent full registration with a base= 3896 parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple- 3897 host1.example.com"), that context would have been used to resolve the 3898 relative anchor values instead, giving 3900 ;rt=temperature;ct=0 3902 Figure 35: Example payload of a response to a resource lookup 3903 with a dedicated base URI 3905 and analogous records. 3907 B.4. A note on differences between link-format and Link header fields 3909 While link-format and Link header fields look very similar and are 3910 based on the same model of typed links, there are some differences 3911 between [RFC6690] and [RFC8288]. When implementing an RD or 3912 interacting with an RD, care must be taken to follow the [RFC6690] 3913 behavior whenever application/link-format representations are used. 3915 * "Default value of anchor": Both under [RFC6690] and [RFC8288], 3916 relative references in the term inside the angle brackets (the 3917 target) and the anchor attribute are resolved against the relevant 3918 base URI (which usually is the URI used to retrieve the entity), 3919 and independent of each other. 3921 When, in an [RFC8288] Link header, the anchor attribute is absent, 3922 the link's context is the URI of the selected representation (and 3923 usually equal to the base URI). 3925 In [RFC6690] links, if the anchor attribute is absent, the default 3926 value is the Origin of (for all relevant cases: the URI reference 3927 "/" resolved against) the link's target. 3929 * There is no percent encoding in link-format documents. 3931 A link-format document is a UTF-8 encoded string of Unicode 3932 characters and does not have percent encoding, while Link header 3933 fields are practically ASCII strings that use percent encoding for 3934 non-ASCII characters, stating the encoding explicitly when 3935 required. 3937 For example, while a Link header field in a page about a Swedish 3938 city might read 3940 Link: ;rel=live-environment-data 3942 a link-format document from the same source might describe the 3943 link as 3945 ;rel=live-environment-data 3947 Appendix C. Limited Link Format 3949 The CoRE Link Format as described in [RFC6690] has been interpreted 3950 differently by implementers, and a strict implementation rules out 3951 some use cases of an RD (e.g. base values with path components in 3952 combination with absent anchors). 3954 This appendix describes a subset of link format documents called 3955 Limited Link Format. The one rule herein is not very limiting in 3956 practice -- all examples in RFC6690, and all deployments the authors 3957 are aware of already stick to them -- but ease the implementation of 3958 RD servers. 3960 It is applicable to representations in the application/link-format 3961 media type, and any other media types that inherit [RFC6690] 3962 Section 2.1. 3964 A link format representation is in Limited Link format if, for each 3965 link in it, the following applies: 3967 All URI references either follow the URI or the path-absolute ABNF 3968 rule of RFC3986 (i.e. target and anchor each either start with a 3969 scheme or with a single slash). 3971 Authors' Addresses 3973 Christian Amsüss (editor) 3974 Hollandstr. 12/4 3975 1020 3976 Austria 3978 Phone: +43-664-9790639 3979 Email: christian@amsuess.com 3981 Zach Shelby 3982 ARM 3983 150 Rose Orchard 3984 San Jose, 95134 3985 United States of America 3987 Phone: +1-408-203-9434 3988 Email: zach.shelby@arm.com 3990 Michael Koster 3991 SmartThings 3992 665 Clyde Avenue 3993 Mountain View, 94043 3994 United States of America 3996 Phone: +1-707-502-5136 3997 Email: Michael.Koster@smartthings.com 3998 Carsten Bormann 3999 Universitaet Bremen TZI 4000 Postfach 330440 4001 D-28359 Bremen 4002 Germany 4004 Phone: +49-421-218-63921 4005 Email: cabo@tzi.org 4007 Peter van der Stok 4008 consultant 4010 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 4011 Email: consultancy@vanderstok.org 4012 URI: www.vanderstok.org