idnits 2.17.1 draft-ietf-core-resource-directory-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 10 instances of too long lines in the document, the longest one being 26 characters in excess of 72. == There are 2 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 366 has weird spacing: '... target o----...' == Line 368 has weird spacing: '...--o rel o...' == Line 434 has weird spacing: '... o con o----...' == Line 439 has weird spacing: '... o loc o---...' == Line 443 has weird spacing: '... o ep o---...' == (3 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The commissioning tool SHOULD not send any target attributes with the links to the registration resources, and the resource directory SHOULD ignore any attributes that are set. -- The document date (October 30, 2017) is 2369 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.arkko-core-dev-urn' is defined on line 2629, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 2643, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-09 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-05) exists of draft-arkko-core-dev-urn-04 == Outdated reference: A later version (-09) exists of draft-silverajan-core-coap-protocol-negotiation-07 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 14 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft ARM 4 Intended status: Standards Track M. Koster 5 Expires: May 3, 2018 SmartThings 6 C. Bormann 7 Universitaet Bremen TZI 8 P. van der Stok 9 consultant 10 C. Amsuess, Ed. 11 Energy Harvesting Solutions 12 October 30, 2017 14 CoRE Resource Directory 15 draft-ietf-core-resource-directory-12 17 Abstract 19 In many M2M applications, direct discovery of resources is not 20 practical due to sleeping nodes, disperse networks, or networks where 21 multicast traffic is inefficient. These problems can be solved by 22 employing an entity called a Resource Directory (RD), which hosts 23 descriptions of resources held on other servers, allowing lookups to 24 be performed for those resources. This document specifies the web 25 interfaces that a Resource Directory supports in order for web 26 servers to discover the RD and to register, maintain, lookup and 27 remove resource descriptions. Furthermore, new link attributes 28 useful in conjunction with an RD are defined. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on May 3, 2018. 47 Copyright Notice 49 Copyright (c) 2017 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 67 3.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 5 68 3.2. Architecture . . . . . . . . . . . . . . . . . . . . . . 6 69 3.3. Content model . . . . . . . . . . . . . . . . . . . . . . 7 70 3.4. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 11 71 3.5. Use Case: Home and Building Automation . . . . . . . . . 12 72 3.6. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 12 73 4. Finding a Resource Directory . . . . . . . . . . . . . . . . 13 74 4.1. Resource Directory Address Option (RDAO) . . . . . . . . 14 75 5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 15 76 5.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 16 77 5.2. URI Discovery . . . . . . . . . . . . . . . . . . . . . . 16 78 5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 18 79 5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 22 80 5.3.2. Third-party registration . . . . . . . . . . . . . . 23 81 5.4. Operations on the Registration Resource . . . . . . . . . 23 82 5.4.1. Registration Update . . . . . . . . . . . . . . . . . 24 83 5.4.2. Registration Removal . . . . . . . . . . . . . . . . 26 84 5.4.3. Read Endpoint Links . . . . . . . . . . . . . . . . . 27 85 5.4.4. Update Endpoint Links . . . . . . . . . . . . . . . . 28 86 6. RD Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 29 87 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 29 88 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 31 89 7. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 31 90 7.1. Resource lookup . . . . . . . . . . . . . . . . . . . . . 32 91 7.2. Endpoint and group lookup . . . . . . . . . . . . . . . . 33 92 7.3. Lookup filtering . . . . . . . . . . . . . . . . . . . . 33 93 7.4. Lookup examples . . . . . . . . . . . . . . . . . . . . . 35 94 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38 95 8.1. Endpoint Identification and Authentication . . . . . . . 38 96 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 39 97 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 39 98 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 99 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 40 100 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 40 101 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 40 102 9.3.1. Full description of the "Endpoint Type" Registration 103 Parameter . . . . . . . . . . . . . . . . . . . . . . 42 104 9.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . . 42 105 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 42 106 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 43 107 10.1.1. Installation Characteristics . . . . . . . . . . . . 43 108 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 44 109 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 47 110 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 47 111 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 49 112 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 50 113 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 51 114 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 51 115 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 51 116 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 117 13.1. Normative References . . . . . . . . . . . . . . . . . . 56 118 13.2. Informative References . . . . . . . . . . . . . . . . . 57 119 Appendix A. Web links and the Resource Directory . . . . . . . . 58 120 A.1. A simple example . . . . . . . . . . . . . . . . . . . . 58 121 A.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 59 122 A.1.2. Interpreting attributes and relations . . . . . . . . 59 123 A.2. A slightly more complex example . . . . . . . . . . . . . 59 124 A.3. Enter the Resource Directory . . . . . . . . . . . . . . 60 125 A.4. A note on differences between link-format and Link 126 headers . . . . . . . . . . . . . . . . . . . . . . . . . 62 127 Appendix B. Syntax examples for Protocol Negotiation . . . . . . 62 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 63 130 1. Introduction 132 The work on Constrained RESTful Environments (CoRE) aims at realizing 133 the REST architecture in a suitable form for the most constrained 134 nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and 135 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 136 applications such as smart energy and building automation. 138 The discovery of resources offered by a constrained server is very 139 important in machine-to-machine applications where there are no 140 humans in the loop and static interfaces result in fragility. The 141 discovery of resources provided by an HTTP Web Server is typically 142 called Web Linking [RFC5988]. The use of Web Linking for the 143 description and discovery of resources hosted by constrained web 144 servers is specified by the CoRE Link Format [RFC6690]. However, 145 [RFC6690] only describes how to discover resources from the web 146 server that hosts them by querying "/.well-known/core". In many M2M 147 scenarios, direct discovery of resources is not practical due to 148 sleeping nodes, disperse networks, or networks where multicast 149 traffic is inefficient. These problems can be solved by employing an 150 entity called a Resource Directory (RD), which hosts descriptions of 151 resources held on other servers, allowing lookups to be performed for 152 those resources. 154 This document specifies the web interfaces that a Resource Directory 155 supports in order for web servers to discover the RD and to register, 156 maintain, lookup and remove resource descriptions. Furthermore, new 157 link attributes useful in conjunction with a Resource Directory are 158 defined. Although the examples in this document show the use of 159 these interfaces with CoAP [RFC7252], they can be applied in an 160 equivalent manner to HTTP [RFC7230]. 162 2. Terminology 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 166 "OPTIONAL" in this document are to be interpreted as described in 167 [RFC2119]. The term "byte" is used in its now customary sense as a 168 synonym for "octet". 170 This specification requires readers to be familiar with all the terms 171 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 172 should also be familiar with the terms and concepts discussed in 173 [RFC7252]. To describe the REST interfaces defined in this 174 specification, the URI Template format is used [RFC6570]. 176 This specification makes use of the following additional terminology: 178 Resource Directory 179 A web entity that stores information about web resources and 180 implements the REST interfaces defined in this specification for 181 registration and lookup of those resources. 183 Domain 184 In the context of a Resource Directory, a domain is a logical 185 grouping of endpoints. 187 Group 188 In the context of a Resource Directory, a group is a logical 189 grouping of endpoints for the purpose of group communications. 190 All groups within a domain have unique names. 192 Endpoint 193 Endpoint (EP) is a term used to describe a web server or client in 194 [RFC7252]. In the context of this specification an endpoint is 195 used to describe a web server that registers resources to the 196 Resource Directory. An endpoint is identified by its endpoint 197 name, which is included during registration, and has a unique name 198 within the associated domain of the registration. 200 Context 201 A Context is a base URL that gives scheme and (typically) 202 authority information about an Endpoint. The Context of an 203 Endpoint is provided at registration time, and is used by the 204 Resource Directory to resolve relative references inside the 205 registration into absolute URIs. 207 Directory Resource 208 A resource in the Resource Directory (RD) containing registration 209 resources. 211 Group Resource 212 A resource in the RD containing registration resources of the 213 Endpoints that form a group. 215 Registration Resource 216 A resource in the RD that contains information about an Endpoint 217 and its links. 219 Commissioning Tool 220 Commissioning Tool (CT) is a device that assists during the 221 installation of the network by assigning values to parameters, 222 naming endpoints and groups, or adapting the installation to the 223 needs of the applications. 225 RDAO 226 Resource Directory Address Option. 228 3. Architecture and Use Cases 230 3.1. Principles 232 The Resource Directory is primarily a tool to make discovery 233 operations more efficient than querying /.well-known/core on all 234 connected device, or across boundaries that would be limiting those 235 operations. 237 It provides a cache (in the high-level sense, not as defined in 238 [RFC7252]/[RFC2616]) of data that could otherwise only be obtained by 239 directly querying the /.well-known/core resource on the target 240 device, or by accessing those resources with a multicast request. 242 From that, it follows that no information should be stored in the 243 resource directory that cannot be discovered from querying the 244 described device's /.well-known/core resource directly. 246 It also follows that data in the resource directory can only be 247 provided by the device whose descriptions are cached or a dedicated 248 Commissioning Tool (CT). These CTs are thought to act on behalf 249 agents too constrained, or generally unable, to present that 250 information themselves. No other client can modify data in the 251 resource directory or even expect those changes to propagate back to 252 its source. 254 3.2. Architecture 256 The resource directory architecture is illustrated in Figure 1. A 257 Resource Directory (RD) is used as a repository for Web Links 258 [RFC5988] about resources hosted on other web servers, which are 259 called endpoints (EP). An endpoint is a web server associated with a 260 scheme, IP address and port, thus a physical node may host one or 261 more endpoints. The RD implements a set of REST interfaces for 262 endpoints to register and maintain sets of Web Links (called resource 263 directory registration entries), and for clients to lookup resources 264 from the RD or maintain groups. Endpoints themselves can also act as 265 clients. An RD can be logically segmented by the use of Domains. 266 The domain an endpoint is associated with can be defined by the RD or 267 configured by an outside entity. This information hierarchy is shown 268 in Figure 2. 270 A mechanism to discover an RD using CoRE Link Format [RFC6690] is 271 defined. 273 Endpoints proactively register and maintain resource directory 274 registration entries on the RD, which are soft state and need to be 275 periodically refreshed. 277 An endpoint is provided with interfaces to register, update and 278 remove a resource directory registration entry. It is also possible 279 for an RD to fetch Web Links from endpoints and add them as resource 280 directory registration entries. 282 At the first registration of a set of entries, a "registration 283 resource" is created, the location of which is returned to the 284 registering endpoint. The registering endpoint uses this 285 registration resource to manage the contents of the registration 286 entry. 288 A lookup interface for discovering any of the Web Links held in the 289 RD is provided using the CoRE Link Format. 291 Registration Lookup, Group 292 Interface Interfaces 293 +----+ | | 294 | EP |---- | | 295 +----+ ---- | | 296 --|- +------+ | 297 +----+ | ----| | | +--------+ 298 | EP | ---------|-----| RD |----|-----| Client | 299 +----+ | ----| | | +--------+ 300 --|- +------+ | 301 +----+ ---- | | 302 | EP |---- | | 303 +----+ 305 Figure 1: The resource directory architecture. 307 +------------+ 308 | Domain | <-- Name 309 +------------+ 310 | | 311 | +------------+ 312 | | Group | <-- Name, Scheme, IP, Port 313 | +------------+ 314 | | 315 +------------+ 316 | Endpoint | <-- Name, Scheme, IP, Port 317 +------------+ 318 | 319 | 320 +------------+ 321 | Resource | <-- Target, Parameters 322 +------------+ 324 Figure 2: The resource directory information hierarchy. 326 3.3. Content model 328 The Entity-Relationship (ER) models shown in Figure 3 and Figure 4 329 model the contents of /.well-known/core and the resource directory 330 respectively, with entity-relationship diagrams [ER]. Entities 331 (rectangles) are used for concepts that exist independently. 332 Attributes (ovals) are used for concepts that exist only in 333 connection with a related entity. Relations (diamonds) give a 334 semantic meaning to the relation between entities. Numbers specify 335 the cardinality of the relations. 337 Some of the attribute values are URIs. Those values are always full 338 URIs and never relative references in the information model. They 339 can, however, be expressed as relative references in serializations, 340 and often are. 342 These models provide an abstract view of the information expressed in 343 link-format documents and a Resource Directory. They cover the 344 concepts, but not necessarily all details of an RD's operation; they 345 are meant to give an overview, and not be a template for 346 implementations. 348 +----------------------+ 349 | /.well-known/core | 350 +----------------------+ 351 | 352 | 1 353 ////////\\\\\\\ 354 < contains > 355 \\\\\\\\/////// 356 | 357 | 0+ 358 +--------------------+ 359 | link | 360 +--------------------+ 361 | 362 | 1 oooooooo 363 +-----o target o 364 0+ | oooooooo 365 oooooooooooo | 366 o target o--------+ 367 o attribute o | 0+ oooooo 368 oooooooooooo +-----o rel o 369 | oooooo 370 | 371 | 1 ooooooooo 372 +-----o context o 373 ooooooooo 375 Figure 3: E-R Model of the content of /.well-known/core 377 The model shown in Figure 3 models the contents of /.well-known/core 378 which contains: 380 o a set of links belonging to the host 382 The host is free to choose links it deems appropriate to be exposed 383 in its ".well-known/core". Typically, the links describe resources 384 that are served by the host, but the set can also contain links to 385 resources on other servers (see examples in [RFC6690] page 14). The 386 set does not necessarily contain links to all resources served by the 387 host. 389 A link has the following attributes: 391 o Zero or more link relations: They describe a relations between the 392 link context and the link target. 394 In link-format serialization, they are expressed as space- 395 separated values in the "rel" attribute, and default to "hosts". 397 o A link context URI: It defines the source of the relation, eg. 398 _who_ "hosts" something. 400 In link-format serialization, it is expressed in the "anchor" 401 attribute. There, it can be a relative reference, in which case 402 it gets resolved against the URI of the ".well-known/core" 403 document it was obtained from . It defaults to that document's 404 URI. 406 In the serialization, the context also serves as the Base URI for 407 resolving the target reference. 409 o A link target URI: It defines the destination of the relation (eg. 410 _what_ is hosted), and is the topic of all target attributes. 412 In link-format serialization, it is expressed between angular 413 brackets, and sometimes called the "href". If it is a relative URI, 414 it gets resolved against the link context URI. 416 o Other target attributes (eg. resource type (rt), interface (if), 417 cor content-type (ct)). These provide additional information 418 about the target URI. 420 +----------------------+ 421 | resource-directory | 422 +----------------------+ 423 | 424 | oooooooooooo 0-1 425 | o MC address o---+ 426 | oooooooooooo | 427 | | 428 //////\\\\ 0+ +--------+ 429 < contains >----------------| group | 430 \\\\\///// +--------+ 431 | | 432 0-n | | 1+ 433 ooooooo 1 +---------------+ ///////\\\\\\ 434 o con o-------| registration |---------< composed of > 435 ooooooo +---------------+ \\\\\\\////// 436 | | 437 | +--------------+ 438 oooooooo 1 | | 439 o loc o----+ /////\\\\ 440 oooooooo | < contains > 441 | \\\\\///// 442 oooooooo 1 | | 443 o ep o----+ | 0+ 444 oooooooo | +------------------+ 445 | | link | 446 oooooooo 0-1 | +------------------+ 447 o d o----+ | 448 oooooooo | | 1 oooooooo 449 | +-----o target o 450 oooooooo 0-1 | | oooooooo 451 o lt o----+ ooooooooooo 0+ | 452 oooooooo | o target o-----+ 453 | o attribute o | 0+ oooooo 454 ooooooooooo 0+ | ooooooooooo +-----o rel o 455 o endpoint o----+ | oooooo 456 o attribute o | 457 ooooooooooo | 1 ooooooooo 458 +----o context o 459 ooooooooo 461 Figure 4: E-R Model of the content of the Resource Directory 463 The model shown in Figure 4 models the contents of the resource 464 directory which contains in addition to /.well-known/core: 466 o 0 to n Registration (entries), 467 o 0 or more Groups 469 A Group has no or one Multicast address attribute and is composed of 470 0 or more endpoints. A registration is associated with one endpoint 471 (ep). An endpoint can be part of 0 or more Groups . A registration 472 defines a set of links as defined for /.well-known/core. A 473 Registration has six attributes: 475 o one ep (endpoint with a unique name) 477 o one con (a string describing the scheme://authority part) 479 o one lt (lifetime), 481 o one loc (location in the RD) 483 o optional one d (domain for query filtering), 485 o optional additional endpoint attributes (from Section 9.3) 487 The cardinality of con is currently 1. Its value is used as a Base 488 URI when resolving URIs in the links contained in the endpoint. 490 Links are modelled as they are in Figure 3. 492 3.4. Use Case: Cellular M2M 494 Over the last few years, mobile operators around the world have 495 focused on development of M2M solutions in order to expand the 496 business to the new type of users: machines. The machines are 497 connected directly to a mobile network using an appropriate embedded 498 wireless interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing 499 short and wide range wireless interfaces. From the system design 500 point of view, the ambition is to design horizontal solutions that 501 can enable utilization of machines in different applications 502 depending on their current availability and capabilities as well as 503 application requirements, thus avoiding silo like solutions. One of 504 the crucial enablers of such design is the ability to discover 505 resources (machines -- endpoints) capable of providing required 506 information at a given time or acting on instructions from the end 507 users. 509 Imagine a scenario where endpoints installed on vehicles enable 510 tracking of the position of these vehicles for fleet management 511 purposes and allow monitoring of environment parameters. During the 512 boot-up process endpoints register with a Resource Directory, which 513 is hosted by the mobile operator or somewhere in the cloud. 515 Periodically, these endpoints update their registration and may 516 modify resources they offer. 518 When endpoints are not always connected, for example because they 519 enter a sleep mode, a remote server is usually used to provide proxy 520 access to the endpoints. Mobile apps or web applications for 521 environment monitoring contact the RD, look up the endpoints capable 522 of providing information about the environment using appropriate set 523 of link parameters, obtain information on how to contact them (URLs 524 of the proxy server) and then initiate interaction to obtain 525 information that is finally processed, displayed on the screen and 526 usually stored in a database. Similarly, fleet management systems 527 provide the appropriate link parameters to the RD to look up for EPs 528 deployed on the vehicles the application is responsible for. 530 3.5. Use Case: Home and Building Automation 532 Home and commercial building automation systems can benefit from the 533 use of M2M web services. The discovery requirements of these 534 applications are demanding. Home automation usually relies on run- 535 time discovery to commission the system, whereas in building 536 automation a combination of professional commissioning and run-time 537 discovery is used. Both home and building automation involve peer- 538 to-peer interactions between endpoints, and involve battery-powered 539 sleeping devices. 541 3.6. Use Case: Link Catalogues 543 Resources may be shared through data brokers that have no knowledge 544 beforehand of who is going to consume the data. Resource Directory 545 can be used to hold links about resources and services hosted 546 anywhere to make them discoverable by a general class of 547 applications. 549 For example, environmental and weather sensors that generate data for 550 public consumption may provide the data to an intermediary server, or 551 broker. Sensor data are published to the intermediary upon changes 552 or at regular intervals. Descriptions of the sensors that resolve to 553 links to sensor data may be published to a Resource Directory. 554 Applications wishing to consume the data can use RD Lookup to 555 discover and resolve links to the desired resources and endpoints. 556 The Resource Directory service need not be coupled with the data 557 intermediary service. Mapping of Resource Directories to data 558 intermediaries may be many-to-many. 560 Metadata in web link formats like [RFC6690] are supplied by Resource 561 Directories, which may be internally stored as triples, or relation/ 562 attribute pairs providing metadata about resource links. External 563 catalogs that are represented in other formats may be converted to 564 common web linking formats for storage and access by Resource 565 Directories. Since it is common practice for these to be URN 566 encoded, simple and lossless structural transforms should generally 567 be sufficient to store external metadata in Resource Directories. 569 The additional features of Resource Directory allow domains to be 570 defined to enable access to a particular set of resources from 571 particular applications. This provides isolation and protection of 572 sensitive data when needed. Resource groups may defined to allow 573 batched reads from multiple resources. 575 4. Finding a Resource Directory 577 A device coming up may want to find one or more resource directories 578 to make itself known with. 580 The device may be pre-configured to exercise specific mechanisms for 581 finding the resource directory: 583 o It may be configured with a specific IP address for the RD. That 584 IP address may also be an anycast address, allowing the network to 585 forward RD requests to an RD that is topologically close; each 586 target network environment in which some of these preconfigured 587 nodes are to be brought up is then configured with a route for 588 this anycast address that leads to an appropriate RD. (Instead of 589 using an anycast address, a multicast address can also be 590 preconfigured. The RD directory servers then need to configure 591 one of their interfaces with this multicast address.) 593 o It may be configured with a DNS name for the RD and a resource- 594 record type to look up under this name; it can find a DNS server 595 to perform the lookup using the usual mechanisms for finding DNS 596 servers. 598 o It may be configured to use a service discovery mechanism such as 599 DNS-SD [RFC6763]. The present specification suggests configuring 600 the service with name rd._sub._coap._udp, preferably within the 601 domain of the querying nodes. 603 For cases where the device is not specifically configured with a way 604 to find a resource directory, the network may want to provide a 605 suitable default. 607 o If the address configuration of the network is performed via 608 SLAAC, this is provided by the RDAO option Section 4.1. 610 o If the address configuration of the network is performed via DHCP, 611 this could be provided via a DHCP option (no such option is 612 defined at the time of writing). 614 Finally, if neither the device nor the network offer any specific 615 configuration, the device may want to employ heuristics to find a 616 suitable resource directory. 618 The present specification does not fully define these heuristics, but 619 suggests a number of candidates: 621 o In a 6LoWPAN, just assume the Edge Router (6LBR) can act as a 622 resource directory (using the ABRO option to find that [RFC6775]). 623 Confirmation can be obtained by sending a Unicast to 624 "coap://[6LBR]/.well-known/core?rt=core.rd*". 626 o In a network that supports multicast well, discovering the RD 627 using a multicast query for /.well-known/core as specified in CoRE 628 Link Format [RFC6690]: Sending a Multicast GET to 629 "coap://[ff02::1]/.well-known/core?rt=core.rd*". RDs within the 630 multicast scope will answer the query. 632 As some of the RD addresses obtained by the methods listed here are 633 just (more or less educated) guesses, endpoints MUST make use of any 634 error messages to very strictly rate-limit requests to candidate IP 635 addresses that don't work out. For example, an ICMP Destination 636 Unreachable message (and, in particular, the port unreachable code 637 for this message) may indicate the lack of a CoAP server on the 638 candidate host, or a CoAP error response code such as 4.05 "Method 639 Not Allowed" may indicate unwillingness of a CoAP server to act as a 640 directory server. 642 4.1. Resource Directory Address Option (RDAO) 644 The Resource Directory Option (RDAO) using IPv6 neighbor Discovery 645 (ND) carries information about the address of the Resource Directory 646 (RD). This information is needed when endpoints cannot discover the 647 Resource Directory with link-local multicast address because the 648 endpoint and the RD are separated by a border Router (6LBR). In many 649 circumstances the availability of DHCP cannot be guaranteed either 650 during commissioning of the network. The presence and the use of the 651 RD is essential during commissioning. 653 It is possible to send multiple RDAO options in one message, 654 indicating as many resource directory addresses. 656 The lifetime 0x0 means that the RD address is invalid and to be 657 removed. 659 The RDAO format is: 661 0 1 2 3 662 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 663 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 664 | Type | Length = 3 | Valid Lifetime | 665 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 666 | Reserved | 667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 668 | | 669 + + 670 | | 671 + RD Address + 672 | | 673 + + 674 | | 675 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 677 Fields: 679 Type: 38 681 Length: 8-bit unsigned integer. The length of 682 the option in units of 8 bytes. 683 Always 3. 685 Valid Lifetime: 16-bit unsigned integer. The length of 686 time in units of 60 seconds (relative to 687 the time the packet is received) that 688 this Resource Directory address is valid. 689 A value of all zero bits (0x0) indicates 690 that this Resource Directory address 691 is not valid anymore. 693 Reserved: This field is unused. It MUST be 694 initialized to zero by the sender and 695 MUST be ignored by the receiver. 697 RD Address: IPv6 address of the RD. 699 Figure 5: Resource Directory Address Option 701 5. Resource Directory 703 This section defines the required set of REST interfaces between a 704 Resource Directory (RD) and endpoints. Although the examples 705 throughout this section assume the use of CoAP [RFC7252], these REST 706 interfaces can also be realized using HTTP [RFC7230]. In all 707 definitions in this section, both CoAP response codes (with dot 708 notation) and HTTP response codes (without dot notation) are shown. 709 An RD implementing this specification MUST support the discovery, 710 registration, update, lookup, and removal interfaces defined in this 711 section. 713 All operations on the contents of the Resource Directory MUST be 714 atomic and idempotent. 716 A resource directory MAY make the information submitted to it 717 available to further directories, if it can ensure that a loop does 718 not form. The protocol used between directories to ensure loop-free 719 operation is outside the scope of this document. 721 5.1. Content Formats 723 Resource Directory implementations using this specification MUST 724 support the application/link-format content format (ct=40). 726 Resource Directories implementing this specification MAY support 727 additional content formats. 729 Any additional content format supported by a Resource Directory 730 implementing this specification MUST have an equivalent serialization 731 in the application/link-format content format. 733 5.2. URI Discovery 735 Before an endpoint can make use of an RD, it must first know the RD's 736 address and port, and the URI path information for its REST APIs. 737 This section defines discovery of the RD and its URIs using the well- 738 known interface of the CoRE Link Format [RFC6690]. A complete set of 739 RD discovery methods is described in Section 4. 741 Discovery of the RD registration URI path is performed by sending 742 either a multicast or unicast GET request to "/.well-known/core" and 743 including a Resource Type (rt) parameter [RFC6690] with the value 744 "core.rd" in the query string. Likewise, a Resource Type parameter 745 value of "core.rd-lookup*" is used to discover the URIs for RD Lookup 746 operations, and "core.rd-group" is used to discover the URI path for 747 RD Group operations. Upon success, the response will contain a 748 payload with a link format entry for each RD function discovered, 749 indicating the URI path of the RD function returned and the 750 corresponding Resource Type. When performing multicast discovery, 751 the multicast IP address used will depend on the scope required and 752 the multicast capabilities of the network. 754 A Resource Directory MAY provide hints about the content-formats it 755 supports in the links it exposes or registers, using the "ct" link 756 attribute, as shown in the example below. Clients MAY use these 757 hints to select alternate content-formats for interaction with the 758 Resource Directory. 760 HTTP does not support multicast and consequently only unicast 761 discovery can be supported using HTTP. Links to Resource Directories 762 MAY be registered in other Resource Directories, and well-known entry 763 points SHOULD be provided to enable the bootstrapping of unicast 764 discovery. 766 An RD implementation of this specification MUST support query 767 filtering for the rt parameter as defined in [RFC6690]. 769 The discovery request interface is specified as follows: 771 Interaction: EP -> RD 773 Method: GET 775 URI Template: /.well-known/core{?rt} 777 URI Template Variables: 779 rt := Resource Type (optional). MAY contain one of the values 780 "core.rd", "core.rd-lookup*", "core.rd-lookup-res", "core.rd- 781 lookup-ep", "core.rd-lookup-gp", "core.rd-group" or "core.rd*" 783 Content-Format: application/link-format (if any) 785 Content-Format: application/link-format+json (if any) 787 Content-Format: application/link-format+cbor (if any) 789 The following response codes are defined for this interface: 791 Success: 2.05 "Content" or 200 "OK" with an application/link-format, 792 application/link-format+json, or application/link-format+cbor 793 payload containing one or more matching entries for the RD 794 resource. 796 Failure: 4.00 "Bad Request" or 400 "Bad Request" is returned in case 797 of a malformed request for a unicast request. 799 Failure: No error response to a multicast request. 801 HTTP support : YES (Unicast only) 802 The following example shows an endpoint discovering an RD using this 803 interface, thus learning that the directory resource is, in this 804 example, at /rd, and that the content-format delivered by the server 805 hosting the resource is application/link-format (ct=40). Note that 806 it is up to the RD to choose its RD resource paths. 808 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 810 Res: 2.05 Content 811 ;rt="core.rd";ct=40, 812 ;rt="core.rd-lookup-ep";ct=40, 813 ;rt="core.rd-lookup-res";ct=40, 814 ;rt="core.rd-lookup-gp";ct=40, 815 ;rt="core.rd-group";ct=40 817 Figure 6: Example discovery exchange 819 The following example shows the way of indicating that a client may 820 request alternate content-formats. The Content-Format code attribute 821 "ct" MAY include a space-separated sequence of Content-Format codes 822 as specified in Section 7.2.1 of [RFC7252], indicating that multiple 823 content-formats are available. The example below shows the required 824 Content-Format 40 (application/link-format) indicated as well as the 825 the CBOR and JSON representation of link format. The RD resource 826 paths /rd, /rd-lookup, and /rd-group are example values. 828 [ The RFC editor is asked to replace these and later occurrences of 829 TBD64 and TBD504 with the numeric ID values assigned by IANA to 830 application/link-format+cbor and application/link-format+json, 831 respectively, as they are defined in I-D.ietf-core-links-json. ] 833 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 835 Res: 2.05 Content 836 ;rt="core.rd";ct="40 65225", 837 ;rt="core.rd-lookup-res";ct="40 TBD64 TBD504", 838 ;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504", 839 ;rt="core.rd-lookup-gp";ct=40 TBD64 TBD504", 840 ;rt="core.rd-group";ct="40 TBD64 TBD504" 842 5.3. Registration 844 After discovering the location of an RD, an endpoint MAY register its 845 resources using the registration interface. This interface accepts a 846 POST from an endpoint containing the list of resources to be added to 847 the directory as the message payload in the CoRE Link Format 848 [RFC6690], JSON CoRE Link Format (application/link-format+json), or 849 CBOR CoRE Link Format (application/link-format+cbor) 851 [I-D.ietf-core-links-json], along with query parameters indicating 852 the name of the endpoint, and optionally its domain and the lifetime 853 of the registration. It is expected that other specifications will 854 define further parameters (see Section 9.3). The RD then creates a 855 new registration resource in the RD and returns its location. An 856 endpoint MUST use that location when refreshing registrations using 857 this interface. Registration resources in the RD are kept active for 858 the period indicated by the lifetime parameter. The endpoint is 859 responsible for refreshing the registration resource within this 860 period using either the registration or update interface. The 861 registration interface MUST be implemented to be idempotent, so that 862 registering twice with the same endpoint parameters ep and d does not 863 create multiple registration resources. A new registration resource 864 may be created at any time to supersede an existing registration, 865 replacing the registration parameters and links. 867 An empty payload is considered a malformed request. 869 The posted link-format document can (and typically does) contain 870 relative references both in its link targets and in its anchors, or 871 contain empty anchors. The RD server needs to resolve these 872 references in order to faithfully represent them in lookups. The 873 Base URI against which they are resolved is the context of the 874 registration, which is provided either explicitly in the "con" 875 parameter or constructed implicitly from the requester's network 876 address. When resolving relative target references, the server first 877 resolves the context of that link, and then interprets the target as 878 a reference relative to that context (see Appendix A.4). 880 The registration request interface is specified as follows: 882 Interaction: EP -> RD 884 Method: POST 886 URI Template: {+rd}{?ep,d,lt,con,extra-attrs*} 888 URI Template Variables: 890 rd := RD registration URI (mandatory). This is the location of 891 the RD, as obtained from discovery. 893 ep := Endpoint name (mostly mandatory). The endpoint name is an 894 identifier that MUST be unique within a domain. The maximum 895 length of this parameter is 63 bytes. If the RD is configured 896 to recognize the endpoint (eg. based on its security context), 897 the endpoint can elide the endpoint name, and assign one based 898 on the configuration. 900 d := Domain (optional). The domain to which this endpoint 901 belongs. The maximum length of this parameter is 63 bytes. 902 When this parameter is elided, the RD MAY associate the 903 endpoint with a configured default domain. 905 lt := Lifetime (optional). Lifetime of the registration in 906 seconds. Range of 60-4294967295. If no lifetime is included 907 in the initial registration, a default value of 86400 (24 908 hours) SHOULD be assumed. 910 con := Context (optional). This parameter sets the Default Base 911 URI under which the request's links are to be interpreted. The 912 URI MUST NOT have a path component of its own, but MUST be 913 suitable as a base URI to resolve any relative references given 914 in the registration. The parameter is therefore of the shape 915 "scheme://authority" for HTTP and CoAP URIs. In the absence of 916 this parameter the scheme of the protocol, source address and 917 source port of the registration request are assumed. This 918 parameter is mandatory when the directory is filled by a third 919 party such as an commissioning tool. If the endpoint uses an 920 ephemeral port to register with, it MUST include the con 921 parameter in the registration to provide a valid network path. 922 If the endpoint which is located behind a NAT gateway is 923 registering with a Resource Directory which is on the network 924 service side of the NAT gateway, the endpoint MUST use a 925 persistent port for the outgoing registration in order to 926 provide the NAT gateway with a valid network address for 927 replies and incoming requests. 929 extra-attrs := Additional registration attributes (optional). 930 The endpoint can pass any parameter registered at Section 9.3 931 to the directory. If the RD is aware of the parameter's 932 specified semantics, it processes it accordingly. Otherwise, 933 it MUST store the unknown key and its value(s) as an endpoint 934 attribute for further lookup. 936 Content-Format: application/link-format 938 Content-Format: application/link-format+json 940 Content-Format: application/link-format+cbor 942 The following response codes are defined for this interface: 944 Success: 2.01 "Created" or 201 "Created". The Location header 945 option MUST be included in the response when a new registration 946 resource is created. This Location MUST be a stable identifier 947 generated by the RD as it is used for all subsequent operations on 948 this registration resource. The registration resource location 949 thus returned is for the purpose of updating the lifetime of the 950 registration and for maintaining the content of the registered 951 links, including updating and deleting links. A registration with 952 an already registered ep and d value pair responds with the same 953 success code and Location as the original registration; the set of 954 links registered with the endpoint is replaced with the links from 955 the payload. 957 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 958 request. 960 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 961 Service could not perform the operation. 963 HTTP support: YES 965 The following example shows an endpoint with the name "node1" 966 registering two resources to an RD using this interface. The 967 location "/rd" is an example RD location discovered in a request 968 similar to Figure 6. 970 Req: POST coap://rd.example.com/rd?ep=node1 971 Content-Format: 40 972 Payload: 973 ;ct=41;rt="temperature-c";if="sensor", 974 ;ct=41;rt="light-lux";if="sensor" 976 Res: 2.01 Created 977 Location: /rd/4521 979 A Resource Directory may optionally support HTTP. Here is an example 980 of almost the same registration operation above, when done using HTTP 981 and the JSON Link Format. 983 Req: POST /rd?ep=node1&con=http://[2001:db8:1::1] HTTP/1.1 984 Host : example.com 985 Content-Type: application/link-format+json 986 Payload: 987 [ 988 {"href": "/sensors/temp", "ct": "41", "rt": "temperature-c", "if": "sensor"}, 989 {"href": "/sensors/light", "ct": "41", "rt": "light-lux", "if": "sensor"} 990 ] 992 Res: 201 Created 993 Location: /rd/4521 994 5.3.1. Simple Registration 996 Not all endpoints hosting resources are expected to know how to 997 upload links to a RD as described in Section 5.3. Instead, simple 998 endpoints can implement the Simple Registration approach described in 999 this section. An RD implementing this specification MUST implement 1000 Simple Registration. However, there may be security reasons why this 1001 form of directory discovery would be disabled. 1003 This approach requires that the endpoint makes available the hosted 1004 resources that it wants to be discovered, as links on its "/.well- 1005 known/core" interface as specified in [RFC6690]. 1007 The endpoint then finds one or more addresses of the directory server 1008 as described in Section 4. 1010 An endpoint finally asks the directory server to probe it for 1011 resources and publish them as follows: 1013 It sends (and regularly refreshes with) a POST request to the 1014 "/.well-known/core" URI of the directory server of choice. The body 1015 of the POST request is empty, which triggers the resource directory 1016 server to perform GET requests at the requesting server's default 1017 discovery URI to obtain the link-format payload to register. 1019 The endpoint includes the same registration parameters in the POST 1020 request as it would per Section 5.3. The context of the registration 1021 is taken from the requesting server's URI. 1023 The endpoints MUST be deleted after the expiration of their lifetime. 1024 Additional operations cannot be executed because no registration 1025 location is returned. 1027 The following example shows an endpoint using Simple Registration, by 1028 simply sending an empty POST to a resource directory. 1030 Req:(to RD server from [2001:db8:2::1]) 1031 POST /.well-known/core?lt=6000&ep=node1 1032 Content-Format: 40 1033 No payload 1035 Res: 2.04 Changed 1037 (later) 1039 Req: (from RD server to [2001:db8:2::1]) 1040 GET /.well-known/core 1041 Accept: 40 1043 Res: 2.05 Content 1044 Payload: 1045 1047 5.3.2. Third-party registration 1049 For some applications, even Simple Registration may be too taxing for 1050 certain very constrained devices, in particular if the security 1051 requirements become too onerous. 1053 In a controlled environment (e.g. building control), the Resource 1054 Directory can be filled by a third device, called a commissioning 1055 tool. The commissioning tool can fill the Resource Directory from a 1056 database or other means. For that purpose the scheme, IP address and 1057 port of the registered device is indicated in the Context parameter 1058 of the registration described in Section 5.3. 1060 5.4. Operations on the Registration Resource 1062 After the initial registration, an endpoint should retain the 1063 returned location of the Registration Resource for further 1064 operations, including refreshing the registration in order to extend 1065 the lifetime and "keep-alive" the registration. When the lifetime of 1066 the registration has expired, the RD SHOULD NOT respond to discovery 1067 queries concerning this endpoint. The RD SHOULD continue to provide 1068 access to the Registration Resource after a registration time-out 1069 occurs in order to enable the registering endpoint to eventually 1070 refresh the registration. The RD MAY eventually remove the 1071 registration resource for the purpose of resource recovery and 1072 garbage collection. If the Registration Resource is removed, the 1073 endpoint will need to re-register. 1075 The Registration Resource may also be used to inspect the 1076 registration resource using GET, update the registration link 1077 contents, or cancel the registration using DELETE. 1079 These operations are described in this section. 1081 5.4.1. Registration Update 1083 The update interface is used by an endpoint to refresh or update its 1084 registration with an RD. To use the interface, the endpoint sends a 1085 POST request to the registration resource returned in the Location 1086 header option in the response returned from the initial registration 1087 operation. 1089 An update MAY update the lifetime- or the context- registration 1090 parameters "lt", "con" as in Section 5.3. Parameters that are not 1091 being changed SHOULD NOT be included in an update. Adding parameters 1092 that have not changed increases the size of the message but does not 1093 have any other implications. Parameters MUST be included as query 1094 parameters in an update operation as in Section 5.3. 1096 A registration update resets the timeout of the registration to the 1097 (possibly updated) lifetime of the registration, independent of 1098 whether a "lt" parameter was given. 1100 If the context of the registration is changed in an update explicitly 1101 or implicitly, relative references submitted in the original 1102 registration or later updates are resolved anew against the new 1103 context (like in the original registration). 1105 This operation only describes the use of POST with an empty payload. 1106 As with modification of individual using iPATCH or PATCH as proposed 1107 in Section 5.4.4, future standards might describe the semantics of 1108 using content formats and payloads with the POST method to update the 1109 links of a registration. 1111 The update registration request interface is specified as follows: 1113 Interaction: EP -> RD 1115 Method: POST 1117 URI Template: {+location}{?lt,con,extra-attrs*} 1119 URI Template Variables: 1121 location := This is the Location returned by the RD as a result 1122 of a successful earlier registration. 1124 lt := Lifetime (optional). Lifetime of the registration in 1125 seconds. Range of 60-4294967295. If no lifetime is included, 1126 the previous last lifetime set on a previous update or the 1127 original registration (falling back to 86400) SHOULD be used. 1129 con := Context (optional). This parameter updates the context 1130 established in the original registration to a new value. If 1131 the parameter is set in an update, it is stored by the RD as 1132 the new Base URI under which to interpret the links of the 1133 registration, following the same restrictions as in the 1134 registration. If the parameter is not set and was set 1135 explicitly before, the previous context value is kept 1136 unmodified. If the parameter is not set and was not set 1137 explicitly before either, the source address and source port of 1138 the update request are stored as the context. 1140 extra-attrs := Additional registration attributes (optional). As 1141 with the registration, the RD processes them if it knows their 1142 semantics. Otherwise, unknown attributes are stored as 1143 endpoint attributes, overriding any previously stored endpoint 1144 attributes of the same key. 1146 Content-Format: none (no payload) 1148 The following response codes are defined for this interface: 1150 Success: 2.04 "Changed" or 204 "No Content" if the update was 1151 successfully processed. 1153 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1154 request. 1156 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1157 exist (e.g. may have expired). 1159 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1160 Service could not perform the operation. 1162 HTTP support: YES 1164 The following example shows an endpoint updating its registration 1165 resource at an RD using this interface with the example location 1166 value: /rd/4521. 1168 Req: POST /rd/4521 1170 Res: 2.04 Changed 1172 The following example shows an endpoint updating its registration 1173 resource at an RD using this interface with the example location 1174 value: /rd/4521. The initial registration by the client set the 1175 following values: 1177 o endpoint name (ep)=endpoint1 1179 o lifetime (lt)=500 1181 o context (con)=coap://local-proxy-old.example.com:5683 1183 The initial state of the Resource Directory is reflected in the 1184 following request: 1186 Req: GET /rd-lookup/res?ep=endpoint1 1188 Res: 2.01 Content 1189 Payload: 1190 ;ct=41;rt="temperature";anchor="coap://local-proxy-old.example.com:5683", 1191 ;ct=41;rt="light-lux";if="sensor";anchor="coap://local-proxy-old.example.com:5683" 1193 The following example shows an EP changing the context to 1194 "coaps://new.example.com:5684": 1196 Req: POST /rd/4521?con=coaps://new.example.com:5684 1198 Res: 2.04 Changed 1200 The consecutive query returns: 1202 Req: GET /rd-lookup/res?ep=endpoint1 1204 Res: 2.01 Content 1205 Payload: 1206 ;ct=41;rt="temperature";anchor="coaps://new.example.com:5684", 1207 ;ct=41;rt="light-lux";if="sensor";anchor="coaps://new.example.com:5684", 1209 5.4.2. Registration Removal 1211 Although RD entries have soft state and will eventually timeout after 1212 their lifetime, an endpoint SHOULD explicitly remove its entry from 1213 the RD if it knows it will no longer be available (for example on 1214 shut-down). This is accomplished using a removal interface on the RD 1215 by performing a DELETE on the endpoint resource. 1217 Removed endpoints are implicitly removed from the groups to which 1218 they belong. 1220 The removal request interface is specified as follows: 1222 Interaction: EP -> RD 1224 Method: DELETE 1226 URI Template: {+location} 1228 URI Template Variables: 1230 location := This is the Location returned by the RD as a result 1231 of a successful earlier registration. 1233 The following responses codes are defined for this interface: 1235 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1237 Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed 1238 request. 1240 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1241 exist (e.g. may have expired). 1243 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1244 Service could not perform the operation. 1246 HTTP support: YES 1248 The following examples shows successful removal of the endpoint from 1249 the RD with example location value /rd/4521. 1251 Req: DELETE /rd/4521 1253 Res: 2.02 Deleted 1255 5.4.3. Read Endpoint Links 1257 Some endpoints may wish to manage their links as a collection, and 1258 may need to read the current set of links stored in the registration 1259 resource, in order to determine link maintenance operations. 1261 One or more links MAY be selected by using query filtering as 1262 specified in [RFC6690] Section 4.1 1264 If no links are selected, the Resource Directory SHOULD return an 1265 empty payload. 1267 The read request interface is specified as follows: 1269 Interaction: EP -> RD 1270 Method: GET 1272 URI Template: {+location}{?href,rel,rt,if,ct} 1274 URI Template Variables: 1276 location := This is the Location returned by the RD as a result 1277 of a successful earlier registration. 1279 href,rel,rt,if,ct := link relations and attributes specified in 1280 the query in order to select particular links based on their 1281 relations and attributes. "href" denotes the URI target of the 1282 link. See [RFC6690] Sec. 4.1 1284 The following responses codes are defined for this interface: 1286 Success: 2.05 "Content" or 200 "OK" upon success with an 1287 "application/link-format", "application/link-format+cbor", or 1288 "application/link-format+json" payload. 1290 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1291 request. 1293 Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not 1294 exist (e.g. may have expired). 1296 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1297 Service could not perform the operation. 1299 HTTP support: YES 1301 The following examples show successful read of the endpoint links 1302 from the RD, with example location value /rd/4521. 1304 Req: GET /rd/4521 1306 Res: 2.01 Content 1307 Payload: 1308 ;ct=41;rt="temperature-c";if="sensor", 1309 ;ct=41;rt="light-lux";if="sensor" 1311 5.4.4. Update Endpoint Links 1313 An iPATCH (or PATCH) update [RFC8132] adds, removes or changes links 1314 of a registration by including link update information in the payload 1315 of the update with a media type that still needs to be defined. 1317 6. RD Groups 1319 This section defines the REST API for the creation, management, and 1320 lookup of endpoints for group operations. Similar to endpoint 1321 registration entries in the RD, groups may be created or removed. 1322 However unlike an endpoint entry, a group entry consists of a list of 1323 endpoints and does not have a lifetime associated with it. In order 1324 to make use of multicast requests with CoAP, a group MAY have a 1325 multicast address associated with it. 1327 6.1. Register a Group 1329 In order to create a group, a commissioning tool (CT) used to 1330 configure groups, makes a request to the RD indicating the name of 1331 the group to create (or update), optionally the domain the group 1332 belongs to, and optionally the multicast address of the group. The 1333 registration message is a list of links to registration resources of 1334 the endpoints that belong to that group. 1336 The commissioning tool SHOULD not send any target attributes with the 1337 links to the registration resources, and the resource directory 1338 SHOULD ignore any attributes that are set. 1340 Configuration of the endpoints themselves is out of scope of this 1341 specification. Such an interface for managing the group membership 1342 of an endpoint has been defined in [RFC7390]. 1344 The registration request interface is specified as follows: 1346 Interaction: CT -> RD 1348 Method: POST 1350 URI Template: {+rd-group}{?gp,d,con} 1352 URI Template Variables: 1354 rd-group := RD Group URI (mandatory). This is the location of 1355 the RD Group REST API. 1357 gp := Group Name (mandatory). The name of the group to be 1358 created or replaced, unique within that domain. The maximum 1359 length of this parameter is 63 bytes. 1361 d := Domain (optional). The domain to which this group belongs. 1362 The maximum length of this parameter is 63 bytes. Optional. 1363 When this parameter is elided, the RD MAY associate the 1364 endpoint with a configured default domain. 1366 con := Context (optional). This parameter sets the scheme, 1367 address and port of the multicast address associated with the 1368 group. When con is used, scheme and host are mandatory and 1369 port parameter is optional. 1371 Content-Format: application/link-format 1373 Content-Format: application/link-format+json 1375 Content-Format: application/link-format+cbor 1377 The following response codes are defined for this interface: 1379 Success: 2.01 "Created" or 201 "Created". The Location header 1380 option MUST be returned in response to a successful group CREATE 1381 operation. This Location MUST be a stable identifier generated by 1382 the RD as it is used for delete operations of the group resource. 1384 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1385 request. 1387 Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not 1388 registered in the RD (e.g. may have expired). 1390 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1391 Service could not perform the operation. 1393 HTTP support: YES 1395 The following example shows an EP registering a group with the name 1396 "lights" which has two endpoints. The RD group path /rd-group is an 1397 example RD location discovered in a request similar to Figure 6. 1399 Req: POST coap://rd.example.com/rd-group?gp=lights 1400 &con=coap://[ff35:30:2001:db8::1] 1401 Content-Format: 40 1402 Payload: 1403 , 1404 1406 Res: 2.01 Created 1407 Location: /rd-group/12 1409 The href value is the path to the registration resource of the 1410 Endpoint. 1412 6.2. Group Removal 1414 A group can be removed simply by sending a removal message to the 1415 location of the group registration resource which was returned when 1416 initially registering the group. Removing a group MUST NOT remove 1417 the endpoints of the group from the RD. 1419 The removal request interface is specified as follows: 1421 Interaction: CT -> RD 1423 Method: DELETE 1425 URI Template: {+location} 1427 URI Template Variables: 1429 location := This is the path of the group resource returned by 1430 the RD as a result of a successful group registration. 1432 The following responses codes are defined for this interface: 1434 Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion 1436 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1437 request. 1439 Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. 1441 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1442 Service could not perform the operation. 1444 HTTP support: YES 1446 The following examples shows successful removal of the group from the 1447 RD with the example location value /rd-group/12. 1449 Req: DELETE /rd-group/12 1451 Res: 2.02 Deleted 1453 7. RD Lookup 1455 To discover the resources registered with the RD, a lookup interface 1456 must be provided. This lookup interface is defined as a default, and 1457 it is assumed that RDs may also support lookups to return resource 1458 descriptions in alternative formats (e.g. Atom or HTML Link) or 1459 using more advanced interfaces (e.g. supporting context or semantic 1460 based lookup). 1462 RD Lookup allows lookups for groups, endpoints and resources using 1463 attributes defined in this document and for use with the CoRE Link 1464 Format. The result of a lookup request is the list of links (if any) 1465 corresponding to the type of lookup. Thus, a group lookup MUST 1466 return a list of groups, an endpoint lookup MUST return a list of 1467 endpoints and a resource lookup MUST return a list of links to 1468 resources. 1470 The lookup type is selected by a URI endpoint, which is indicated by 1471 a Resource Type as per Table 1 below: 1473 +-------------+--------------------+-----------+ 1474 | Lookup Type | Resource Type | Mandatory | 1475 +-------------+--------------------+-----------+ 1476 | Resource | core.rd-lookup-res | Mandatory | 1477 | Endpoint | core.rd-lookup-ep | Mandatory | 1478 | Group | core.rd-lookup-gp | Optional | 1479 +-------------+--------------------+-----------+ 1481 Table 1: Lookup Types 1483 7.1. Resource lookup 1485 Resource lookup results in links that are semantically equivalent to 1486 the links submitted to the RD if they were accessed on the endpoint 1487 itself. The links and link parameters returned are equal to the 1488 submitted ones except for anchor, which was resolved by the server 1489 against the endpoint's context. 1491 Links that did not have an anchor attribute are therefore returned 1492 with the (explicitly or implicitly set) context URI of the 1493 registration as the anchor. Links whose anchor was submitted as an 1494 absolute URI are returned as they were registered. The hrefs of 1495 links can always be served as they were submitted; the server MAY 1496 return relative references in absolute form in to resource lookups, 1497 but that results in needlessly verbose responses. 1499 Above rules allow the client to interpret the response as links 1500 without any further knowledge of what the RD does. The Resource 1501 Directory MAY replace the contexts with a configured intermediate 1502 proxy, e.g. in the case of an HTTP lookup interface for CoAP 1503 endpoints. 1505 7.2. Endpoint and group lookup 1507 Endpoint and group lookups result in links to registration resources 1508 and group resources, respectively. Endpoint registration resources 1509 are annotated with their endpoint names (ep), domains (d, if 1510 present), context (con) and lifetime (lt, if present). Additional 1511 endpoint attributes are added as link attributes to their endpoint 1512 link unless their specification says otherwise. Group resources are 1513 annotated with their group names (gp), domain (d, if present) and 1514 multicast address (con, if present). 1516 While Endpoint Lookup does expose the registration resources, the RD 1517 does not need to make them accessible to clients. Clients SHOULD NOT 1518 attempt to dereference or manipulate them. 1520 7.3. Lookup filtering 1522 Using the Accept Option, the requester can control whether this list 1523 is returned in CoRE Link Format ("application/link-format", default) 1524 or its alternate content-formats ("application/link-format+json" or 1525 "application/link-format+cbor"). 1527 The page and count parameters are used to obtain lookup results in 1528 specified increments using pagination, where count specifies how many 1529 links to return and page specifies which subset of links organized in 1530 sequential pages, each containing 'count' links, starting with link 1531 zero and page zero. Thus, specifying count of 10 and page of 0 will 1532 return the first 10 links in the result set (links 0-9). Count = 10 1533 and page = 1 will return the next 'page' containing links 10-19, and 1534 so on. 1536 Multiple search criteria MAY be included in a lookup. All included 1537 criteria MUST match for a link to be returned. 1539 A link matches a search criterion if it has an attribute of the same 1540 name and the same value, allowing for a trailing "*" wildcard 1541 operator as in Section 4.1 of [RFC6690]. Attributes that are defined 1542 as "link-type" match if the search value matches any of their values 1543 (see Section 4.1 of [RFC6690]; eg. "?if=core.s" matches ";if="abc 1544 core.s";"). A link also matches a search criterion if the link that 1545 would be produced for any of its containing entities would match the 1546 criterion: A search criterion matches an endpoint if it matches the 1547 endpoint itself or any of the groups it is contained in, and one on a 1548 resource if it matches the resource, the resource's endpoint, or any 1549 of the endpoint's groups. 1551 Note that "href" is also a valid search criterion and matches target 1552 references. Like all search criteria, on a resource lookup it can 1553 match the target reference of the resource link itself, but also the 1554 registration resource of the endpoint that registered it, or any 1555 group resource that endpoint is contained in. 1557 Clients that are interested in a lookup result repeatedly or 1558 continuously can use mechanisms like ETag caching, resource 1559 observation ([RFC7641]), or any future mechanism that might allow 1560 more efficient observations of collections. These are advertised, 1561 detected and used according to their own specifications and can be 1562 used with the lookup interface as with any other resource. 1564 The lookup interface is specified as follows: 1566 Interaction: Client -> RD 1568 Method: GET 1570 URI Template: {+type-lookup-location}{?page,count,search*} 1572 URI Template Variables: 1574 type-lookup-location := RD Lookup URI for a given lookup type 1575 (mandatory). The address is discovered as described in 1576 Section 5.2. 1578 search := Search criteria for limiting the number of results 1579 (optional). 1581 page := Page (optional). Parameter can not be used without the 1582 count parameter. Results are returned from result set in pages 1583 that contain 'count' links starting from index (page * count). 1584 Page numbering starts with zero. 1586 count := Count (optional). Number of results is limited to this 1587 parameter value. If the page parameter is also present, the 1588 response MUST only include 'count' links starting with the 1589 (page * count) link in the result set from the query. If the 1590 count parameter is not present, then the response MUST return 1591 all matching links in the result set. Link numbering starts 1592 with zero. 1594 Content-Format: application/link-format (optional) 1596 Content-Format: application/link-format+json (optional) 1598 Content-Format: application/link-format+cbor (optional) 1600 The following responses codes are defined for this interface: 1602 Success: 2.05 "Content" or 200 "OK" with an "application/link- 1603 format", "application/link-format+cbor", or "application/link- 1604 format+json" payload containing matching entries for the lookup. 1605 The payload can contain zero links (which is an empty payload, 1606 "80" (hex) or "[]" in the respective content format), indicating 1607 that no entities matched the request. 1609 Failure: No error response to a multicast request. 1611 Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed 1612 request. 1614 Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". 1615 Service could not perform the operation. 1617 HTTP support: YES 1619 7.4. Lookup examples 1621 The examples in this section assume CoAP hosts with a default CoAP 1622 port 61616. HTTP hosts are possible and do not change the nature of 1623 the examples. 1625 The following example shows a client performing a resource lookup 1626 with the example resource look-up locations discovered in Figure 6: 1628 Req: GET /rd-lookup/res?rt=temperature 1630 Res: 2.05 Content 1631 ;rt="temperature";anchor="coap://[2001:db8:3::123]:61616" 1633 The same lookup using the CBOR Link Format media type: 1635 Req: GET /rd-lookup/res?rt=temperature 1636 Accept: TBD64 1638 Res: 2.05 Content 1639 Content-Format: TBD64 1640 Payload in Hex notation: 1641 81A301652F74656D70096B74656D706572617475726503781E636F61703A2F2F5B323030 1642 313A6462383A333A3A3132335D3A3631363136 1643 Decoded payload: 1644 [{1: "/temp", 9: "temperature", 3: "coap://[2001:db8:3::123]:61616"}] 1646 A client that wants to be notified of new resources as they show up 1647 can use observation: 1649 Req: GET /rd-lookup/res?rt=light 1650 Observe: 0 1652 Res: 2.05 Content 1653 Observe: 23 1654 Payload: empty 1656 (at a later point in time) 1658 Res: 2.05 Content 1659 Observe: 24 1660 Payload: 1661 ;rt="light";anchor="coap://[2001:db8:3::124]", 1662 ;rt="light";anchor="coap://[2001:db8:3::124]", 1663 ;rt="light";anchor="coap://[2001:db8:3::124]" 1665 The following example shows a client performing an endpoint type 1666 lookup: 1668 Req: GET /rd-lookup/ep?et=power-node 1670 Res: 2.05 Content 1671 ;con="coap://[2001:db8:3::127]:61616";ep="node5"; 1672 et="power-node";ct="40";lt="600", 1673 ;con="coap://[2001:db8:3::129]:61616";ep="node7"; 1674 et="power-node";ct="40";lt="600";d="floor-3" 1676 The following example shows a client performing a group lookup for 1677 all groups: 1679 Req: GET /rd-lookup/gp 1681 Res: 2.05 Content 1682 ;gp="lights1";d="example.com";con="coap://[ff35:30:2001:db8::1]", 1683 ;gp="lights2";d="example.com";con="coap://[ff35:30:2001:db8::2]" 1685 The following example shows a client performing a lookup for all 1686 endpoints in a particular group: 1688 Req: GET /rd-lookup/ep?gp=lights1 1690 Res: 2.05 Content 1691 ;con="coap://[2001:db8:3::123]:61616";ep="node1";et="power-node";ct="40";lt="600", 1692 ;con="coap://[2001:db8:3::124]:61616";ep="node2";et="power-node";ct="40";lt="600" 1694 The following example shows a client performing a lookup for all 1695 groups the endpoint "node1" belongs to: 1697 Req: GET /rd-lookup/gp?ep=node1 1699 Res: 2.05 Content 1700 ;gp="lights1" 1702 The following example shows a client performing a paginated resource 1703 lookup 1705 Req: GET /rd-lookup/res?page=0&count=5 1707 Res: 2.05 Content 1708 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1709 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1710 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1711 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1712 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616" 1714 Req: GET /rd-lookup/res?page=1&count=5 1716 Res: 2.05 Content 1717 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1718 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1719 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1720 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616", 1721 ;rt=sensor;ct=60;anchor="coap://[2001:db8:3::123]:61616" 1723 The following example shows a client performing a lookup of all 1724 resources from endpoints of a given endpoint type. It assumes that 1725 two endpoints (with endpoint names "sensor1" and "sensor2") have 1726 previously registered with their respective addresses 1727 "coap://sensor1.example.com" and "coap://sensor2.example.com", and 1728 posted the very payload of the 6th request of section 5 of [RFC6690]. 1730 It demonstrates how the link targets stay unmodified, but the anchors 1731 get constructed by the resource directory: 1733 Req: GET /rd-lookup/res?et=sensor-node 1735 ;ct=40;title="Sensor Index"; 1736 anchor="coap://sensor1.example.com", 1737 ;rt="temperature-c";if="sensor"; 1738 anchor="coap://sensor1.example.com", 1739 ;rt="light-lux";if="sensor"; 1740 anchor="coap://sensor1.example.com", 1741 ;rel="describedby"; 1742 anchor="coap://sensor1.example.com/sensors/temp", 1743 ;rel="alternate";anchor="coap://sensor1.example.com/sensors/temp", 1744 ;ct=40;title="Sensor Index"; 1745 anchor="coap://sensor2.example.com", 1746 ;rt="temperature-c";if="sensor"; 1747 anchor="coap://sensor2.example.com", 1748 ;rt="light-lux";if="sensor"; 1749 anchor="coap://sensor2.example.com", 1750 ;rel="describedby"; 1751 ;anchor="coap://sensor2.example.com/sensors/temp", 1752 ;rel="alternate";anchor="coap://sensor2.example.com/sensors/temp" 1754 8. Security Considerations 1756 The security considerations as described in Section 7 of [RFC5988] 1757 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1758 may be protected e.g. using DTLS when hosted on a CoAP server as 1759 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1760 all resource directory interfaces defined in this document. 1762 8.1. Endpoint Identification and Authentication 1764 An Endpoint is determined to be unique within (the domain of) an RD 1765 by the Endpoint identifier parameter included during Registration, 1766 and any associated TLS or DTLS security bindings. An Endpoint MUST 1767 NOT be identified by its protocol, port or IP address as these may 1768 change over the lifetime of an Endpoint. 1770 Every operation performed by an Endpoint or Client on a resource 1771 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1772 Public Key or Certificate based security. 1774 Consider te following threat: two devices A and B are managed by a 1775 single server. Both devices have unique, per-device credentials for 1776 use with DTLS to make sure that only parties with authorization to 1777 access A or B can do so. 1779 Now, imagine that a malicious device A wants to sabotage the device 1780 B. It uses its credentials during the TLS exchange. Then, it puts 1781 the endpoint name of device B. If the server does not check whether 1782 the identifier provided in the DTLS handshake matches the identifier 1783 used at the CoAP layer then it may be inclined to use the endpoint 1784 name for looking up what information to provision to the malicious 1785 device. 1787 Therfore, Endpoints MUST include the Endpoint identifier in the 1788 message, and this identifier MUST be checked by a resource directory 1789 to match the Endpoint identifier included in the Registration 1790 message. 1792 8.2. Access Control 1794 Access control SHOULD be performed separately for the RD 1795 registration, Lookup, and group API paths, as different endpoints may 1796 be authorized to register with an RD from those authorized to lookup 1797 endpoints from the RD. Such access control SHOULD be performed in as 1798 fine-grained a level as possible. For example access control for 1799 lookups could be performed either at the domain, endpoint or resource 1800 level. 1802 8.3. Denial of Service Attacks 1804 Services that run over UDP unprotected are vulnerable to unknowingly 1805 become part of a DDoS attack as UDP does not require return 1806 routability check. Therefore, an attacker can easily spoof the 1807 source IP of the target entity and send requests to such a service 1808 which would then respond to the target entity. This can be used for 1809 large-scale DDoS attacks on the target. Especially, if the service 1810 returns a response that is order of magnitudes larger than the 1811 request, the situation becomes even worse as now the attack can be 1812 amplified. DNS servers have been widely used for DDoS amplification 1813 attacks. There is also a danger that NTP Servers could become 1814 implicated in denial-of-service (DoS) attacks since they run on 1815 unprotected UDP, there is no return routability check, and they can 1816 have a large amplification factor. The responses from the NTP server 1817 were found to be 19 times larger than the request. A Resource 1818 Directory (RD) which responds to wild-card lookups is potentially 1819 vulnerable if run with CoAP over UDP. Since there is no return 1820 routability check and the responses can be significantly larger than 1821 requests, RDs can unknowingly become part of a DDoS amplification 1822 attack. 1824 9. IANA Considerations 1825 9.1. Resource Types 1827 "core.rd", "core.rd-group", "core.rd-lookup-ep", "core.rd-lookup- 1828 res", and "core.rd-lookup-gp" resource types need to be registered 1829 with the resource type registry defined by [RFC6690]. 1831 9.2. IPv6 ND Resource Directory Address Option 1833 This document registers one new ND option type under the subregistry 1834 "IPv6 Neighbor Discovery Option Formats": 1836 o Resource Directory address Option (38) 1838 9.3. RD Parameter Registry 1840 This specification defines a new sub-registry for registration and 1841 lookup parameters called "RD Parameters" under "CoRE Parameters". 1842 Although this specification defines a basic set of parameters, it is 1843 expected that other standards that make use of this interface will 1844 define new ones. 1846 Each entry in the registry must include * the human readable name of 1847 the parameter, * the short name as used in query parameters or link 1848 attributes, * indication of whether it can be passed as a query 1849 parameter at registration of endpoints or groups, as a query 1850 parameter in lookups, or be expressed as a link attribute, * validity 1851 requirements if any, and * a description. 1853 The query parameter MUST be both a valid URI query key [RFC3986] and 1854 a parmname as used in [RFC5988]. 1856 The description must give details on which registrations they apply 1857 to (Endpoint, group registrations or both? Can they be updated?), 1858 and how they are to be processed in lookups. 1860 The mechanisms around new RD parameters should be designed in such a 1861 way that they tolerate RD implementations that are unaware of the 1862 parameter and expose any parameter passed at registration or updates 1863 on in endpoint lookups. (For example, if a parameter used at 1864 registration were to be confidential, the registering endpoint should 1865 be instructed to only set that parameter if the RD advertises support 1866 for keeping it confidential at the discovery step.) 1868 Initial entries in this sub-registry are as follows: 1870 +----------+-------+---------------+-----+--------------------------+ 1871 | Full | Short | Validity | Use | Description | 1872 | name | | | | | 1873 +----------+-------+---------------+-----+--------------------------+ 1874 | Endpoint | ep | | RLA | Name of the endpoint, | 1875 | Name | | | | max 63 bytes | 1876 | Lifetime | lt | 60-4294967295 | RLA | Lifetime of the | 1877 | | | | | registration in seconds | 1878 | Domain | d | | RLA | Domain to which this | 1879 | | | | | endpoint belongs | 1880 | Context | con | URI | RLA | The scheme, address and | 1881 | | | | | port and path at which | 1882 | | | | | this server is available | 1883 | Group | gp | | RLA | Name of a group in the | 1884 | Name | | | | RD | 1885 | Page | page | Integer | L | Used for pagination | 1886 | Count | count | Integer | L | Used for pagination | 1887 | Endpoint | et | | RLA | Semantic name of the | 1888 | Type | | | | endpoint (see Section | 1889 | | | | | 9.4) | 1890 +----------+-------+---------------+-----+--------------------------+ 1892 Table 2: RD Parameters 1894 (Short: Short name used in query parameters or link attributes. Use: 1895 R = used at registration, L = used at lookup, A = expressed in link 1896 attribute 1898 The descriptions for the options defined in this document are only 1899 summarized here. To which registrations they apply and when they are 1900 to be shown is described in the respective sections of this document. 1902 The IANA policy for future additions to the sub-registry is "Expert 1903 Review" as described in [RFC8126]. The evaluation should consider 1904 formal criteria, duplication of functionality (Is the new entry 1905 redundant with an existing one?), topical suitability (Eg. is the 1906 described property actually a property of the endpoint and not a 1907 property of a particular resource, in which case it should go into 1908 the payload of the registration and need not be registered?), and the 1909 potential for conflict with commonly used link attributes (For 1910 example, "if" could be used as a parameter for conditional 1911 registration if it were not to be used in lookup or attributes, but 1912 would make a bad parameter for lookup, because a resource lookup with 1913 an "if" query parameter could ambiguously filter by the registered 1914 endpoint property or the [RFC6690] link attribute). It is expected 1915 that the registry will receive between 5 and 50 registrations in 1916 total over the next years. 1918 9.3.1. Full description of the "Endpoint Type" Registration Parameter 1920 An endpoint registering at an RD can describe itself with endpoint 1921 types, similar to how resources are described with Resource Types in 1922 [RFC6690]. An endpoint type is expressed as a string, which can be 1923 either a URI or one of the values defined in the Endpoint Type 1924 subregistry. Endpoint types can be passed in the "et" query 1925 parameter as part of extra-attrs at the Registration step, are shown 1926 on endpoint lookups using the "et" target attribute, and can be 1927 filtered for using "et" as a search criterion in resource and 1928 endpoint lookup. Multiple endpoint types are given as separate query 1929 parameters or link attributes. 1931 Note that Endpoint Type differs from Resource Type in that it uses 1932 multiple attributes rather than space separated values. As a result, 1933 Resource Directory implementations automatically support correct 1934 filtering in the lookup interfaces from the rules for unknown 1935 endpoint attributes. 1937 9.4. "Endpoint Type" (et=) RD Parameter values 1939 This specification establishes a new sub-registry under "CoRE 1940 Parameters" called '"Endpoint Type" (et=) RD Parameter values'. The 1941 registry properties (required policy, requirements, template) are 1942 identical to those of the Resource Type parameters in [RFC6690], in 1943 short: 1945 The review policy is IETF Review for values starting with "core", and 1946 Specification Required for others. 1948 The requirements to be enforced are: 1950 o The values MUST be related to the purpose described in 1951 Section 9.3.1. 1953 o The registered values MUST conform to the ABNF reg-rel-type 1954 definition of [RFC6690] and MUST NOT be a URI. 1956 o It is recommended to use the period "." character for 1957 segmentation. 1959 The registry is initially empty. 1961 10. Examples 1963 Two examples are presented: a Lighting Installation example in 1964 Section 10.1 and a LWM2M example in Section 10.2. 1966 10.1. Lighting Installation 1968 This example shows a simplified lighting installation which makes use 1969 of the Resource Directory (RD) with a CoAP interface to facilitate 1970 the installation and start up of the application code in the lights 1971 and sensors. In particular, the example leads to the definition of a 1972 group and the enabling of the corresponding multicast address. No 1973 conclusions must be drawn on the realization of actual installation 1974 or naming procedures, because the example only "emphasizes" some of 1975 the issues that may influence the use of the RD and does not pretend 1976 to be normative. 1978 10.1.1. Installation Characteristics 1980 The example assumes that the installation is managed. That means 1981 that a Commissioning Tool (CT) is used to authorize the addition of 1982 nodes, name them, and name their services. The CT can be connected 1983 to the installation in many ways: the CT can be part of the 1984 installation network, connected by WiFi to the installation network, 1985 or connected via GPRS link, or other method. 1987 It is assumed that there are two naming authorities for the 1988 installation: (1) the network manager that is responsible for the 1989 correct operation of the network and the connected interfaces, and 1990 (2) the lighting manager that is responsible for the correct 1991 functioning of networked lights and sensors. The result is the 1992 existence of two naming schemes coming from the two managing 1993 entities. 1995 The example installation consists of one presence sensor, and two 1996 luminaries, luminary1 and luminary2, each with their own wireless 1997 interface. Each luminary contains three lamps: left, right and 1998 middle. Each luminary is accessible through one endpoint. For each 1999 lamp a resource exists to modify the settings of a lamp in a 2000 luminary. The purpose of the installation is that the presence 2001 sensor notifies the presence of persons to a group of lamps. The 2002 group of lamps consists of: middle and left lamps of luminary1 and 2003 right lamp of luminary2. 2005 Before commissioning by the lighting manager, the network is 2006 installed and access to the interfaces is proven to work by the 2007 network manager. 2009 At the moment of installation, the network under installation is not 2010 necessarily connected to the DNS infra structure. Therefore, SLAAC 2011 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 2012 Table 3 below: 2014 +--------------------+----------------+ 2015 | Name | IPv6 address | 2016 +--------------------+----------------+ 2017 | luminary1 | 2001:db8:4::1 | 2018 | luminary2 | 2001:db8:4::2 | 2019 | Presence sensor | 2001:db8:4::3 | 2020 | Resource directory | 2001:db8:4::ff | 2021 +--------------------+----------------+ 2023 Table 3: interface SLAAC addresses 2025 In Section 10.1.2 the use of resource directory during installation 2026 is presented. 2028 10.1.2. RD entries 2030 It is assumed that access to the DNS infrastructure is not always 2031 possible during installation. Therefore, the SLAAC addresses are 2032 used in this section. 2034 For discovery, the resource types (rt) of the devices are important. 2035 The lamps in the luminaries have rt: light, and the presence sensor 2036 has rt: p-sensor. The endpoints have names which are relevant to the 2037 light installation manager. In this case luminary1, luminary2, and 2038 the presence sensor are located in room 2-4-015, where luminary1 is 2039 located at the window and luminary2 and the presence sensor are 2040 located at the door. The endpoint names reflect this physical 2041 location. The middle, left and right lamps are accessed via path 2042 /light/middle, /light/left, and /light/right respectively. The 2043 identifiers relevant to the Resource Directory are shown in Table 4 2044 below: 2046 +----------------+------------------+---------------+---------------+ 2047 | Name | endpoint | resource path | resource type | 2048 +----------------+------------------+---------------+---------------+ 2049 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 2050 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 2051 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 2052 | luminary2 | lm_R2-4-015_door | /light/left | light | 2053 | luminary2 | lm_R2-4-015_door | /light/middle | light | 2054 | luminary2 | lm_R2-4-015_door | /light/right | light | 2055 | Presence | ps_R2-4-015_door | /ps | p-sensor | 2056 | sensor | | | | 2057 +----------------+------------------+---------------+---------------+ 2059 Table 4: Resource Directory identifiers 2061 It is assumed that the CT knows of the RD's address, and has 2062 performed URI discovery on it that gave a response like the one in 2063 the Section 5.2 example. 2065 The CT inserts the endpoints of the luminaries and the sensor in the 2066 RD using the Context parameter (con) to specify the interface 2067 address: 2069 Req: POST coap://[2001:db8:4::ff]/rd 2070 ?ep=lm_R2-4-015_wndw&con=coap://[2001:db8:4::1]&d=R2-4-015 2071 Payload: 2072 ;rt="light", 2073 ;rt="light", 2074 ;rt="light" 2076 Res: 2.01 Created 2077 Location: /rd/4521 2079 Req: POST coap://[2001:db8:4::ff]/rd 2080 ?ep=lm_R2-4-015_door&con=coap://[2001:db8:4::2]&d=R2-4-015 2081 Payload: 2082 ;rt="light", 2083 ;rt="light", 2084 ;rt="light" 2086 Res: 2.01 Created 2087 Location: /rd/4522 2089 Req: POST coap://[2001:db8:4::ff]/rd 2090 ?ep=ps_R2-4-015_door&con=coap://[2001:db8:4::3]d&d=R2-4-015 2091 Payload: 2092 ;rt="p-sensor" 2094 Res: 2.01 Created 2095 Location: /rd/4523 2097 The domain name d=R2-4-015 has been added for an efficient lookup 2098 because filtering on "ep" name is more awkward. The same domain name 2099 is communicated to the two luminaries and the presence sensor by the 2100 CT. 2102 The group is specified in the RD. The Context parameter is set to 2103 the site-local multicast address allocated to the group. In the POST 2104 in the example below, these two endpoints and the endpoint of the 2105 presence sensor are registered as members of the group. 2107 Req: POST coap://[2001:db8:4::ff]/rd-group 2108 ?gp=grp_R2-4-015&con=coap://[ff05::1] 2109 Payload: 2110 , 2111 , 2112 2114 Res: 2.01 Created 2115 Location: /rd-group/501 2117 After the filling of the RD by the CT, the application in the 2118 luminaries can learn to which groups they belong, and enable their 2119 interface for the multicast address. 2121 The luminary, knowing its domain, queries the RD for the endpoint 2122 with rt=light and d=R2-4-015. The RD returns all endpoints in the 2123 domain. 2125 Req: GET coap://[2001:db8:4::ff]/rd-lookup/ep 2126 ?d=R2-4-015;rt=light 2128 Res: 2.05 Content 2129 ;con="coap://[2001:db8:4::1]", 2130 ep="lm_R2-4-015_wndw", 2131 ;con="coap://[2001:db8:4::2]", 2132 ep="lm_R2-4-015_door" 2134 Knowing its own IPv6 address, the luminary discovers its endpoint 2135 name. With the endpoint name the luminary queries the RD for all 2136 groups to which the endpoint belongs. 2138 Req: GET coap://[2001:db8:4::ff]/rd-lookup/gp 2139 ?ep=lm_R2-4-015_wndw 2141 Res: 2.05 Content 2142 ;gp="grp_R2-4-015";con="coap://[ff05::1]" 2144 From the context parameter value, the luminary learns the multicast 2145 address of the multicast group. 2147 Alternatively, the CT can communicate the multicast address directly 2148 to the luminaries by using the "coap-group" resource specified in 2149 [RFC7390]. 2151 Req: POST //[2001:db8:4::1]/coap-group 2152 Content-Format: application/coap-group+json 2153 { "a": "[ff05::1]", 2154 "n": "grp_R2-4-015"} 2156 Res: 2.01 Created 2157 Location-Path: /coap-group/1 2159 Dependent on the situation, only the address, "a", or the name, "n", 2160 is specified in the coap-group resource. 2162 10.2. OMA Lightweight M2M (LWM2M) Example 2164 This example shows how the OMA LWM2M specification makes use of 2165 Resource Directory (RD). 2167 OMA LWM2M is a profile for device services based on CoAP(OMA Name 2168 Authority). LWM2M defines a simple object model and a number of 2169 abstract interfaces and operations for device management and device 2170 service enablement. 2172 An LWM2M server is an instance of an LWM2M middleware service layer, 2173 containing a Resource Directory along with other LWM2M interfaces 2174 defined by the LWM2M specification. 2176 CoRE Resource Directory (RD) is used to provide the LWM2M 2177 Registration interface. 2179 LWM2M does not provide for registration domains and does not 2180 currently use the rd-group or rd-lookup interfaces. 2182 The LWM2M specification describes a set of interfaces and a resource 2183 model used between a LWM2M device and an LWM2M server. Other 2184 interfaces, proxies, and applications are currently out of scope for 2185 LWM2M. 2187 The location of the LWM2M Server and RD URI path is provided by the 2188 LWM2M Bootstrap process, so no dynamic discovery of the RD is used. 2189 LWM2M Servers and endpoints are not required to implement the /.well- 2190 known/core resource. 2192 10.2.1. The LWM2M Object Model 2194 The OMA LWM2M object model is based on a simple 2 level class 2195 hierarchy consisting of Objects and Resources. 2197 An LWM2M Resource is a REST endpoint, allowed to be a single value or 2198 an array of values of the same data type. 2200 An LWM2M Object is a resource template and container type that 2201 encapsulates a set of related resources. An LWM2M Object represents 2202 a specific type of information source; for example, there is a LWM2M 2203 Device Management object that represents a network connection, 2204 containing resources that represent individual properties like radio 2205 signal strength. 2207 Since there may potentially be more than one of a given type object, 2208 for example more than one network connection, LWM2M defines instances 2209 of objects that contain the resources that represent a specific 2210 physical thing. 2212 The URI template for LWM2M consists of a base URI followed by Object, 2213 Instance, and Resource IDs: 2215 {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- 2216 instance} 2218 The five variables given here are strings. base-uri can also have 2219 the special value "undefined" (sometimes called "null" in RFC 6570). 2220 Each of the variables object-instance, resource-id, and resource- 2221 instance can be the special value "undefined" only if the values 2222 behind it in this sequence also are "undefined". As a special case, 2223 object-instance can be "empty" (which is different from "undefined") 2224 if resource-id is not "undefined". 2226 base-uri := Base URI for LWM2M resources or "undefined" for default 2227 (empty) base URI 2229 object-id := OMNA (OMA Name Authority) registered object ID (0-65535) 2231 object-instance := Object instance identifier (0-65535) or 2232 "undefined"/"empty" (see above)) to refer to all instances of an 2233 object ID 2235 resource-id := OMNA (OMA Name Authority) registered resource ID 2236 (0-65535) or "undefined" to refer to all resources within an instance 2238 resource-instance := Resource instance identifier or "undefined" to 2239 refer to single instance of a resource 2241 LWM2M IDs are 16 bit unsigned integers represented in decimal (no 2242 leading zeroes except for the value 0) by URI format strings. For 2243 example, a LWM2M URI might be: 2245 /1/0/1 2246 The base uri is empty, the Object ID is 1, the instance ID is 0, the 2247 resource ID is 1, and the resource instance is "undefined". This 2248 example URI points to internal resource 1, which represents the 2249 registration lifetime configured, in instance 0 of a type 1 object 2250 (LWM2M Server Object). 2252 10.2.2. LWM2M Register Endpoint 2254 LWM2M defines a registration interface based on the REST API, 2255 described in Section 5. The RD registration URI path of the LWM2M 2256 Resource Directory is specified to be "/rd". 2258 LWM2M endpoints register object IDs, for example , to indicate 2259 that a particular object type is supported, and register object 2260 instances, for example , to indicate that a particular instance 2261 of that object type exists. 2263 Resources within the LWM2M object instance are not registered with 2264 the RD, but may be discovered by reading the resource links from the 2265 object instance using GET with a CoAP Content-Format of application/ 2266 link-format. Resources may also be read as a structured object by 2267 performing a GET to the object instance with a Content-Format of 2268 senml+json. 2270 When an LWM2M object or instance is registered, this indicates to the 2271 LWM2M server that the object and its resources are available for 2272 management and service enablement (REST API) operations. 2274 LWM2M endpoints may use the following RD registration parameters as 2275 defined in Table 2 : 2277 ep - Endpoint Name 2278 lt - registration lifetime 2280 Endpoint Name, Lifetime, and LWM2M Version are mandatory parameters 2281 for the register operation, all other registration parameters are 2282 optional. 2284 Additional optional LWM2M registration parameters are defined: 2286 +-----------+-------+-------------------------------+---------------+ 2287 | Name | Query | Validity | Description | 2288 +-----------+-------+-------------------------------+---------------+ 2289 | Binding | b | {"U",UQ","S","SQ","US","UQS"} | Available | 2290 | Mode | | | Protocols | 2291 | | | | | 2292 | LWM2M | ver | 1.0 | Spec Version | 2293 | Version | | | | 2294 | | | | | 2295 | SMS | sms | | MSISDN | 2296 | Number | | | | 2297 +-----------+-------+-------------------------------+---------------+ 2299 Table 5: LWM2M Additional Registration Parameters 2301 The following RD registration parameters are not currently specified 2302 for use in LWM2M: 2304 et - Endpoint Type 2305 con - Context 2307 The endpoint registration must include a payload containing links to 2308 all supported objects and existing object instances, optionally 2309 including the appropriate link-format relations. 2311 Here is an example LWM2M registration payload: 2313 ,,, 2315 This link format payload indicates that object ID 1 (LWM2M Server 2316 Object) is supported, with a single instance 0 existing, object ID 3 2317 (LWM2M Device object) is supported, with a single instance 0 2318 existing, and object 5 (LWM2M Firmware Object) is supported, with no 2319 existing instances. 2321 10.2.3. LWM2M Update Endpoint Registration 2323 The LwM2M update is really very similar to the registration update as 2324 described in Section 5.4.1, with the only difference that there are 2325 more parameters defined and available. All the parameters listed in 2326 that section are also available with the initial registration but are 2327 all optional: 2329 lt - Registration Lifetime 2330 b - Protocol Binding 2331 sms - MSISDN 2332 link payload - new or modified links 2333 A Registration update is also specified to be used to update the 2334 LWM2M server whenever the endpoint's UDP port or IP address are 2335 changed. 2337 10.2.4. LWM2M De-Register Endpoint 2339 LWM2M allows for de-registration using the delete method on the 2340 returned location from the initial registration operation. LWM2M de- 2341 registration proceeds as described in Section 5.4.2. 2343 11. Acknowledgments 2345 Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders 2346 Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, 2347 Hannes Tschofenig, Sampo Ukkola, Linyi Tian, and Jan Newmarch have 2348 provided helpful comments, discussions and ideas to improve and shape 2349 this document. Zach would also like to thank his colleagues from the 2350 EU FP7 SENSEI project, where many of the resource directory concepts 2351 were originally developed. 2353 12. Changelog 2355 changes from -11 to -12 2357 o added Content Model section, including ER diagram 2359 o removed domain lookup interface; domains are now plain attributes 2360 of groups and endpoints 2362 o updated chapter "Finding a Resource Directory"; now distinguishes 2363 configuration-provided, network-provided and heuristic sources 2365 o improved text on: atomicity, idempotency, lookup with multiple 2366 parameters, endpoint removal, simple registration 2368 o updated LWM2M description 2370 o clarified where relative references are resolved, and how context 2371 and anchor interact 2373 o new appendix on the interaction with RFCs 6690, 5988 and 3986 2375 o lookup interface: group and endpoint lookup return group and 2376 registration resources as link targets 2378 o lookup interface: search parameters work the same across all 2379 entities 2381 o removed all methods that modify links in an existing registration 2382 (POST with payload, PATCH and iPATCH) 2384 o removed plurality definition (was only needed for link 2385 modification) 2387 o enhanced IANA registry text 2389 o More examples and improved text 2391 changes from -09 to -10 2393 o removed "ins" and "exp" link-format extensions. 2395 o removed all text concerning DNS-SD. 2397 o removed inconsistency in RDAO text. 2399 o suggestions taken over from various sources 2401 o replaced "Function Set" with "REST API", "base URI", "base path" 2403 o moved simple registration to registration section 2405 changes from -08 to -09 2407 o clarified the "example use" of the base RD resource values /rd, 2408 /rd-lookup, and /rd-group. 2410 o changed "ins" ABNF notation. 2412 o various editorial improvements, including in examples 2414 o clarifications for RDAO 2416 changes from -07 to -08 2418 o removed link target value returned from domain and group lookup 2419 types 2421 o Maximum length of domain parameter 63 bytes for consistency with 2422 group 2424 o removed option for simple POST of link data, don't require a 2425 .well-known/core resource to accept POST data and handle it in a 2426 special way; we already have /rd for that 2428 o add IPv6 ND Option for discovery of an RD 2429 o clarify group configuration section 6.1 that endpoints must be 2430 registered before including them in a group 2432 o removed all superfluous client-server diagrams 2434 o simplified lighting example 2436 o introduced Commissioning Tool 2438 o RD-Look-up text is extended. 2440 changes from -06 to -07 2442 o added text in the discovery section to allow content format hints 2443 to be exposed in the discovery link attributes 2445 o editorial updates to section 9 2447 o update author information 2449 o minor text corrections 2451 Changes from -05 to -06 2453 o added note that the PATCH section is contingent on the progress of 2454 the PATCH method 2456 changes from -04 to -05 2458 o added Update Endpoint Links using PATCH 2460 o http access made explicit in interface specification 2462 o Added http examples 2464 Changes from -03 to -04: 2466 o Added http response codes 2468 o Clarified endpoint name usage 2470 o Add application/link-format+cbor content-format 2472 Changes from -02 to -03: 2474 o Added an example for lighting and DNS integration 2476 o Added an example for RD use in OMA LWM2M 2477 o Added Read Links operation for link inspection by endpoints 2479 o Expanded DNS-SD section 2481 o Added draft authors Peter van der Stok and Michael Koster 2483 Changes from -01 to -02: 2485 o Added a catalogue use case. 2487 o Changed the registration update to a POST with optional link 2488 format payload. Removed the endpoint type update from the update. 2490 o Additional examples section added for more complex use cases. 2492 o New DNS-SD mapping section. 2494 o Added text on endpoint identification and authentication. 2496 o Error code 4.04 added to Registration Update and Delete requests. 2498 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 2499 resource type parameters. 2501 Changes from -00 to -01: 2503 o Removed the ETag validation feature. 2505 o Place holder for the DNS-SD mapping section. 2507 o Explicitly disabled GET or POST on returned Location. 2509 o New registry for RD parameters. 2511 o Added support for the JSON Link Format. 2513 o Added reference to the Groupcomm WG draft. 2515 Changes from -05 to WG Document -00: 2517 o Updated the version and date. 2519 Changes from -04 to -05: 2521 o Restricted Update to parameter updates. 2523 o Added pagination support for the Lookup interface. 2525 o Minor editing, bug fixes and reference updates. 2527 o Added group support. 2529 o Changed rt to et for the registration and update interface. 2531 Changes from -03 to -04: 2533 o Added the ins= parameter back for the DNS-SD mapping. 2535 o Integrated the Simple Directory Discovery from Carsten. 2537 o Editorial improvements. 2539 o Fixed the use of ETags. 2541 o Fixed tickets 383 and 372 2543 Changes from -02 to -03: 2545 o Changed the endpoint name back to a single registration parameter 2546 ep= and removed the h= and ins= parameters. 2548 o Updated REST interface descriptions to use RFC6570 URI Template 2549 format. 2551 o Introduced an improved RD Lookup design as its own function set. 2553 o Improved the security considerations section. 2555 o Made the POST registration interface idempotent by requiring the 2556 ep= parameter to be present. 2558 Changes from -01 to -02: 2560 o Added a terminology section. 2562 o Changed the inclusion of an ETag in registration or update to a 2563 MAY. 2565 o Added the concept of an RD Domain and a registration parameter for 2566 it. 2568 o Recommended the Location returned from a registration to be 2569 stable, allowing for endpoint and Domain information to be changed 2570 during updates. 2572 o Changed the lookup interface to accept endpoint and Domain as 2573 query string parameters to control the scope of a lookup. 2575 13. References 2577 13.1. Normative References 2579 [I-D.ietf-core-links-json] 2580 Li, K., Rahman, A., and C. Bormann, "Representing 2581 Constrained RESTful Environments (CoRE) Link Format in 2582 JSON and CBOR", draft-ietf-core-links-json-09 (work in 2583 progress), July 2017. 2585 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2586 Requirement Levels", BCP 14, RFC 2119, 2587 DOI 10.17487/RFC2119, March 1997, . 2590 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2591 Resource Identifier (URI): Generic Syntax", STD 66, 2592 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2593 . 2595 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2596 DOI 10.17487/RFC5988, October 2010, . 2599 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2600 and D. Orchard, "URI Template", RFC 6570, 2601 DOI 10.17487/RFC6570, March 2012, . 2604 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2605 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2606 . 2608 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2609 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2610 . 2612 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2613 Writing an IANA Considerations Section in RFCs", BCP 26, 2614 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2615 . 2617 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2618 FETCH Methods for the Constrained Application Protocol 2619 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2620 . 2622 13.2. Informative References 2624 [ER] Chen, P., "The entity-relationship model---toward a 2625 unified view of data", ACM Transactions on Database 2626 Systems Vol. 1, pp. 9-36, DOI 10.1145/320434.320440, March 2627 1976. 2629 [I-D.arkko-core-dev-urn] 2630 Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 2631 Names for Device Identifiers", draft-arkko-core-dev-urn-04 2632 (work in progress), July 2017. 2634 [I-D.nottingham-rfc5988bis] 2635 Nottingham, M., "Web Linking", draft-nottingham- 2636 rfc5988bis-08 (work in progress), August 2017. 2638 [I-D.silverajan-core-coap-protocol-negotiation] 2639 Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation", 2640 draft-silverajan-core-coap-protocol-negotiation-07 (work 2641 in progress), October 2017. 2643 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2644 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2645 Transfer Protocol -- HTTP/1.1", RFC 2616, 2646 DOI 10.17487/RFC2616, June 1999, . 2649 [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. 2650 Bormann, "Neighbor Discovery Optimization for IPv6 over 2651 Low-Power Wireless Personal Area Networks (6LoWPANs)", 2652 RFC 6775, DOI 10.17487/RFC6775, November 2012, 2653 . 2655 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2656 Protocol (HTTP/1.1): Message Syntax and Routing", 2657 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2658 . 2660 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2661 Application Protocol (CoAP)", RFC 7252, 2662 DOI 10.17487/RFC7252, June 2014, . 2665 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2666 the Constrained Application Protocol (CoAP)", RFC 7390, 2667 DOI 10.17487/RFC7390, October 2014, . 2670 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2671 Application Protocol (CoAP)", RFC 7641, 2672 DOI 10.17487/RFC7641, September 2015, . 2675 Appendix A. Web links and the Resource Directory 2677 Understanding the semantics of a link-format document and its URI 2678 references is a journey through different documents ([RFC3986] 2679 defining URIs, [RFC6690] defining link-format documents based on 2680 [RFC5988] which defines link headers, and [RFC7252] providing the 2681 transport). This appendix summarizes the mechanisms and semantics at 2682 play from an entry in ".well-known/core" to a resource lookup. 2684 This text is primarily aimed at people entering the field of 2685 Constrained Restful Environments from applications that previously 2686 did not use web mechanisms. 2688 A.1. A simple example 2690 Let's start this example with a very simple host, "2001:db8:f0::1". 2691 A client that follows classical CoAP Discovery ([RFC7252] Section 7), 2692 sends the following multicast request to learn about neighbours 2693 supporting resources with resource-type "temperature". 2695 The client sends a link-local multicast: 2697 GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature 2699 RES 2.05 Content 2700 ;rt=temperature;ct=0 2702 where the response is sent by the server, "[2001:db8:f0::1]:5683". 2704 While the client - on the practical or implementation side - can just 2705 go ahead and create a new request to "[2001:db8:f0::1]:5683" with 2706 Uri-Path: "temp", the full resolution steps without any shortcuts 2707 are: 2709 A.1.1. Resolving the URIs 2711 The client parses the single returned record. The link's target 2712 (sometimes called "href") is ""/temp"", which is a relative URI that 2713 needs resolving. The Base URI to resolve that against is, in absence 2714 of an "anchor" parameter, the URI of the requested resource as 2715 described in [RFC6690] Section 2.1. 2717 The URI of the requested resource can be composed by following the 2718 steps of [RFC7252] section 6.5 (with an addition at the end of 8.2) 2719 into ""coap://[2001:db8:f0::1]/.well-known/core"". 2721 The record's target is resolved by replacing the path ""/.well-known/ 2722 core"" from the Base URI (section 5.2 [RFC3986]) with the relative 2723 target URI ""/temp"" into ""coap://[2001:db8:f0::1]/temp"". 2725 A.1.2. Interpreting attributes and relations 2727 Some more information but the record's target can be obtained from 2728 the payload: the resource type of the target is "temperature", and 2729 its content type is text/plain (ct=0). 2731 A relation in a web link is a three-part statement that the context 2732 resource has a named relation to the target resource, like "_This 2733 page_ has _its table of contents_ at _/toc.html_". In [RFC6690] 2734 link-format documents, there is an implicit "host relation" specified 2735 with default parameter: rel="hosts". 2737 In our example, the context of the link is the URI of the requested 2738 document itself. A full English expression of the "host relation" 2739 is: 2741 '"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource 2742 "coap://[2001:db8:f0::1]/temp", which is of the resource type 2743 "temperature" and can be accessed using the text/plain content 2744 format.' 2746 A.2. A slightly more complex example 2748 Omitting the "rt=temperature" filter, the discovery query would have 2749 given some more records in the payload: 2751 ;rt=temperature;ct=0, 2752 ;rt=light-lux;ct=0, 2753 ;anchor="/sensors/temp";rel=alternate, 2754 ;anchor="/sensors/temp"; 2755 rel=describedby, 2756 ;rel=alternate;ct=65001; 2757 anchor="http://www.example.com/sensors/t123" 2759 Parsing the third record, the client encounters the "anchor" 2760 parameter. It is a URI relative to the document's Base URI and is 2761 thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That is 2762 the context resource of the link, so the "rel" statement is not about 2763 the target and the document Base URI any more, but about the target 2764 and that address. 2766 Thus, the third record could be read as 2767 ""coap://[2001:db8:f0::1]/sensors/temp" has an alternate 2768 representation at "coap://[2001:db8:f0::1]/t"". 2770 The fourth record can be read as ""coap://[2001:db8:f0::1]/sensors/ 2771 temp" is described by "http://www.example.com/sensors/t123"" 2773 In the last example the anchor is absolute, where a ""t123.pdf"" is 2774 resolved relative to ""http://www.example.com/sensors/t123"", which 2775 gives a statement that ""http://www.example.com/sensors/t123/ 2776 t123.pdf" is an alternate representation to 2777 ""http://www.example.com/sensors/t123" of which the content type is 2778 PDF". 2780 A.3. Enter the Resource Directory 2782 The resource directory tries to carry the semantics obtainable by 2783 classical CoAP discovery over to the resource lookup interface as 2784 faithfully as possible. 2786 For the following queries, we will assume that the simple host has 2787 used Simple Registration to register at the resource directory that 2788 was announced to it, sending this request from its UDP port 2789 "[2001:db8:f0::1]:6553": 2791 POST coap://[2001:db8:f01::ff]/.well-known/core?ep-simple-host1 2793 The resource directory would have accepted the registration, and 2794 queried the simple host's ".well-known/core" by itself. As a result, 2795 the host is registered as an endpoint in the RD with the name 2796 "simple-host1". The registration is active for 86400 seconds, and 2797 the endpoint registration Base URI is ""coap://[2001:db8:f0::1]/"" 2798 because that is the address the registration was sent from (and no 2799 explicit "con=" was given). 2801 If the client now queries the RD as it would previously have issued a 2802 multicast request, it would go through the RD discovery steps by 2803 fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- 2804 lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the 2805 resource lookup endpoint, and issue a request to 2806 "coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive 2807 the following data: 2809 ;rt=temperature;ct=0;anchor="coap://[2001:db8:f0::1]" 2811 This is not _literally_ the same response that it would have received 2812 from a multicast request, but it would contain the (almost) same 2813 statement: 2815 '"coap://[2001:db8:f0::1]" is hosting the resource 2816 "coap://[2001:db8:f0::1]/temp", which is of the resource type 2817 "temperature" and can be accessed using the text/plain content 2818 format.' 2820 (The difference is whether "/" or "/.well-known/core" hosts the 2821 resources, which is subject of ongoing discussion about RFC6690). 2823 To complete the examples, the client could also query all resources 2824 hosted at the endpoint with the known endpoint name "simple-host1". 2825 A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1" 2826 would return 2828 ;rt=temperature;ct=0;anchor="coap://[2001:db8:f0::1]", 2829 ;rt=light-lux;ct=0;anchor="coap://[2001:db8:f0::1]", 2830 ;anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, 2831 ; 2832 anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=describedby, 2833 ;rel=alternate;ct=65001; 2834 anchor="http://www.example.com/sensors/t123" 2836 Note that the last link was not modified at all because its anchor 2837 was already an absolute reference. 2839 Had the simple host registered with an explicit context (eg. 2840 "?ep=simple-host1&con=coap+tcp://simple-host1.example.com"), that 2841 context would have been used to resolve the relative anchor values 2842 instead, giving 2844 ;rt=temperature;ct=0;anchor="coap+tcp://simple-host1.example.com" 2845 and analogous records. 2847 A.4. A note on differences between link-format and Link headers 2849 While link-format and Link headers look very similar and are based on 2850 the same model of typed links, there are some differences between 2851 [RFC6690] and [RFC5988] that should be kept in mind when using or 2852 implementing a Resource Directory: 2854 o There is no percent encoding in link-format documents. 2856 A link-format document is a UTF-8 encoded string of Unicode 2857 characters and does not have percent encoding, while Link headers 2858 are practically ASCII strings that use percent encoding for non- 2859 ASCII characters, stating the encoding explictly when required. 2861 For example, while a Link header in a page about a Swedish city 2862 might read 2864 "Link: ;rel="live-environment-data"" 2866 a link-format document from the same source might describe the 2867 link as 2869 ";rel="live-environment-data"" 2871 o In a link-format document, if the anchor attribute is present, the 2872 link target reference is resolved by using the the (resolved) 2873 anchor value as Base URI for that link, while in Link headers, it 2874 is resolved against the URI of the requested document. 2876 This is explicit in [RFC6690] section 2.1 for link-format, and 2877 spelled out in section B.2 of [I-D.nottingham-rfc5988bis] , which 2878 obsoletes the older [RFC5988]. [RFC6690] is based on [RFC5988] 2879 and has not been updated with clarifications from 2880 [I-D.nottingham-rfc5988bis]. 2882 Appendix B. Syntax examples for Protocol Negotiation 2884 [ This appendix should not show up in a published version of this 2885 document. ] 2887 The protocol negotiation that is being worked on in 2888 [I-D.silverajan-core-coap-protocol-negotiation] makes use of the 2889 Resource Directory. 2891 Until that document is update to use the latest resource-directory 2892 specification, here are some examples of protocol negotiation with 2893 the current Resource Directory: 2895 An endpoint could register as follows: 2897 Req: POST coap://rd.example.com/rd?ep=node1 2898 &at=coap+tcp://[2001:db8:f1::2] 2899 &at=coap://[2001:db8:f1::2] 2900 Content-Format: 40 2901 Payload: 2902 ;ct=0;rt="temperature";if="core.s" 2904 Res: 2.01 Created 2905 Location: /rd/1234 2907 A UDP client would then query: 2909 Req: GET /rd-lookup/res?rt=temperature 2911 Res: 2.05 Content 2912 ;ct=0;rt="temperature";if="core.s"; 2913 anchor="coap://[2001:db8:f1::2]" 2915 while a TCP capable client could say: 2917 Req: GET /rd-lookup/res?rt=temperature&tt=tcp 2919 Res: 2.05 Content 2920 ;ct=0;rt="temperature";if="core.s"; 2921 anchor="coap+tcp://[2001:db8:f1::2]" 2923 Authors' Addresses 2925 Zach Shelby 2926 ARM 2927 150 Rose Orchard 2928 San Jose 95134 2929 USA 2931 Phone: +1-408-203-9434 2932 Email: zach.shelby@arm.com 2933 Michael Koster 2934 SmartThings 2935 665 Clyde Avenue 2936 Mountain View 94043 2937 USA 2939 Phone: +1-707-502-5136 2940 Email: Michael.Koster@smartthings.com 2942 Carsten Bormann 2943 Universitaet Bremen TZI 2944 Postfach 330440 2945 Bremen D-28359 2946 Germany 2948 Phone: +49-421-218-63921 2949 Email: cabo@tzi.org 2951 Peter van der Stok 2952 consultant 2954 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2955 Email: consultancy@vanderstok.org 2956 URI: www.vanderstok.org 2958 Christian Amsuess (editor) 2959 Energy Harvesting Solutions 2960 Hollandstr. 12/4 2961 1020 2962 Austria 2964 Phone: +43-664-9790639 2965 Email: c.amsuess@energyharvesting.at