idnits 2.17.1 draft-ietf-core-resource-directory-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 22, 2015) is 3232 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-02 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-02 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft M. Koster 4 Intended status: Standards Track ARM 5 Expires: December 24, 2015 C. Bormann 6 Universitaet Bremen TZI 7 P. van der Stok 8 consultant 9 June 22, 2015 11 CoRE Resource Directory 12 draft-ietf-core-resource-directory-03 14 Abstract 16 In many M2M applications, direct discovery of resources is not 17 practical due to sleeping nodes, disperse networks, or networks where 18 multicast traffic is inefficient. These problems can be solved by 19 employing an entity called a Resource Directory (RD), which hosts 20 descriptions of resources held on other servers, allowing lookups to 21 be performed for those resources. This document specifies the web 22 interfaces that a Resource Directory supports in order for web 23 servers to discover the RD and to register, maintain, lookup and 24 remove resources descriptions. Furthermore, new link attributes 25 useful in conjunction with an RD are defined. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on December 24, 2015. 44 Copyright Notice 46 Copyright (c) 2015 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 64 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6 65 3.2. Use Case: Home and Building Automation . . . . . . . . . 7 66 3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7 67 4. Simple Directory Discovery . . . . . . . . . . . . . . . . . 8 68 4.1. Finding a Directory Server . . . . . . . . . . . . . . . 9 69 4.2. Third-party registration . . . . . . . . . . . . . . . . 10 70 5. Resource Directory Function Set . . . . . . . . . . . . . . . 10 71 5.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 10 72 5.2. Registration . . . . . . . . . . . . . . . . . . . . . . 12 73 5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 5.4. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 5.5. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 17 76 6. Group Function Set . . . . . . . . . . . . . . . . . . . . . 18 77 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 18 78 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 20 79 7. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . 21 80 8. New Link-Format Attributes . . . . . . . . . . . . . . . . . 25 81 8.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 25 82 8.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 25 83 9. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 25 84 9.1. DNS-based Service discovery . . . . . . . . . . . . . . . 26 85 9.2. mapping ins to . . . . . . . . . . . . . . . . 27 86 9.3. Mapping rt to . . . . . . . . . . . . . . . 27 87 9.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 28 88 9.5. TXT Record key=value strings . . . . . . . . . . . . . . 28 89 9.6. Importing resource links into DNS-SD . . . . . . . . . . 28 90 10. Security Considerations . . . . . . . . . . . . . . . . . . . 29 91 10.1. Endpoint Identification and Authentication . . . . . . . 30 92 10.2. Access Control . . . . . . . . . . . . . . . . . . . . . 30 93 10.3. Denial of Service Attacks . . . . . . . . . . . . . . . 30 94 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 95 11.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 31 96 11.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 31 97 11.3. RD Parameter Registry . . . . . . . . . . . . . . . . . 31 98 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 32 99 12.1. Lighting Installation . . . . . . . . . . . . . . . . . 32 100 12.1.1. Installation Characteristics . . . . . . . . . . . . 32 101 12.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 34 102 12.1.3. DNS entries . . . . . . . . . . . . . . . . . . . . 37 103 12.1.4. RD Operation . . . . . . . . . . . . . . . . . . . . 41 104 12.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 41 105 12.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 42 106 12.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 42 107 12.2.3. Alternate Base URI . . . . . . . . . . . . . . . . . 44 108 12.2.4. LWM2M Update Endpoint Registration . . . . . . . . . 44 109 12.2.5. LWM2M De-Register Endpoint . . . . . . . . . . . . . 44 110 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 111 14. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 45 112 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 113 15.1. Normative References . . . . . . . . . . . . . . . . . . 47 114 15.2. Informative References . . . . . . . . . . . . . . . . . 48 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 117 1. Introduction 119 The work on Constrained RESTful Environments (CoRE) aims at realizing 120 the REST architecture in a suitable form for the most constrained 121 nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and 122 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 123 applications such as smart energy and building automation. 125 The discovery of resources offered by a constrained server is very 126 important in machine-to-machine applications where there are no 127 humans in the loop and static interfaces result in fragility. The 128 discovery of resources provided by an HTTP Web Server is typically 129 called Web Linking [RFC5988]. The use of Web Linking for the 130 description and discovery of resources hosted by constrained web 131 servers is specified by the CoRE Link Format [RFC6690]. This 132 specification however only describes how to discover resources from 133 the web server that hosts them by requesting "/.well-known/core". In 134 many M2M scenarios, direct discovery of resources is not practical 135 due to sleeping nodes, disperse networks, or networks where multicast 136 traffic is inefficient. These problems can be solved by employing an 137 entity called a Resource Directory (RD), which hosts descriptions of 138 resources held on other servers, allowing lookups to be performed for 139 those resources. 141 This document specifies the web interfaces that a Resource Directory 142 supports in order for web servers to discover the RD and to register, 143 maintain, lookup and remove resource descriptions. Furthermore, new 144 link attributes useful in conjunction with a Resource Directory are 145 defined. Although the examples in this document show the use of 146 these interfaces with CoAP [RFC7252], they can be applied in an 147 equivalent manner to HTTP [RFC7230]. 149 2. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 153 "OPTIONAL" in this document are to be interpreted as described in 154 [RFC2119]. The term "byte" is used in its now customary sense as a 155 synonym for "octet". 157 This specification requires readers to be familiar with all the terms 158 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 159 should also be familiar with the terms and concepts discussed in 160 [RFC7252]. To describe the REST interfaces defined in this 161 specification, the URI Template format is used [RFC6570]. 163 This specification makes use of the following additional terminology: 165 Resource Directory 166 A web entity that stores information about web resources and 167 implements the REST interfaces defined in this specification for 168 registration and lookup of those resources. 170 Domain 171 In the context of a Resource Directory, a domain is a logical 172 grouping of endpoints. This specification assumes that the list 173 of Domains supported by an RD is pre-configured by that RD. When 174 a domain is exported to DNS, the domain value equates to the DNS 175 domain name. 177 Group 178 In the context of a Resource Directory, a group is a logical 179 grouping of endpoints for the purpose of group communications. 180 All groups within a domain are unique. 182 Endpoint 183 Endpoint (EP) is a term used to describe a web server or client in 184 [RFC7252]. In the context of this specification an endpoint is 185 used to describe a web server that registers resources to the 186 Resource Directory. An endpoint is identified by its endpoint 187 name, which is included during registration, and is unique within 188 the associated domain of the registration. 190 3. Architecture and Use Cases 192 The resource directory architecture is illustrated in Figure 1. A 193 Resource Directory (RD) is used as a repository for Web Links 194 [RFC5988] about resources hosted on other web servers, which are 195 called endpoints (EP). An endpoint is a web server associated with a 196 scheme, IP address and port (called Context), thus a physical node 197 may host one or more endpoints. The RD implements a set of REST 198 interfaces for endpoints to register and maintain sets of Web Links 199 (called resource directory entries), and for clients to lookup 200 resources from the RD or maintain groups. Endpoints themselves can 201 also act as clients. An RD can be logically segmented by the use of 202 Domains. The domain an endpoint is associated with can be defined by 203 the RD or configured by an outside entity. This information 204 hierarchy is shown in Figure 2. 206 Endpoints are assumed to proactively register and maintain resource 207 directory entries on the RD, which are soft state and need to be 208 periodically refreshed. An endpoint is provided with interfaces to 209 register, update and remove a resource directory entry. Furthermore, 210 a mechanism to discover an RD using the CoRE Link Format is defined. 211 It is also possible for an RD to proactively discover Web Links from 212 endpoints and add them as resource directory entries. A lookup 213 interface for discovering any of the Web Links held in the RD is 214 provided using the CoRE Link Format. 216 Registration Lookup, Group 217 +----+ | | 218 | EP |---- | | 219 +----+ ---- | | 220 --|- +------+ | 221 +----+ | ----| | | +--------+ 222 | EP | ---------|-----| RD |----|-----| Client | 223 +----+ | ----| | | +--------+ 224 --|- +------+ | 225 +----+ ---- | | 226 | EP |---- | | 227 +----+ 229 Figure 1: The resource directory architecture. 231 +------------+ 232 | Domain | <-- Name 233 +------------+ 234 | | 235 | +------------+ 236 | | Group | <-- Name, IP 237 | +------------+ 238 | | 239 +------------+ 240 | Endpoint | <-- Name, Scheme, IP, Port 241 +------------+ 242 | 243 | 244 +------------+ 245 | Resource | <-- Target, Parameters 246 +------------+ 248 Figure 2: The resource directory information hierarchy. 250 3.1. Use Case: Cellular M2M 252 Over the last few years, mobile operators around the world have 253 focused on development of M2M solutions in order to expand the 254 business to the new type of users: machines. The machines are 255 connected directly to a mobile network using an appropriate embedded 256 air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short 257 and wide range wireless interfaces. From the system design point of 258 view, the ambition is to design horizontal solutions that can enable 259 utilization of machines in different applications depending on their 260 current availability and capabilities as well as application 261 requirements, thus avoiding silo like solutions. One of the crucial 262 enablers of such design is the ability to discover resources 263 (machines -- endpoints) capable of providing required information at 264 a given time or acting on instructions from the end users. 266 In a typical scenario, during a boot-up procedure (and periodically 267 afterwards), the machines (endpoints) register with a Resource 268 Directory (for example EPs installed on vehicles enabling tracking of 269 their position for fleet management purposes and monitoring 270 environment parameters) hosted by the mobile operator or somewhere 271 else in the network, periodically a description of its own 272 capabilities. Due to the usual network configuration of mobile 273 networks, the EPs attached to the mobile network do not have routable 274 addresses. Therefore, a remote server is usually used to provide 275 proxy access to the EPs. The address of each (proxy) endpoint on 276 this server is included in the resource description stored in the RD. 277 The users, for example mobile applications for environment 278 monitoring, contact the RD, look-up the endpoints capable of 279 providing information about the environment using appropriate set of 280 link parameters, obtain information on how to contact them (URLs of 281 the proxy server) and then initiate interaction to obtain information 282 that is finally processed, displayed on the screen and usually stored 283 in a database. Similarly, fleet management systems provide the 284 appropriate link parameters to the RD to look-up for EPs deployed on 285 the vehicles the application is responsible for. 287 3.2. Use Case: Home and Building Automation 289 Home and commercial building automation systems can benefit from the 290 use of M2M web services. The discovery requirements of these 291 applications are demanding. Home automation usually relies on run- 292 time discovery to commission the system, whereas in building 293 automation a combination of professional commissioning and run-time 294 discovery is used. Both home and building automation involve peer- 295 to-peer interactions between endpoints, and involve battery-powered 296 sleeping devices. 298 The exporting of resource information to other discovery systems is 299 also important in these automation applications. In home automation 300 there is a need to interact with other consumer electronics, which 301 may already support DNS-SD, and in building automation larger 302 resource directories or DNS-SD covering multiple buildings. 304 3.3. Use Case: Link Catalogues 306 Resources may be shared through data brokers that have no knowledge 307 beforehand of who is going to consume the data. Resource Directory 308 can be used to hold links about resources and services hosted 309 anywhere to make them discoverable by a general class of 310 applications. 312 For example, environmental and weather sensors that generate data for 313 public consumption may provide the data to an intermediary server, or 314 broker. Sensor data are published to the intermediary upon changes 315 or at regular intervals. Descriptions of the sensors that resolve to 316 links to sensor data may be published to a Resource Directory. 317 Applications wishing to consume the data can use the Resource 318 Directory lookup function set to discover and resolve links to the 319 desired resources and endpoints. The Resource Directory service need 320 not be coupled with the data intermediary service. Mapping of 321 Resource Directories to data intermediaries may be many-to-many. 323 Metadata in link-format or link-format+json representations are 324 supplied by Resource Directories, which may be internally stored as 325 triples, or relation/attribute pairs providing metadata about 326 resource links. External catalogs that are represented in other 327 formats may be converted to link-format or link-format+json for 328 storage and access by Resource Directories. Since it is common 329 practice for these to be URN encoded, simple and lossless structural 330 transforms will generally be sufficient to store external metadata in 331 Resource Directories. 333 The additional features of Resource Directory allow domains to be 334 defined to enable access to a particular set of resources from 335 particular applications. This provides isolation and protection of 336 sensitive data when needed. Resource groups may defined to allow 337 batched reads from multiple resources. 339 4. Simple Directory Discovery 341 Not all endpoints hosting resources are expected to know how to 342 implement the Resource Directory Function Set (see Section 5) and 343 thus explicitly register with a Resource Directory (or other such 344 directory server). Instead, simple endpoints can implement the 345 generic Simple Directory Discovery approach described in this 346 section. An RD implementing this specification MUST implement Simple 347 Directory Discovery. However, there may be security reasons why this 348 form of directory discovery would be disabled. 350 This approach requires that the endpoint makes available the hosted 351 resources that it wants to be discovered, as links on its "/.well- 352 known/core" interface as specified in [RFC6690]. 354 The endpoint then finds one or more IP addresses of the directory 355 server it wants to know about its resources as described in 356 Section 4.1. 358 An endpoint that wants to make itself discoverable occasionally sends 359 a POST request to the "/.well-known/core" URI of any candidate 360 directory server that it finds. The body of the POST request is 361 either 363 o empty, in which case the directory server is encouraged by this 364 POST request to perform GET requests at the requesting server's 365 default discovery URI. 367 or 369 o a non-empty link-format document, which indicates the specific 370 services that the requesting server wants to make known to the 371 directory server. 373 The directory server integrates the information it received this way 374 into its resource directory. It MAY make the information available 375 to further directories, if it can ensure that a loop does not form. 376 The protocol used between directories to ensure loop-free operation 377 is outside the scope of this document. 379 The following example shows an endpoint using simple resource 380 discovery, by simply sending a POST with its links in the body to a 381 directory. 383 EP RD 384 | | 385 | -- POST /.well-known/core "..." ---> | 386 | | 387 | | 388 | <---- 2.01 Created ------------------------- | 389 | | 391 4.1. Finding a Directory Server 393 Endpoints that want to contact a directory server can obtain 394 candidate IP addresses for such servers in a number of ways. 396 In a 6LoWPAN, good candidates can be taken from: 398 o specific static configuration (e.g., anycast addresses), if any, 400 o the ABRO option of 6LoWPAN-ND [RFC6775], 402 o other ND options that happen to point to servers (such as RDNSS), 404 o DHCPv6 options that might be defined later. 406 In networks with more inexpensive use of multicast, the candidate IP 407 address may be a well-known multicast address, i.e. directory servers 408 are found by simply sending POST requests to that well-known 409 multicast address (details TBD). 411 As some of these sources are just (more or less educated) guesses, 412 endpoints MUST make use of any error messages to very strictly rate- 413 limit requests to candidate IP addresses that don't work out. For 414 example, an ICMP Destination Unreachable message (and, in particular, 415 the port unreachable code for this message) may indicate the lack of 416 a CoAP server on the candidate host, or a CoAP error response code 417 such as 4.05 "Method Not Allowed" may indicate unwillingness of a 418 CoAP server to act as a directory server. 420 4.2. Third-party registration 422 For some applications, even Simple Directory Discovery may be too 423 taxing for certain very constrained devices, in particular if the 424 security requirements become too onerous. 426 In a controlled environment (e.g. building control), the Resource 427 Directory can be filled by a third device, called an installation 428 tool. The installation tool can fill the Resource Directory from a 429 database or other means. For that purpose the scheme, IP address and 430 port of the registered device is indicated in the Context parameter 431 of the registration as well. 433 5. Resource Directory Function Set 435 This section defines the REST interfaces between an RD and endpoints, 436 which is called the Resource Directory Function Set. Although the 437 examples throughout this section assume the use of CoAP [RFC7252], 438 these REST interfaces can also be realized using HTTP [RFC7230]. An 439 RD implementing this specification MUST support the discovery, 440 registration, update, lookup, and removal interfaces defined in this 441 section. 443 Resource directory entries are designed to be easily exported to 444 other discovery mechanisms such as DNS-SD. For that reason, 445 parameters that would meaningfully be mapped to DNS SHOULD be limited 446 to a maximum length of 63 bytes. 448 5.1. Discovery 450 Before an endpoint can make use of an RD, it must first know the RD's 451 IP address, port and the path of its RD Function Set. There can be 452 several mechanisms for discovering the RD including assuming a 453 default location (e.g. on an Edge Router in a LoWPAN), by assigning 454 an anycast address to the RD, using DHCP, or by discovering the RD 455 using the CoRE Link Format (see also Section 4.1). This section 456 defines discovery of the RD using the well-known interface of the 457 CoRE Link Format [RFC6690] as the required mechanism. It is however 458 expected that RDs will also be discoverable via other methods 459 depending on the deployment. 461 Discovery is performed by sending either a multicast or unicast GET 462 request to "/.well-known/core" and including a Resource Type (rt) 463 parameter [RFC6690] with the value "core.rd" in the query string. 464 Likewise, a Resource Type parameter value of "core.rd-lookup" is used 465 to discover the RD Lookup Function Set. Upon success, the response 466 will contain a payload with a link format entry for each RD 467 discovered, with the URL indicating the root resource of the RD. 469 When performing multicast discovery, the multicast IP address used 470 will depend on the scope required and the multicast capabilities of 471 the network. 473 An RD implementation of this specification MUST support query 474 filtering for the rt parameter as defined in [RFC6690]. 476 The discovery request interface is specified as follows: 478 Interaction: EP -> RD 480 Method: GET 482 URI Template: /.well-known/core{?rt} 484 URI Template Variables: 486 rt := Resource Type (optional). MAY contain the value "core.rd", 487 "core.rd-lookup", "core.rd-group" or "core.rd*" 489 Content-Type: application/link-format (if any) 491 The following response codes are defined for this interface: 493 Success: 2.05 "Content" with an application/link-format payload 494 containing one or more matching entries for the RD resource. 496 Failure: 4.04 "Not Found" is returned in case no matching entry is 497 found for a unicast request. 499 Failure: 4.00 "Bad Request" is returned in case of a malformed 500 request for a unicast request. 502 Failure: No error response to a multicast request. 504 The following example shows an endpoint discovering an RD using this 505 interface, thus learning that the base RD resource is, in this 506 example, at /rd. Note that it is up to the RD to choose its base RD 507 resource, although diagnostics and debugging is facilitated by using 508 the base paths specified here where possible. 510 EP RD 511 | | 512 | ----- GET /.well-known/core?rt=core.rd* ------> | 513 | | 514 | | 515 | <---- 2.05 Content "; rt="core.rd" ------ | 516 | | 518 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 520 Res: 2.05 Content 521 ;rt="core.rd", 522 ;rt="core.rd-lookup", 523 ;rt="core.rd-group" 525 5.2. Registration 527 After discovering the location of an RD Function Set, an endpoint MAY 528 register its resources using the registration interface. This 529 interface accepts a POST from an endpoint containing the list of 530 resources to be added to the directory as the message payload in the 531 CoRE Link Format [RFC6690] or JSON Link Format 532 [I-D.ietf-core-links-json] along with query string parameters 533 indicating the name of the endpoint, its domain and the lifetime of 534 the registration. All parameters except the endpoint name are 535 optional. It is expected that other specifications will define 536 further parameters (see Section 11.3). The RD then creates a new 537 resource or updates an existing resource in the RD and returns its 538 location. An endpoint MUST use that location when refreshing 539 registrations using this interface. Endpoint resources in the RD are 540 kept active for the period indicated by the lifetime parameter. The 541 endpoint is responsible for refreshing the entry within this period 542 using either the registration or update interface. The registration 543 interface MUST be implemented to be idempotent, so that registering 544 twice with the same endpoint parameter does not create multiple RD 545 entries. 547 The registration request interface is specified as follows: 549 Interaction: EP -> RD 551 Method: POST 553 URI Template: /{+rd}{?ep,d,et,lt,con} 555 URI Template Variables: 557 rd := RD Function Set path (mandatory). This is the path of the 558 RD Function Set, as obtained from discovery. An RD SHOULD use 559 the value "rd" for this variable whenever possible. 561 ep := Endpoint (mandatory). The endpoint identifier or name of 562 the registering node, unique within that domain. The maximum 563 length of this parameter is 63 bytes. 565 d := Domain (optional). The domain to which this endpoint 566 belongs. This parameter SHOULD be less than 63 bytes. 567 Optional. When this parameter is elided, the RD MAY associate 568 the endpoint with a configured default domain. The domain 569 value is needed to export the endpoint to DNS-SD (see 570 Section 9). 572 et := Endpoint Type (optional). The semantic type of the 573 endpoint. This parameter SHOULD be less than 63 bytes. 574 Optional. 576 lt := Lifetime (optional). Lifetime of the registration in 577 seconds. Range of 60-4294967295. If no lifetime is included, 578 a default value of 86400 (24 hours) SHOULD be assumed. 580 con := Context (optional). This parameter sets the scheme, 581 address and port at which this server is available in the form 582 scheme://host:port. Optional. In the absence of this 583 parameter the scheme of the protocol, source IP address and 584 source port of the register request are assumed. This 585 parameter is mandatory when the directory is filled by a third 586 party such as an installation tool. 588 Content-Type: application/link-format 590 Content-Type: application/link-format+json 592 The following response codes are defined for this interface: 594 Success: 2.01 "Created". The Location header MUST be included with 595 the new resource entry for the endpoint. This Location MUST be a 596 stable identifier generated by the RD as it is used for all 597 subsequent operations on this registration. The resource returned 598 in the Location is only for the purpose of the Update (POST) and 599 Removal (DELETE), and MUST NOT implement GET or PUT methods. 601 Failure: 4.00 "Bad Request". Malformed request. 603 Failure: 5.03 "Service Unavailable". Service could not perform the 604 operation. 606 The following example shows an endpoint with the name "node1" 607 registering two resources to an RD using this interface. The 608 resulting location /rd/4521 is just an example of an RD generated 609 location. 611 EP RD 612 | | 613 | --- POST /rd?ep=node1 " | 614 | | 615 | | 616 | <-- 2.01 Created Location: /rd/4521 ---------- | 617 | | 619 Req: POST coap://rd.example.com/rd?ep=node1 620 Payload: 621 ;ct=41;rt="temperature-c";if="sensor", 622 ;ct=41;rt="light-lux";if="sensor" 624 Res: 2.01 Created 625 Location: /rd/4521 627 5.3. Update 629 The update interface is used by an endpoint to refresh or update its 630 registration with an RD. To use the interface, the endpoint sends a 631 POST request to the resource returned in the Location option in the 632 response to the first registration. An update MAY update the 633 lifetime or context parameters if they have changed since the last 634 registration or update. Parameters that have not changed SHOULD NOT 635 be included in an update. Upon receiving an update request, the RD 636 resets the timeout for that endpoint and updates the scheme, IP 637 address and port of the endpoint (using the source address of the 638 update, or the context parameter if present). 640 An update MAY optionally add or replace links for the endpoint by 641 including those links in the payload of the update as a CoRE Link 642 Format document. Including links in an update message greatly 643 increases the load on an RD and SHOULD be done infrequently. A link 644 is replaced only if both the target URI and relation type match (see 645 Section 10.1). 647 The update request interface is specified as follows: 649 Interaction: EP -> RD 651 Method: POST 653 URI Template: /{+location}{?lt,con} 654 URI Template Variables: 656 location := This is the Location path returned by the RD as a 657 result of a successful earlier registration. 659 lt := Lifetime (optional). Lifetime of the registration in 660 seconds. Range of 60-4294967295. If no lifetime is included, 661 a default value of 86400 (24 hours) SHOULD be assumed. 663 con := Context (optional). This parameter sets the scheme, 664 address and port at which this server is available in the form 665 scheme://host:port. Optional. In the absence of this 666 parameter the scheme of the protocol, source IP address and 667 source port used to register are assumed. This parameter is 668 compulsory when the directory is filled by a third party such 669 as an installation tool. 671 Content-Type: application/link-format (optional) 673 Content-Type: application/link-format+json (optional) 675 The following response codes are defined for this interface: 677 Success: 2.04 "Changed" in the update was successfully processed. 679 Failure: 4.00 "Bad Request". Malformed request. 681 Failure: 4.04 "Not Found". Registration does not exist (e.g. may 682 have expired). 684 Failure: 5.03 "Service Unavailable". Service could not perform the 685 operation. 687 The following example shows an endpoint updating its registration at 688 an RD using this interface. 690 EP RD 691 | | 692 | --- POST /rd/4521 --------------------------> | 693 | | 694 | | 695 | <-- 2.04 Changed ---------------------------- | 696 | | 698 Req: POST /rd/4521 700 Res: 2.04 Changed 702 5.4. Removal 704 Although RD entries have soft state and will eventually timeout after 705 their lifetime, an endpoint SHOULD explicitly remove its entry from 706 the RD if it knows it will no longer be available (for example on 707 shut-down). This is accomplished using a removal interface on the RD 708 by performing a DELETE on the endpoint resource. 710 The removal request interface is specified as follows: 712 Interaction: EP -> RD 714 Method: DELETE 716 URI Template: /{+location} 718 URI Template Variables: 720 location := This is the Location path returned by the RD as a 721 result of a successful earlier registration. 723 The following responses codes are defined for this interface: 725 Success: 2.02 "Deleted" upon successful deletion 727 Failure: 4.00 "Bad Request". Malformed request. 729 Failure: 4.04 "Not Found". Registration does not exist (e.g. may 730 have expired). 732 Failure: 5.03 "Service Unavailable". Service could not perform the 733 operation. 735 The following examples shows successful removal of the endpoint from 736 the RD. 738 EP RD 739 | | 740 | --- DELETE /rd/4521 ------------------------> | 741 | | 742 | | 743 | <-- 2.02 Deleted ---------------------------- | 744 | | 746 Req: DELETE /rd/4521 748 Res: 2.02 Deleted 750 5.5. Read Endpoint Links 752 Some endpoints may wish to manage their links as a collection, and 753 may need to read the current set of links in order to determine link 754 maintenance operations. 756 The read request interface is specified as follows: 758 Interaction: EP -> RD 760 Method: GET 762 URI Template: /{+location}{?rt,if,ct} 764 URI Template Variables: 766 location := This is the Location path returned by the RD as a 767 result of a successful earlier registration. 769 The following responses codes are defined for this interface: 771 Success: 2.05 "Content" upon success 773 Failure: 4.00 "Bad Request". Malformed request. 775 Failure: 4.04 "Not Found". Registration does not exist (e.g. may 776 have expired). 778 Failure: 5.03 "Service Unavailable". Service could not perform the 779 operation. 781 The following examples show successful read of the endpoint links 782 from the RD. 784 EP RD 785 | | 786 | --- GET /rd/4521 ------------------------> | 787 | | 788 | | 789 | <-- 2.05 Content ;ct=41;rt="temperature-c";if="sensor", 797 ;ct=41;rt="light-lux";if="sensor" 799 6. Group Function Set 801 This section defines a function set for the creation of groups of 802 endpoints for the purpose of managing and looking up endpoints for 803 group operations. The group function set is similar to the resource 804 directory function set, in that a group may be created or removed. 805 However unlike an endpoint entry, a group entry consists of a list of 806 endpoints and does not have a lifetime associated with it. In order 807 to make use of multicast requests with CoAP, a group MAY have a 808 multicast address associated with it. 810 6.1. Register a Group 812 In order to create a group, a management entity used to configure 813 groups, makes a request to the RD indicating the name of the group to 814 create (or update), optionally the domain the group belongs to, and 815 optionally the multicast address of the group. The registration 816 message includes the list of endpoints that belong to that group. If 817 an endpoint has already registered with the RD, the RD attempts to 818 use the context of the endpoint from its RD endpoint entry. If the 819 client registering the group knows the endpoint has already 820 registered, then it MAY send a blank target URI for that endpoint 821 link when registering the group. Configuration of the endpoints 822 themselves is out of scope of this specification. Such an interface 823 for managing the group membership of an endpoint has been defined in 824 [RFC7390]. 826 The registration request interface is specified as follows: 828 Interaction: Manager -> RD 830 Method: POST 832 URI Template: /{+rd-group}{?gp,d,con} 834 URI Template Variables: 836 rd-group := RD Group Function Set path (mandatory). This is the 837 path of the RD Group Function Set. An RD SHOULD use the value 838 "rd-group" for this variable whenever possible. 840 gp := Group Name (mandatory). The name of the group to be 841 created or replaced, unique within that domain. The maximum 842 length of this parameter is 63 bytes. 844 d := Domain (optional). The domain to which this group belongs. 845 The maximum length of this parameter is 63 bytes. Optional. 846 When this parameter is elided, the RD MAY associate the 847 endpoint with a configured default domain. The domain value is 848 needed to export the endpoint to DNS-SD (see Section 9) 850 con := Context (optional). This parameter is used to set the IP 851 multicast address at which this server is available in the form 852 scheme://multicast-address:port. Optional. In the absence of 853 this parameter no multicast address is configured. This 854 parameter is compulsory when the directory is filled by an 855 installation tool. 857 Content-Type: application/link-format 859 Content-Type: application/link-format+json 861 The following response codes are defined for this interface: 863 Success: 2.01 "Created". The Location header MUST be included with 864 the new group entry. This Location MUST be a stable identifier 865 generated by the RD as it is used for delete operations on this 866 registration. 868 Failure: 4.00 "Bad Request". Malformed request. 870 Failure: 5.03 "Service Unavailable". Service could not perform the 871 operation. 873 The following example shows a group with the name "lights" 874 registering two endpoints to an RD using this interface. The 875 resulting location /rd-group/12 is just an example of an RD generated 876 group location. 878 EP RD 879 | | 880 | - POST /rd-group?gp=lights "<>;ep=node1..." --> | 881 | | 882 | | 883 | <---- 2.01 Created Location: /rd-group/12 ---- | 884 | | 886 Req: POST coap://rd.example.com/rd-group?gp=lights 887 Payload: 888 <>;ep="node1", 889 <>;ep="node2" 891 Res: 2.01 Created 892 Location: /rd-group/12 894 6.2. Group Removal 896 A group can be removed simply by sending a removal message to the 897 location returned when registering the group. Removing a group MUST 898 NOT remove the endpoints of the group from the RD. 900 The removal request interface is specified as follows: 902 Interaction: Manager -> RD 904 Method: DELETE 906 URI Template: /{+location} 908 URI Template Variables: 910 location := This is the Location path returned by the RD as a 911 result of a successful group registration. 913 The following responses codes are defined for this interface: 915 Success: 2.02 "Deleted" upon successful deletion 917 Failure: 4.00 "Bad Request". Malformed request. 919 Failure: 4.04 "Not Found". Group does not exist. 921 Failure: 5.03 "Service Unavailable". Service could not perform the 922 operation. 924 The following examples shows successful removal of the group from the 925 RD. 927 EP RD 928 | | 929 | --- DELETE /rd-group/412 -------------------> | 930 | | 931 | | 932 | <-- 2.02 Deleted ---------------------------- | 933 | | 935 Req: DELETE /rd-group/12 937 Res: 2.02 Deleted 939 7. RD Lookup Function Set 941 In order for an RD to be used for discovering resources registered 942 with it, a lookup interface can be provided using this function set. 943 This lookup interface is defined as a default, and it is assumed that 944 RDs may also support lookups to return resource descriptions in 945 alternative formats (e.g. Atom or HTML Link) or using more advanced 946 interfaces (e.g. supporting context or semantic based lookup). 948 This function set allows lookups for domains, groups, endpoints and 949 resources using attributes defined in the RD Function Set and for use 950 with the CoRE Link Format. The result of a lookup request is the 951 list of links (if any) corresponding to the type of lookup. Using 952 the Accept Option, the requester can control whether this list is 953 returned in CoRE Link Format ("application/link-format", default) or 954 its JSON form ("application/link-format+json"). The target of these 955 links SHOULD be the actual location of the domain, endpoint or 956 resource, but MAY be an intermediate proxy e.g. in the case of an 957 HTTP lookup interface for CoAP endpoints. Multiple query parameters 958 MAY be included in a lookup, all included parameters MUST match for a 959 resource to be returned. The character '*' MAY be included at the 960 end of a parameter value as a wildcard operator. 962 The lookup interface is specified as follows: 964 Interaction: Client -> RD 966 Method: GET 968 URI Template: /{+rd-lookup-base}/{lookup- 969 type}{?d,ep,gp,et,rt,page,count,resource-param} 971 URI Template Variables: 973 rd-lookup-base := RD Lookup Function Set path (mandatory). This 974 is the path of the RD Lookup Function Set. An RD SHOULD use the 975 value "rd-lookup" for this variable whenever possible. 977 lookup-type := ("d", "ep", "res", "gp") (mandatory) This variable 978 is used to select the kind of lookup to perform (domain, 979 endpoint, resource, or group). 981 ep := Endpoint (optional). Used for endpoint, group and resource 982 lookups. 984 d := Domain (optional). Used for domain, group, endpoint and 985 resource lookups. 987 page := Page (optional). Parameter can not be used without the 988 count parameter. Results are returned from result set in pages 989 that contains 'count' results starting from index (page * 990 count). 992 count := Count (optional). Number of results is limited to this 993 parameter value. If the parameter is not present, then an RD 994 implementation specific default value SHOULD be used. 996 rt := Resource type (optional). Used for group, endpoint and 997 resource lookups. 999 et := Endpoint type (optional). Used for group, endpoint and 1000 resource lookups. 1002 resource-param := Link attribute parameters (optional). Any link 1003 attribute as defined in Section 4.1 of [RFC6690], used for 1004 resource lookups. 1006 The following responses codes are defined for this interface: 1008 Success: 2.05 "Content" with an "application/link-format" or 1009 "application/link-format+json" payload containing a matching 1010 entries for the lookup. 1012 Failure: 4.04 "Not Found" in case no matching entry is found for a 1013 unicast request. 1015 Failure: No error response to a multicast request. 1017 Failure: 4.00 "Bad Request". Malformed request. 1019 Failure: 5.03 "Service Unavailable". Service could not perform the 1020 operation. 1022 The following example shows a client performing a resource lookup: 1024 Client RD 1025 | | 1026 | ----- GET /rd-lookup/res?rt=temperature -----------------> | 1027 | | 1028 | | 1029 | <-- 2.05 Content ;rt="temperature" | 1030 | | 1032 Req: GET /rd-lookup/res?rt=temperature 1034 Res: 2.05 Content 1035 ;rt="temperature" 1037 The following example shows a client performing an endpoint type 1038 lookup: 1040 Client RD 1041 | | 1042 | ----- GET /rd-lookup/ep?et=power-node --------------------> | 1043 | | 1044 | | 1045 | <-- 2.05 Content ;ep="node5" ------------ | 1046 | | 1048 Req: GET /rd-lookup/ep?et=power-node 1050 Res: 2.05 Content 1051 ;ep="node5", 1052 ;ep="node7" 1054 The following example shows a client performing a domain lookup: 1056 Client RD 1057 | | 1058 | ----- GET /rd-lookup/d ----------------------------------> | 1059 | | 1060 | | 1061 | <-- 2.05 Content ;d=domain1,;d=domain2 ---------- | 1062 | | 1064 Req: GET /rd-lookup/d 1066 Res: 2.05 Content 1067 ;d="domain1", 1068 ;d="domain2" 1070 The following example shows a client performing a group lookup for 1071 all groups: 1073 Client RD 1074 | | 1075 | ----- GET /rd-lookup/gp ---------------------------------> | 1076 | | 1077 | | 1078 | <-- 2.05 Content ;gp="lights1"; ------------- | 1079 | d="example.com" ------------- | 1080 | | 1082 Req: GET /rd-lookup/gp 1084 Res: 2.05 Content 1085 ;gp="lights1";d="example.com" 1087 The following example shows a client performing a lookup for all 1088 endpoints in a particular group: 1090 Client RD 1091 | | 1092 | ----- GET /rd-lookup/ep?gp=lights1-----------------------> | 1093 | | 1094 | | 1095 | <-- 2.05 Content ;ep="node1" ---------- | 1096 | | 1098 Req: GET /rd-lookup/ep?gp=lights1 1100 Res: 2.05 Content 1101 ;ep="node1", 1102 ;ep="node2", 1104 The following example shows a client performing a lookup for all 1105 groups an endpoint belongs to: 1107 Client RD 1108 | | 1109 | ----- GET /rd-lookup/gp?ep=node1 ------------------------> | 1110 | | 1111 | | 1112 | <-- 2.05 Content ;gp="lights1";ep="node1" | 1113 | | 1115 Req: GET /rd-lookup/gp?ep=node1 1117 Res: 2.05 Content 1118 ;gp="lights1";ep="node1", 1120 8. New Link-Format Attributes 1122 When using the CoRE Link Format to describe resources being 1123 discovered by or posted to a resource directory service, additional 1124 information about those resources is useful. This specification 1125 defines the following new attributes for use in the CoRE Link Format 1126 [RFC6690]: 1128 link-extension = ( "ins" "=" quoted-string ) ; Max 63 bytes 1129 link-extension = ( "exp" ) 1131 8.1. Resource Instance attribute 'ins' 1133 The Resource Instance "ins" attribute is an identifier for this 1134 resource, which makes it possible to distinguish it from other 1135 similar resources. This attribute is similar in use to the 1136 portion of a DNS-SD record (see Section 9.1, and SHOULD be 1137 unique across resources with the same Resource Type attribute in the 1138 domain it is used. A Resource Instance might be a descriptive string 1139 like "Ceiling Light, Room 3", a short ID like "AF39" or a unique UUID 1140 or iNumber. This attribute is used by a Resource Directory to 1141 distinguish between multiple instances of the same resource type 1142 within the directory. 1144 This attribute MUST be no more than 63 bytes in length. The resource 1145 identifier attribute MUST NOT appear more than once in a link 1146 description. 1148 8.2. Export attribute 'exp' 1150 The Export "exp" attribute is used as a flag to indicate that a link 1151 description MAY be exported by a resource directory to external 1152 directories. 1154 The CoRE Link Format is used for many purposes between CoAP 1155 endpoints. Some are useful mainly locally, for example checking the 1156 observability of a resource before accessing it, determining the size 1157 of a resource, or traversing dynamic resource structures. However, 1158 other links are very useful to be exported to other directories, for 1159 example the entry point resource to a functional service. 1161 9. DNS-SD Mapping 1163 CoRE Resource Discovery is intended to support fine-grained discovery 1164 of hosted resources, their attributes, and possibly other resource 1165 relations [RFC6690]. In contrast, service discovery generally refers 1166 to a coarse-grained resolution of an endpoint's IP address, port 1167 number, and protocol. 1169 Resource and service discovery are complementary in the case of large 1170 networks, where the latter can facilitate scaling. This document 1171 defines a mapping between CoRE Link Format attributes and DNS-Based 1172 Service Discovery [RFC6763] fields that permits discovery of CoAP 1173 services by either means. 1175 9.1. DNS-based Service discovery 1177 DNS-Based Service Discovery (DNS-SD) defines a conventional method of 1178 configuring DNS PTR, SRV, and TXT resource records to facilitate 1179 discovery of services (such as CoAP servers in a subdomain) using the 1180 existing DNS infrastructure. This section gives a brief overview of 1181 DNS-SD; see [RFC6763] for a detailed specification. 1183 DNS-SD service names are limited to 255 octets and are of the form: 1185 Service Name = ... 1187 The service name is the label of SRV/TXT resource records. The SRV 1188 RR specifies the host and the port of the endpoint. The TXT RR 1189 provides additional information. 1191 The part of the service name is identical to the global (DNS 1192 subdomain) part of the authority in URIs that identify servers or 1193 groups of servers. 1195 The part is composed of at least two labels. The first 1196 label of the pair is the application protocol name [RFC6335] preceded 1197 by an underscore character. The second label indicates the transport 1198 and is always "_udp" for UDP-based CoAP services. In cases where 1199 narrowing the scope of the search may be useful, these labels may be 1200 optionally preceded by a subtype name followed by the "_sub" label. 1201 An example of this more specific is 1202 "lamp._sub._dali._udp". 1204 The default part of the service name may be set at the 1205 factory or during the commissioning process. It SHOULD uniquely 1206 identify an instance of within a . Taken 1207 together, these three elements comprise a unique name for an SRV/ TXT 1208 record pair within the DNS subdomain. 1210 The granularity of a service name MAY be that of a host or group, or 1211 it could represent a particular resource within a CoAP server. The 1212 SRV record contains the host name (AAAA record name) and port of the 1213 service while protocol is part of the service name. In the case 1214 where a service name identifies a particular resource, the path part 1215 of the URI must be carried in a corresponding TXT record. 1217 A DNS TXT record is in practice limited to a few hundred octets in 1218 length, which is indicated in the resource record header in the DNS 1219 response message. The data consists of one or more strings 1220 comprising a key=value pair. By convention, the first pair is 1221 txtver= (to support different versions of a service 1222 description). 1224 9.2. mapping ins to 1226 The Resource Instance "ins" attribute maps to the part of 1227 a DNS-SD service name. It is stored directly in the DNS as a single 1228 DNS label of canonical precomposed UTF-8 [RFC3629] "Net-Unicode" 1229 (Unicode Normalization Form C) [RFC5198] text. However, to the 1230 extent that the "ins" attribute may be chosen to match the DNS host 1231 name of a service, it SHOULD use the syntax defined in Section 3.5 of 1232 [RFC1034] and Section 2.1 of [RFC1123]. 1234 The part of the name of a service being offered on the 1235 network SHOULD be configurable by the user setting up the service, so 1236 that he or she may give it an informative name. However, the device 1237 or service SHOULD NOT require the user to configure a name before it 1238 can be used. A sensible choice of default name can allow the device 1239 or service to be accessed in many cases without any manual 1240 configuration at all. The default name should be short and 1241 descriptive, and MAY include a collision-resistant substring such as 1242 the lower bits of the device's MAC address, serial number, 1243 fingerprint, or other identifier in an attempt to make the name 1244 relatively unique. 1246 DNS labels are currently limited to 63 octets in length and the 1247 entire service name may not exceed 255 octets. 1249 9.3. Mapping rt to 1251 The resource type "rt" attribute is mapped into the 1252 part of a DNS-SD service name and SHOULD conform to the reg-rel-type 1253 production of the Link Format defined in Section 2 of [RFC6690]. The 1254 "rt" attribute MUST be composed of at least a single Net-Unicode text 1255 string, without underscore '_' or period '.' and limited to 15 octets 1256 in length, which represents the application protocol name. This 1257 string is mapped to the DNS-SD by prepending an 1258 underscore and appending a period followed by the "_udp" label. For 1259 example, rt="dali" is mapped into "_dali._udp". 1261 The application protocol name may be optionally followed by a period 1262 and a service subtype name consisting of a Net-Unicode text string, 1263 without underscore or period and limited to 63 octets. This string 1264 is mapped to the DNS-SD by appending a period followed 1265 by the "_sub" label and then appending a period followed by the 1266 service type label pair derived as in the previous paragraph. For 1267 example, rt="dali.light" is mapped into "light._sub._dali._udp". 1269 The resulting string is used to form labels for DNS-SD records which 1270 are stored directly in the DNS. 1272 9.4. Domain mapping 1274 DNS domains may be derived from the "d" attribute. The domain 1275 attribute may be suffixed with the zone name of the authoritative DNS 1276 server to generate the domain name. The "ep" attribute is prefixed 1277 to the domain name to generate the FQDN to be stored into DNS with an 1278 AAAA RR. 1280 9.5. TXT Record key=value strings 1282 A number of [RFC6763] key/value pairs are derived from link-format 1283 information, to be exported in the DNS-SD as key=value strings in a 1284 TXT record ([RFC6763], Section 6.3). 1286 The resource is exported as key/value pair "path=". 1288 The Interface Description "if" attribute is exported as key/value 1289 pair "if=". 1291 The DNS TXT record can be further populated by importing any other 1292 resource description attributes as they share the same key=value 1293 format specified in Section 6 of [RFC6763]. 1295 9.6. Importing resource links into DNS-SD 1297 Assuming the ability to query a Resource Directory or multicast a GET 1298 (?exp) over the local link, CoAP resource discovery may be used to 1299 populate the DNS-SD database in an automated fashion. CoAP resource 1300 descriptions (links) can be exported to DNS-SD for exposure to 1301 service discovery by using the Resource Instance attribute as the 1302 basis for a unique service name, composed with the Resource Type as 1303 the , and registered in the correct . The agent 1304 responsible for exporting records to the DNS zone file SHOULD be 1305 authenticated to the DNS server. The following example shows an 1306 agent discovering a resource to be exported: 1308 Agent RD 1309 | | 1310 | --- GET /rd-lookup/res?exp ------------------------------> | 1311 | | 1312 | | 1313 | <-- 2.05 Content ";exp; | 1314 | rt="dali.light";ins="FrontSpot" | 1315 | d="office";ep="node1" | 1316 | | 1318 Req: GET /rd-lookup/res?exp 1320 Res: 2.05 Content 1321 ; 1322 exp;rt="dali.light";ins="Spot"; 1323 d="office"; ep="node1" 1325 The agent subsequently registers the following DNS-SD RRs, assuming a 1326 zone name "example.com" prefixed with "office": 1328 node1.office.example.com. IN AAAA FDFD::1234 1329 _dali._udp.office.example.com IN PTR 1330 Spot._dali._udp.office.example.com 1331 light._sub._dali._udp.example.com IN PTR 1332 Spot._dali._udp.office.example.com 1333 Spot._dali._udp.office.example.com IN SRV 0 0 5678 1334 node1.office.example.com. 1335 Spot._dali._udp.office.example.com IN TXT 1336 txtver=1;path=/light/1 1338 In the above figure the Service Name is chosen as 1339 Spot._dali._udp.office.example.com without the light._sub service 1340 prefix. An alternative Service Name would be: 1341 Spot.light._sub._dali._udp.office.example.com. 1343 10. Security Considerations 1345 The security considerations as described in Section 7 of [RFC5988] 1346 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1347 may be protected e.g. using DTLS when hosted on a CoAP server as 1348 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1349 all resource directory interfaces defined in this document. 1351 10.1. Endpoint Identification and Authentication 1353 An Endpoint is determined to be unique by an RD by the Endpoint 1354 identifier parameter included during Registration, and any associated 1355 TLS or DTLS security bindings. An Endpoint MUST NOT be identified by 1356 its protocol, port or IP address as these may change over the 1357 lifetime of an Endpoint. 1359 Every operation performed by an Endpoint or Client on a resource 1360 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1361 Public Key or Certificate based security. Endpoints using a 1362 Certificate MUST include the Endpoint identifier as the Subject of 1363 the Certificate, and this identifier MUST be checked by a resource 1364 directory to match the Endpoint identifier included in the 1365 Registration message. 1367 10.2. Access Control 1369 Access control SHOULD be performed separately for the RD Function Set 1370 and the RD Lookup Function Set, as different endpoints may be 1371 authorized to register with an RD from those authorized to lookup 1372 endpoints from the RD. Such access control SHOULD be performed in as 1373 fine-grained a level as possible. For example access control for 1374 lookups could be performed either at the domain, endpoint or resource 1375 level. 1377 10.3. Denial of Service Attacks 1379 Services that run over UDP unprotected are vulnerable to unknowingly 1380 become part of a DDoS attack as UDP does not require return 1381 routability check. Therefore, an attacker can easily spoof the 1382 source IP of the target entity and send requests to such a service 1383 which would then respond to the target entity. This can be used for 1384 large-scale DDoS attacks on the target. Especially, if the service 1385 returns a response that is order of magnitudes larger than the 1386 request, the situation becomes even worse as now the attack can be 1387 amplified. DNS servers have been widely used for DDoS amplification 1388 attacks. Recently, it has been observed that NTP Servers, that also 1389 run on unprotected UDP have been used for DDoS attacks 1390 (http://tools.cisco.com/security/center/content/CiscoSecurityNotice/ 1391 CVE-2013-5211) since there is no return routability check and can 1392 have a large amplification factor. The responses from the NTP server 1393 were found to be 19 times larger than the request. A Resource 1394 Directory (RD) which responds to wild-card lookups is potentially 1395 vulnerable if run with CoAP over UDP. Since there is no return 1396 routability check and the responses can be significantly larger than 1397 requests, RDs can unknowingly become part of a DDoS amplification 1398 attack. Therefore, it is RECOMMENDED that implementations ensure 1399 return routability. This can be done, for example by responding to 1400 wild card lookups only over DTLS or TLS or TCP. 1402 11. IANA Considerations 1404 11.1. Resource Types 1406 "core.rd", "core.rd-group" and "core.rd-lookup" resource types need 1407 to be registered with the resource type registry defined by 1408 [RFC6690]. 1410 11.2. Link Extension 1412 The "exp" attribute needs to be registered when a future Web Linking 1413 link-extension registry is created (e.g. in RFC5988bis). 1415 11.3. RD Parameter Registry 1417 This specification defines a new sub-registry for registration and 1418 lookup parameters called "RD Parameters" under "CoRE Parameters". 1419 Although this specification defines a basic set of parameters, it is 1420 expected that other standards that make use of this interface will 1421 define new ones. 1423 Each entry in the registry must include the human readable name of 1424 the parameter, the query parameter, validity requirements if any and 1425 a description. The query parameter MUST be a valid URI query key 1426 [RFC3986]. 1428 Initial entries in this sub-registry are as follows: 1430 +----------+-------+---------------+--------------------------------+ 1431 | Name | Query | Validity | Description | 1432 +----------+-------+---------------+--------------------------------+ 1433 | Endpoint | ep | | Name of the endpoint | 1434 | Name | | | | 1435 | Lifetime | lt | 60-4294967295 | Lifetime of the registration | 1436 | | | | in seconds | 1437 | Domain | d | | Domain to which this endpoint | 1438 | | | | belongs | 1439 | Endpoint | et | | Semantic name of the endpoint | 1440 | Type | | | | 1441 | Context | con | URI | The scheme, address and port | 1442 | | | | at which this server is | 1443 | | | | available | 1444 | Endpoint | ep | | Name of the endpoint, max 63 | 1445 | Name | | | bytes | 1446 | Group | gp | | Name of a group in the RD | 1447 | Name | | | | 1448 | Page | page | Integer | Used for pagination | 1449 | Count | count | Integer | Used for pagination | 1450 +----------+-------+---------------+--------------------------------+ 1452 Table 1: RD Parameters 1454 The IANA policy for future additions to the sub-registry is "Expert 1455 Review" as described in [RFC5226]. 1457 12. Examples 1459 Examples are added here. 1461 12.1. Lighting Installation 1463 This example shows a simplified lighting installation which makes use 1464 of the Resource Directory (RD) to facilitate the installation and 1465 start up of the application code in the lights and sensors. In 1466 particular, the example leads to the definition of a group and the 1467 enabling of the corresponding multicast address. No conclusions must 1468 be drawn on the realization of actual installation procedures, 1469 because the example "emphasizes" some of the issues that may 1470 influence the use of the RD. 1472 12.1.1. Installation Characteristics 1474 The example assumes that the installation is managed. That means 1475 that a Commissioning Tool (CT) is used to authorize the addition of 1476 nodes, name them, and name their services. The CT can be connected 1477 to the installation in many ways: the CT can be part of the 1478 installation network, connected by wifi to the installation network, 1479 or connected via GPRS link, or other method. 1481 It is assumed that there are two naming authorities for the 1482 installation: (1) the network manager that is responsible for the 1483 correct operation of the network and the connected interfaces, and 1484 (2) the lighting manager that is responsible for the correct 1485 functioning of networked lights and sensors. The result is the 1486 existence of two naming schemes coming from the two managing 1487 entities. 1489 The example installation consists of one presence sensor, and two 1490 luminaries, luminary1 and luminary2, each with their own wireless 1491 interface. Each luminary contains three lamps: left, right and 1492 middle. Each luminary is accessible through one end-point. For each 1493 lamp a resource exists to modify the settings of a lamp in a 1494 luminary. The purpose of the installation is that the presence 1495 sensor notifies the presence of persons to a group of lamps. The 1496 group of lamps consists of: middle and left lamps of luminary1 and 1497 right lamp of luminary2. 1499 Before commissioning by the lighting manager, the network is 1500 installed and access to the interfaces is proven to work by the 1501 network manager. Following the lay-out of cables and routers the 1502 network manager has defined DNS domains. The presence sensor and 1503 luminary1 are part of DNS domain: rtr_5612_rrt.example.com and 1504 luminary2 is part of rtr_7899_pfa.example.com. The names of 1505 luminary1- luminary2-, and sensor- interfaces are respectively: 1506 lm_12-345-678, lm_12-456-378, and sn_12-345-781. These names are 1507 stored in DNS together with their IP addresses. The FQDN of the 1508 interfaces is shown in Table 2 below: 1510 +--------------------+----------------------------------------+ 1511 | Name | FQDN | 1512 +--------------------+----------------------------------------+ 1513 | luminary1 | lm_12-345-678.rtr_5612_rrt.example.com | 1514 | luminary2 | lm_12-456-378.rtr_7899_pfa.example.com | 1515 | Presence sensor | sn_12-345-781.rtr_5612_rrt.example.com | 1516 | Resource directory | pc_123456.rtr_5612_rrt.example.com | 1517 +--------------------+----------------------------------------+ 1519 Table 2: interface FQDNs 1521 At the moment of installation, the network under installation is not 1522 necessarily connected to the DNS infra structure. Therefore, SLAAC 1523 IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in 1524 Table 3 below: 1526 +--------------------+--------------+ 1527 | Name | IPv6 address | 1528 +--------------------+--------------+ 1529 | luminary1 | FDFD::ABCD:1 | 1530 | luminary2 | FDFD::ABCD:2 | 1531 | Presence sensor | FDFD::ABCD:3 | 1532 | Resource directory | FDFD::ABCD:0 | 1533 +--------------------+--------------+ 1535 Table 3: interface SLAAC addresses 1537 In Section 12.1.2 the use of resource directory during installation 1538 is presented. In Section 12.1.3 the connection to DNS is discussed. 1540 12.1.2. RD entries 1542 It is assumed that access to the DNS infrastructure is not always 1543 possible during installation. Therefore, the SLAAC addresses are 1544 used in this section. 1546 For discovery, the resource types (rt) of the devices are important. 1547 The lamps in the luminaries have rt: light, and the presence sensor 1548 has rt: p-sensor. The end-points have names which are relevant to 1549 the light installation manager. In this case luminary1, luminary2, 1550 and the presence sensor are located in room 2-4-015, where luminary1 1551 is located at the window and luminary2 and the presence sensor are 1552 located at the door. The end-point names reflect this physical 1553 location. The middle, left and right lamps are accessed via path 1554 /light/middle, /light/left, and /light/right respectively. The 1555 identifiers relevant to the Resource Directory are shown in Table 4 1556 below: 1558 +----------------+------------------+---------------+---------------+ 1559 | Name | end-point | resource path | resource type | 1560 +----------------+------------------+---------------+---------------+ 1561 | luminary1 | lm_R2-4-015_wndw | /light/left | light | 1562 | luminary1 | lm_R2-4-015_wndw | /light/middle | light | 1563 | luminary1 | lm_R2-4-015_wndw | /light/right | light | 1564 | luminary2 | lm_R2-4-015_door | /light/left | light | 1565 | luminary2 | lm_R2-4-015_door | /light/middle | light | 1566 | luminary2 | lm_R2-4-015_door | /light/right | light | 1567 | Presence | ps_R2-4-015_door | /ps | p-sensor | 1568 | sensor | | | | 1569 +----------------+------------------+---------------+---------------+ 1571 Table 4: Resource Directory identifiers 1573 The CT inserts the end-points of the luminaries and the sensor in the 1574 RD using the Context parameter (con) to specify the interface 1575 address: 1577 Req: POST 1578 coap://[FDFD::ABCD:0]/rd?ep=lm_R2-4-015_wndw 1579 Payload: 1580 ;rt="light"; 1581 con="FDFD::ABCD:1"; 1582 d="R2-4-015"; ins="lamp4444"; exp, 1583 ;rt="light"; 1584 con="FDFD::ABCD:1"; 1585 d="R2-4-015"; ins="lamp5555"; exp, 1586 ;rt="light"; 1587 con="FDFD::ABCD:1"; 1588 d="R2-4-015"; ins="lamp6666"; exp 1590 Res: 2.01 Created 1591 Location: /rd/4521 1593 Req: POST coap://[FDFD::ABCD:0]/rd?ep=lm_R2-4-015_door 1594 Payload: 1595 ;rt="light"; 1596 con="FDFD::ABCD:2"; 1597 d="R2-4-015"; ins="lamp1111"; exp, 1598 ;rt="light"; 1599 con="FDFD::ABCD:2"; 1600 d="R2-4-015"; ins="lamp2222"; exp, 1601 ;rt="light"; 1602 con="FDFD::ABCD:2"; 1603 d="R2-4-015"; ins="lamp3333"; exp 1605 Res: 2.01 Created 1606 Location: /rd/4522 1608 Req: POST coap://[FDFD::ABCD:0]/rd?ep=ps_R2-4-015_door 1609 Payload: 1610 ;rt="p-sensor"; 1611 con="FDFD::ABCD:3"; 1612 d="R2-4-015"; ins="pres1234"; exp 1614 Res: 2.01 Created 1615 Location: /rd/4523 1617 The domain name d="R2-4-015" has been added for an efficient lookup 1618 because filtering on "ep" name is awkward. The same domain name is 1619 communicated to the two luminaries and the presence sensor by the CT. 1621 The "exp" attribute is set for the later administration in DNS of the 1622 instance name ins="lampxxxx". 1624 Once the individual endpoints are registered, the group needs to be 1625 registered. Because the presence sensor sends one multicast message 1626 to the luminaries, all lamps in the group need to have an identical 1627 path. This path is created on the two luminaries using the batch 1628 command defined in [I-D.ietf-core-interfaces]. The path to a batch 1629 of lamps is defined as: /light/grp1. In the example below, two 1630 endpoints are updated with an additional resource using the path 1631 /light/grp1 on the two luminaries. 1633 Req: POST 1634 coap://[FDFD::ABCD:1]/light/grp1 1635 (content-type:application/link-format)light/middle, light/left 1637 Res: 2.04 Changed 1639 Req: POST 1640 coap://[FDFD::ABCD:2]/light/grp1 1641 (content-type:application/link-format)light/right 1643 Res: 2.04 Changed 1645 The group is specified in the RD. The Context parameter is set to 1646 the site-local multicast address allocated to the group. In the POST 1647 in the example below, these two end-points and the end-point of the 1648 presence sensor are registered as members of the group. 1650 It is expected that Standards Developing Organization (SDO) may 1651 develop other special purpose protocols to specify additional group 1652 links, group membership, group names and other parameters in the 1653 individual nodes. 1655 Req: POST coap://[FDFD::ABCD:0]/rd-group 1656 ?gp=grp_R2-4-015;con="FF05::1";exp; ins="grp1234" 1657 Payload: 1658 <>ep=lm_R2-4-015_wndw, 1659 <>ep=lm_R2-4-015_door, 1660 <>ep=ps_R2-4-015_door 1662 Res: 2.01 Created 1663 Location: /rd-group/501 1665 After the filling of the RD by the CT, the application in the 1666 luminaries can learn to which groups they belong, and enable their 1667 interface for the multicast address. 1669 The luminary, knowing its domain, queries the RD for the end-point 1670 with rt=light and d=R2-4-015. The RD returns all end-points in the 1671 domain. 1673 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep 1674 ?d=R2-4-015; rt=light 1676 Res: 2.05 Content 1677 ; 1678 ep="lm_R2-4-015_wndw", 1679 ; 1680 ep="lm_R2-4-015_door" 1682 Knowing its own IPv6 address, the luminary discovers its endpoint 1683 name. With the end-point name the luminary queries the RD for all 1684 groups to which the end-point belongs. 1686 Req: GET coap://[FDFD::ABCD:0]/rd-lookup/gp 1687 ?ep=lm_R2-4-015_wndw 1689 Res: 2.05 Content 1690 ; exp; gp="grp_R2-4-015; ins="grp1234"; 1798 ep="lm_R2-4-015_wndw"; 1799 ep="lm_R2-4-015_door 1801 The group with FQDN grp_R2-4-015.bc.example.com can be entered into 1802 the DNS by the agent. The accompanying instance name is grp1234. 1803 The is chosen to be _group._udp. The agent enters the 1804 following RRs into the DNS. 1806 grp_R2-4-015.bc.example.com. IN AAAA FF05::1 1807 _group._udp.bc.example.com IN PTR 1808 grp1234._group._udp.bc.example.com 1809 grp1234._group._udp.bc.example.com IN SRV 0 0 5678 1810 grp_R2-4-015_door.bc.example.com. 1811 grp1234._group._udp.bc.example.com IN TXT 1812 txtver=1;path=/light/grp1 1814 12.1.4. RD Operation 1816 The specification of the group can be used by devices other than the 1817 luminaries and the sensor to learn the multicast address of the group 1818 in a given room. For example a smart phone may be used to adjust the 1819 lamps in the room. 1821 After entry into the room, on request of the user, the smart phone 1822 queries the presence of RDs and may display all the domain names 1823 found on the RDs. The user can, for example, scroll all domains 1824 (room names in this case) and select the room that he entered. After 1825 selection the phone shows all groups in the selected room with their 1826 members. Selecting a group, the user can dim, switch on/off the 1827 group of lights, or possibly even create temporary new groups. 1829 In all examples the SLAAC IPv6 address can be exchanged with the 1830 FQDN, when a connection to DNS exists. Using the FQDN, a node learns 1831 the interface's IPv6 address, or the group's multicast address from 1832 DNS. In the same way the presence sensor can learn the multicast 1833 address to which it should send its presence messages. 1835 12.2. OMA Lightweight M2M (LWM2M) Example 1837 This example shows how the OMA LWM2M specification makes use of 1838 Resource Directory (RD). 1840 OMA LWM2M is a profile for device services based on CoAP, CoRE RD, 1841 and other IETF RFCs and drafts. LWM2M defines a simple object model 1842 and a number of abstract interfaces and operations for device 1843 management and device service enablement. 1845 An LWM2M server is an instance of an LWM2M middleware service layer, 1846 containing a Resource Directory along with other LWM2M interfaces 1847 defined by the LWM2M specification. 1849 CoRE Resource Directory (RD) is used to provide the LWM2M 1850 Registration interface. 1852 LWM2M does not provide for registration domains and does not 1853 currently use the rd-group or rd-lookup interfaces. 1855 The LWM2M specification describes a set of interfaces and a resource 1856 model used between a LWM2M device and an LWM2M server. Other 1857 interfaces, proxies, applications, and function sets are currently 1858 out of scope for LWM2M. 1860 The location of the LWM2M Server and RD Function Set is provided by 1861 the LWM2M Bootstrap process, so no dynamic discovery of the RD 1862 function set is used. LWM2M Servers and endpoints are not required 1863 to implement the ./well-known/core resource. 1865 12.2.1. The LWM2M Object Model 1867 The OMA LWM2M object model is based on a simple 2 level class 1868 hierarchy consisting of Objects and Resources. 1870 An LWM2M Resource is a REST endpoint, allowed to be a single value or 1871 an array of values of the same data type. 1873 An LWM2M Object is a resource template and container type that 1874 encapsulates a set of related resources. An LWM2M Object represents 1875 a specific type of information source; for example, there is a LWM2M 1876 Device Management object that represents a network connection, 1877 containing resources that represent individual properties like radio 1878 signal strength. 1880 Since there may potentially be more than one of a given type object, 1881 for example more than one network connection, LWM2M defines instances 1882 of objects that contain the resources that represent a specific 1883 physical thing. 1885 The URI template for LWM2M consists of a base URI followed by Object, 1886 Instance, and Resource IDs: 1888 /{base-uri}/{object-id}/{instance-id}/{resource-id} 1890 LWM2M IDs are 16 bit numbers represented in decimal by URI format 1891 strings. For example, a LWM2M URI might be: 1893 /1/0/1 1895 The base uri is "/", the Object ID is 1, the instance ID is 0, and 1896 the resource ID is 1. This example URI points to internal resource 1897 1, which represents the registration lifetime configured, in instance 1898 0 of a type 1 object (LWM2M Server Object). 1900 12.2.2. LWM2M Register Endpoint 1902 LWM2M defines a registration interface based on the Resource 1903 Directory Function Set, described in Section 5. The URI of the LWM2M 1904 Resource Directory function set is specified to be "/rd" as 1905 recommended in Section 5.2. 1907 LWM2M endpoints register object IDs, for example , to indicate 1908 that a particular object type is supported, and register object 1909 instances, for example , to indicate that a particular instance 1910 of that object type exists. 1912 Resources within the LWM2M object instance are not registered with 1913 the RD, but may be discovered by reading the resource links from the 1914 object instance using GET with a CoAP Content-Format of application/ 1915 link-format. Resources may also be read as a structured object by 1916 performing a GET to the object instance with a Content-Format of 1917 senml+json. 1919 When an LWM2M object or instance is registered, this indicates to the 1920 LWM2M server that the object and it's resources are available for 1921 management and service enablement (REST API) operations. 1923 LWM2M endpoints may use the following RD registration parameters as 1924 defined in Table 1 : 1926 ep - Endpoint Name 1927 lt - registration lifetime 1929 Endpoint Name is mandatory, all other registration parameters are 1930 optional. 1932 Additional optional LWM2M registration parameters are defined: 1934 +------------+-------+-------------------------------+--------------+ 1935 | Name | Query | Validity | Description | 1936 +------------+-------+-------------------------------+--------------+ 1937 | Protocol | b | {"U",UQ","S","SQ","US","UQS"} | Available | 1938 | Binding | | | Protocols | 1939 | | | | | 1940 | LWM2M | ver | 1.0 | Spec Version | 1941 | Version | | | | 1942 | | | | | 1943 | SMS Number | sms | | MSISDN | 1944 +------------+-------+-------------------------------+--------------+ 1946 Table 5: LWM2M Additional Registration Parameters 1948 The following RD registration parameters are not currently specified 1949 for use in LWM2M: 1951 et - Endpoint Type 1952 con - Context 1954 The endpoint registration must include a payload containing links to 1955 all supported objects and existing object instances, optionally 1956 including the appropriate link-format relations. 1958 Here is an example LWM2M registration payload: 1960 ,,, 1962 This link format payload indicates that object ID 1 (LWM2M Server 1963 Object) is supported, with a single instance 0 existing, object ID 3 1964 (LWM2M Device object) is supported, with a single instance 0 1965 existing, and object 5 (LWM2M Firmware Object) is supported, with no 1966 existing instances. 1968 12.2.3. Alternate Base URI 1970 If the LWM2M endpoint exposes objects at a base URI other that "/", 1971 the endpoint must register the base URI using rt="oma.lwm2m". An 1972 example link payload using alternate base URI would be: 1974 ;rt="oma.lwm2m",,, 1976 This link payload indicates that the lwm2m objects will be placed 1977 under the base URI "/my_lwm2m" and that object ID 1 (server) is 1978 supported, with a single instance 0 existing, and object 5 (firmware 1979 update) is supported. 1981 12.2.4. LWM2M Update Endpoint Registration 1983 An LWM2M Registration update proceeds as described in Section 5.3, 1984 and adds some optional parameter updates: 1986 lt - Registration Lifetime 1987 b - Protocol Binding 1988 sms - MSISDN 1989 link payload - new or modified links 1991 A Registration update is also specified to be used to update the 1992 LWM2M server whenever the endpoint's UDP port or IP address are 1993 changed. 1995 12.2.5. LWM2M De-Register Endpoint 1997 LWM2M allows for de-registration using the delete method on the 1998 returned location from the initial registration operation. LWM2M de- 1999 registration proceeds as described in Section 5.4. 2001 13. Acknowledgments 2003 Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Brandt, 2004 Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have provided 2005 helpful comments, discussions and ideas to improve and shape this 2006 document. Zach would also like to thank his colleagues from the EU 2007 FP7 SENSEI project, where many of the resource directory concepts 2008 were originally developed. 2010 14. Changelog 2012 Changes from -02 to -03: 2014 o Added an example for lighting and DNS integration 2016 o Added an example for RD use in OMA LWM2M 2018 o Added Read Links operation for link inspection by endpoints 2020 o Expanded DNS-SD section 2022 o Added draft authors Peter van der Stok and Michael Koster 2024 Changes from -01 to -02: 2026 o Added a catalogue use case. 2028 o Changed the registration update to a POST with optional link 2029 format payload. Removed the endpoint type update from the update. 2031 o Additional examples section added for more complex use cases. 2033 o New DNS-SD mapping section. 2035 o Added text on endpoint identification and authentication. 2037 o Error code 4.04 added to Registration Update and Delete requests. 2039 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 2040 resource type parameters. 2042 Changes from -00 to -01: 2044 o Removed the ETag validation feature. 2046 o Place holder for the DNS-SD mapping section. 2048 o Explicitly disabled GET or POST on returned Location. 2050 o New registry for RD parameters. 2052 o Added support for the JSON Link Format. 2054 o Added reference to the Groupcomm WG draft. 2056 Changes from -05 to WG Document -00: 2058 o Updated the version and date. 2060 Changes from -04 to -05: 2062 o Restricted Update to parameter updates. 2064 o Added pagination support for the Lookup interface. 2066 o Minor editing, bug fixes and reference updates. 2068 o Added group support. 2070 o Changed rt to et for the registration and update interface. 2072 Changes from -03 to -04: 2074 o Added the ins= parameter back for the DNS-SD mapping. 2076 o Integrated the Simple Directory Discovery from Carsten. 2078 o Editorial improvements. 2080 o Fixed the use of ETags. 2082 Changes from -02 to -03: 2084 o Changed the endpoint name back to a single registration parameter 2085 ep= and removed the h= and ins= parameters. 2087 o Updated REST interface descriptions to use RFC6570 URI Template 2088 format. 2090 o Introduced an improved RD Lookup design as its own function set. 2092 o Improved the security considerations section. 2094 o Made the POST registration interface idempotent by requiring the 2095 ep= parameter to be present. 2097 Changes from -01 to -02: 2099 o Added a terminology section. 2101 o Changed the inclusion of an ETag in registration or update to a 2102 MAY. 2104 o Added the concept of an RD Domain and a registration parameter for 2105 it. 2107 o Recommended the Location returned from a registration to be 2108 stable, allowing for endpoint and Domain information to be changed 2109 during updates. 2111 o Changed the lookup interface to accept endpoint and Domain as 2112 query string parameters to control the scope of a lookup. 2114 15. References 2116 15.1. Normative References 2118 [I-D.ietf-core-links-json] 2119 Bormann, C., "Representing CoRE Link Collections in JSON", 2120 draft-ietf-core-links-json-02 (work in progress), July 2121 2014. 2123 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2124 Requirement Levels", BCP 14, RFC 2119, March 1997. 2126 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2127 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2128 3986, January 2005. 2130 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2131 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2132 May 2008. 2134 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 2136 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2137 Cheshire, "Internet Assigned Numbers Authority (IANA) 2138 Procedures for the Management of the Service Name and 2139 Transport Protocol Port Number Registry", BCP 165, RFC 2140 6335, August 2011. 2142 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2143 and D. Orchard, "URI Template", RFC 6570, March 2012. 2145 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2146 Format", RFC 6690, August 2012. 2148 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2149 Discovery", RFC 6763, February 2013. 2151 15.2. Informative References 2153 [I-D.ietf-core-interfaces] 2154 Shelby, Z. and M. Vial, "CoRE Interfaces", draft-ietf- 2155 core-interfaces-02 (work in progress), November 2014. 2157 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2158 STD 13, RFC 1034, November 1987. 2160 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 2161 and Support", STD 3, RFC 1123, October 1989. 2163 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2164 10646", STD 63, RFC 3629, November 2003. 2166 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 2167 Interchange", RFC 5198, March 2008. 2169 [RFC6775] Shelby, Z., Chakrabarti, S., Nordmark, E., and C. Bormann, 2170 "Neighbor Discovery Optimization for IPv6 over Low-Power 2171 Wireless Personal Area Networks (6LoWPANs)", RFC 6775, 2172 November 2012. 2174 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2175 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2176 2014. 2178 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2179 Application Protocol (CoAP)", RFC 7252, June 2014. 2181 [RFC7390] Rahman, A. and E. Dijk, "Group Communication for the 2182 Constrained Application Protocol (CoAP)", RFC 7390, 2183 October 2014. 2185 Authors' Addresses 2187 Zach Shelby 2188 ARM 2189 150 Rose Orchard 2190 San Jose 95134 2191 USA 2193 Phone: +1-408-203-9434 2194 Email: zach.shelby@arm.com 2195 Michael Koster 2196 ARM 2197 150 Rose Orchard 2198 San Jose 95134 2199 USA 2201 Phone: +1-408-576-1500 x11516 2202 Email: Michael.Koster@arm.com 2204 Carsten Bormann 2205 Universitaet Bremen TZI 2206 Postfach 330440 2207 Bremen D-28359 2208 Germany 2210 Phone: +49-421-218-63921 2211 Email: cabo@tzi.org 2213 Peter van der Stok 2214 consultant 2216 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2217 Email: consultancy@vanderstok.org 2218 URI: www.vanderstok.org