idnits 2.17.1 draft-ietf-core-resource-directory-02.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 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 9, 2014) is 3448 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) -- 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 ARM 4 Intended status: Standards Track C. Bormann 5 Expires: May 13, 2015 Universitaet Bremen TZI 6 November 9, 2014 8 CoRE Resource Directory 9 draft-ietf-core-resource-directory-02 11 Abstract 13 In many M2M applications, direct discovery of resources is not 14 practical due to sleeping nodes, disperse networks, or networks where 15 multicast traffic is inefficient. These problems can be solved by 16 employing an entity called a Resource Directory (RD), which hosts 17 descriptions of resources held on other servers, allowing lookups to 18 be performed for those resources. This document specifies the web 19 interfaces that a Resource Directory supports in order for web 20 servers to discover the RD and to register, maintain, lookup and 21 remove resources descriptions. Furthermore, new link attributes 22 useful in conjunction with an RD are defined. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on May 13, 2015. 41 Copyright Notice 43 Copyright (c) 2014 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . . 5 61 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . . 7 62 3.2. Use Case: Home and Building Automation . . . . . . . . . . 7 63 3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 8 64 4. Simple Directory Discovery . . . . . . . . . . . . . . . . . . 8 65 4.1. Finding a Directory Server . . . . . . . . . . . . . . . . 10 66 4.2. Third-party registration . . . . . . . . . . . . . . . . . 10 67 5. Resource Directory Function Set . . . . . . . . . . . . . . . 10 68 5.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 11 69 5.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 13 70 5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 15 71 5.4. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 16 72 6. Group Function Set . . . . . . . . . . . . . . . . . . . . . . 18 73 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . . 18 74 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 20 75 7. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . . 21 76 8. New Link-Format Attributes . . . . . . . . . . . . . . . . . . 25 77 8.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 25 78 8.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . . 26 79 9. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . . 26 80 9.1. DNS-based Service discovery . . . . . . . . . . . . . . . 26 81 9.2. mapping ins to . . . . . . . . . . . . . . . . 27 82 9.3. Mapping rt to . . . . . . . . . . . . . . . 28 83 9.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . . 28 84 9.5. TXT Record key=value strings . . . . . . . . . . . . . . . 28 85 9.6. Importing resource links into DNS-SD . . . . . . . . . . . 29 86 10. Security Considerations . . . . . . . . . . . . . . . . . . . 30 87 10.1. Endpoint Identification and Authentication . . . . . . . . 30 88 10.2. Access Control . . . . . . . . . . . . . . . . . . . . . . 30 89 10.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 31 90 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 91 11.1. Resource Types . . . . . . . . . . . . . . . . . . . . . . 31 92 11.2. Link Extension . . . . . . . . . . . . . . . . . . . . . . 31 93 11.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 32 94 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 95 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33 96 14. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 33 97 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 98 15.1. Normative References . . . . . . . . . . . . . . . . . . . 35 99 15.2. Informative References . . . . . . . . . . . . . . . . . . 36 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 102 1. Introduction 104 The work on Constrained RESTful Environments (CoRE) aims at realizing 105 the REST architecture in a suitable form for the most constrained 106 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 107 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 108 applications such as smart energy and building automation. 110 The discovery of resources offered by a constrained server is very 111 important in machine-to-machine applications where there are no 112 humans in the loop and static interfaces result in fragility. The 113 discovery of resources provided by an HTTP Web Server is typically 114 called Web Linking [RFC5988]. The use of Web Linking for the 115 description and discovery of resources hosted by constrained web 116 servers is specified by the CoRE Link Format [RFC6690]. This 117 specification however only describes how to discover resources from 118 the web server that hosts them by requesting "/.well-known/core". In 119 many M2M scenarios, direct discovery of resources is not practical 120 due to sleeping nodes, disperse networks, or networks where multicast 121 traffic is inefficient. These problems can be solved by employing an 122 entity called a Resource Directory (RD), which hosts descriptions of 123 resources held on other servers, allowing lookups to be performed for 124 those resources. 126 This document specifies the web interfaces that a Resource Directory 127 supports in order for web servers to discover the RD and to register, 128 maintain, lookup and remove resource descriptions. Furthermore, new 129 link attributes useful in conjunction with a Resource Directory are 130 defined. Although the examples in this document show the use of 131 these interfaces with CoAP [RFC7252], they can be applied in an 132 equivalent manner to HTTP [RFC7230]. 134 2. Terminology 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 138 "OPTIONAL" in this document are to be interpreted as described in 139 [RFC2119]. The term "byte" is used in its now customary sense as a 140 synonym for "octet". 142 This specification requires readers to be familiar with all the terms 143 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 144 should also be familiar with the terms and concepts discussed in 145 [RFC7252]. To describe the REST interfaces defined in this 146 specification, the URI Template format is used [RFC6570]. 148 This specification makes use of the following additional terminology: 150 Resource Directory 151 A web entity that stores information about web resources and 152 implements the REST interfaces defined in this specification for 153 registration and lookup of those resources. 155 Domain 156 In the context of a Resource Directory, a domain is a logical 157 grouping of endpoints. This specification assumes that the list 158 of Domains supported by an RD is pre-configured by that RD. When 159 a domain is exported to DNS, the domain value equates to the DNS 160 domain name. 162 Group 163 In the context of a Resource Directory, a group is a logical 164 grouping of endpoints for the purpose of group communications. 165 All groups within a domain are unique. 167 Endpoint 168 Endpoint (EP) is a term used to describe a web server or client in 169 [RFC7252]. In the context of this specification an endpoint is 170 used to describe a web server that registers resources to the 171 Resource Directory. An endpoint is identified by its endpoint 172 name, which is included during registration, and is unique within 173 the associated domain of the registration. 175 3. Architecture and Use Cases 177 The resource directory architecture is illustrated in Figure 1. A 178 Resource Directory (RD) is used as a repository for Web Links 179 [RFC5988] about resources hosted on other web servers, which are 180 called endpoints (EP). An endpoint is a web server associated with a 181 scheme, IP address and port (called Context), thus a physical node 182 may host one or more endpoints. The RD implements a set of REST 183 interfaces for endpoints to register and maintain sets of Web Links 184 (called resource directory entries), and for clients to lookup 185 resources from the RD or maintain groups. Endpoints themselves can 186 also act as clients. An RD can be logically segmented by the use of 187 Domains. The domain an endpoint is associated with can be defined by 188 the RD or configured by an outside entity. This information 189 hierarchy is shown in Figure 2. 191 Endpoints are assumed to proactively register and maintain resource 192 directory entries on the RD, which are soft state and need to be 193 periodically refreshed. An endpoint is provided with interfaces to 194 register, update and remove a resource directory entry. Furthermore, 195 a mechanism to discover an RD using the CoRE Link Format is defined. 196 It is also possible for an RD to proactively discover Web Links from 197 endpoints and add them as resource directory entries. A lookup 198 interface for discovering any of the Web Links held in the RD is 199 provided using the CoRE Link Format. 201 Registration Lookup, Group 202 +----+ | | 203 | EP |---- | | 204 +----+ ---- | | 205 --|- +------+ | 206 +----+ | ----| | | +--------+ 207 | EP | ---------|-----| RD |----|-----| Client | 208 +----+ | ----| | | +--------+ 209 --|- +------+ | 210 +----+ ---- | | 211 | EP |---- | | 212 +----+ 214 Figure 1: The resource directory architecture. 216 +------------+ 217 | Domain | <-- Name 218 +------------+ 219 | | 220 | +------------+ 221 | | Group | <-- Name, IP 222 | +------------+ 223 | | 224 +------------+ 225 | Endpoint | <-- Name, Scheme, IP, Port 226 +------------+ 227 | 228 | 229 +------------+ 230 | Resource | <-- Target, Parameters 231 +------------+ 233 Figure 2: The resource directory information hierarchy. 235 3.1. Use Case: Cellular M2M 237 Over the last few years, mobile operators around the world have 238 focused on development of M2M solutions in order to expand the 239 business to the new type of users: machines. The machines are 240 connected directly to a mobile network using an appropriate embedded 241 air interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short 242 and wide range wireless interfaces. From the system design point of 243 view, the ambition is to design horizontal solutions that can enable 244 utilization of machines in different applications depending on their 245 current availability and capabilities as well as application 246 requirements, thus avoiding silo like solutions. One of the crucial 247 enablers of such design is the ability to discover resources 248 (machines -- endpoints) capable of providing required information at 249 a given time or acting on instructions from the end users. 251 In a typical scenario, during a boot-up procedure (and periodically 252 afterwards), the machines (endpoints) register with a Resource 253 Directory (for example EPs installed on vehicles enabling tracking of 254 their position for fleet management purposes and monitoring 255 environment parameters) hosted by the mobile operator or somewhere 256 else in the network, periodically a description of its own 257 capabilities. Due to the usual network configuration of mobile 258 networks, the EPs attached to the mobile network do not have routable 259 addresses. Therefore, a remote server is usually used to provide 260 proxy access to the EPs. The address of each (proxy) endpoint on 261 this server is included in the resource description stored in the RD. 262 The users, for example mobile applications for environment 263 monitoring, contact the RD, look-up the endpoints capable of 264 providing information about the environment using appropriate set of 265 link parameters, obtain information on how to contact them (URLs of 266 the proxy server) and then initiate interaction to obtain information 267 that is finally processed, displayed on the screen and usually stored 268 in a database. Similarly, fleet management systems provide the 269 appropriate link parameters to the RD to look-up for EPs deployed on 270 the vehicles the application is responsible for. 272 3.2. Use Case: Home and Building Automation 274 Home and commercial building automation systems can benefit from the 275 use of M2M web services. The discovery requirements of these 276 applications are demanding. Home automation usually relies on run- 277 time discovery to commission the system, whereas in building 278 automation a combination of professional commissioning and run-time 279 discovery is used. Both home and building automation involve peer- 280 to-peer interactions between endpoints, and involve battery-powered 281 sleeping devices. 283 The exporting of resource information to other discovery systems is 284 also important in these automation applications. In home automation 285 there is a need to interact with other consumer electronics, which 286 may already support DNS-SD, and in building automation larger 287 resource directories or DNS-SD covering multiple buildings. 289 3.3. Use Case: Link Catalogues 291 Resources may be shared through data brokers that have no knowledge 292 beforehand of who is going to consume the data. Resource Directory 293 can be used to hold links about resources and services hosted 294 anywhere to make them discoverable by a general class of 295 applications. 297 For example, environmental and weather sensors that generate data for 298 public consumption may provide the data to an intermediary server, or 299 broker. Sensor data are published to the intermediary upon changes 300 or at regular intervals. Descriptions of the sensors that resolve to 301 links to sensor data may be published to a Resource Directory. 302 Applications wishing to consume the data can use the Resource 303 Directory lookup function set to discover and resolve links to the 304 desired resources and endpoints. The Resource Directory service need 305 not be coupled with the data intermediary service. Mapping of 306 Resource Directories to data intermediaries may be many-to-many. 308 Metadata in link-format or link-format+json representations are 309 supplied by Resource Directories, which may be internally stored as 310 triples, or relation/attribute pairs providing metadata about 311 resource links. External catalogs that are represented in other 312 formats may be converted to link-format or link-format+json for 313 storage and access by Resource Directories. Since it is common 314 practice for these to be URN encoded, simple and lossless structural 315 transforms will generally be sufficient to store external metadata in 316 Resource Directories. 318 The additional features of Resource Directory allow domains to be 319 defined to enable access to a particular set of resources from 320 particular applications. this provides isolation and protection of 321 sensitive data when needed. Resource groups may defined to allow 322 batched reads from multiple resources. 324 4. Simple Directory Discovery 326 Not all endpoints hosting resources are expected to know how to 327 implement the Resource Directory Function Set (see Section 5) and 328 thus explicitly register with a Resource Directory (or other such 329 directory server). Instead, simple endpoints can implement the 330 generic Simple Directory Discovery approach described in this 331 section. An RD implementing this specification MUST implement Simple 332 Directory Discovery. However, there may be security reasons why this 333 form of directory discovery would be disabled. 335 This approach requires that the endpoint makes available the hosted 336 resources that it wants to be discovered, as links on its 337 "/.well-known/core" interface as specified in [RFC6690]. 339 The endpoint then finds one or more IP addresses of the directory 340 server it wants to know about its resources as described in 341 Section 4.1. 343 An endpoint that wants to make itself discoverable occasionally sends 344 a POST request to the "/.well-known/core" URI of any candidate 345 directory server that it finds. The body of the POST request is 346 either 348 o empty, in which case the directory server is encouraged by this 349 POST request to perform GET requests at the requesting server's 350 default discovery URI. 352 or 354 o a non-empty link-format document, which indicates the specific 355 services that the requesting server wants to make known to the 356 directory server. 358 The directory server integrates the information it received this way 359 into its resource directory. It MAY make the information available 360 to further directories, if it can ensure that a loop does not form. 361 The protocol used between directories to ensure loop-free operation 362 is outside the scope of this document. 364 The following example shows an endpoint using simple resource 365 discovery, by simply sending a POST with its links in the body to a 366 directory. 368 EP RD 369 | | 370 | -- POST /.well-known/core "..." ---> | 371 | | 372 | | 373 | <---- 2.01 Created ------------------------- | 374 | | 376 4.1. Finding a Directory Server 378 Endpoints that want to contact a directory server can obtain 379 candidate IP addresses for such servers in a number of ways. 381 In a 6LoWPAN, good candidates can be taken from: 383 o specific static configuration (e.g., anycast addresses), if any, 385 o the ABRO option of 6LoWPAN-ND [RFC6775], 387 o other ND options that happen to point to servers (such as RDNSS), 389 o DHCPv6 options that might be defined later. 391 In networks with more inexpensive use of multicast, the candidate IP 392 address may be a well-known multicast address, i.e. directory servers 393 are found by simply sending POST requests to that well-known 394 multicast address (details TBD). 396 As some of these sources are just (more or less educated) guesses, 397 endpoints MUST make use of any error messages to very strictly rate- 398 limit requests to candidate IP addresses that don't work out. For 399 example, an ICMP Destination Unreachable message (and, in particular, 400 the port unreachable code for this message) may indicate the lack of 401 a CoAP server on the candidate host, or a CoAP error response code 402 such as 4.05 "Method Not Allowed" may indicate unwillingness of a 403 CoAP server to act as a directory server. 405 4.2. Third-party registration 407 For some applications, even Simple Directory Discovery may be too 408 taxing for certain very constrained devices, in particular if the 409 security requirements become too onerous. 411 In a controlled environment (e.g. building control), the Resource 412 Directory can be filled by a third device, called an installation 413 tool. The installation tool can fill the Resource Directory from a 414 database or other means. For that purpose the scheme, IP address and 415 port of the registered device is indicated in the Context parameter 416 of the registration as well. 418 5. Resource Directory Function Set 420 This section defines the REST interfaces between an RD and endpoints, 421 which is called the Resource Directory Function Set. Although the 422 examples throughout this section assume the use of CoAP [RFC7252], 423 these REST interfaces can also be realized using HTTP [RFC7230]. An 424 RD implementing this specification MUST support the discovery, 425 registration, update, lookup, and removal interfaces defined in this 426 section. 428 Resource directory entries are designed to be easily exported to 429 other discovery mechanisms such as DNS-SD. For that reason, 430 parameters that would meaningfully be mapped to DNS SHOULD be limited 431 to a maximum length of 63 bytes. 433 5.1. Discovery 435 Before an endpoint can make use of an RD, it must first know the RD's 436 IP address, port and the path of its RD Function Set. There can be 437 several mechanisms for discovering the RD including assuming a 438 default location (e.g. on an Edge Router in a LoWPAN), by assigning 439 an anycast address to the RD, using DHCP, or by discovering the RD 440 using the CoRE Link Format (see also Section 4.1). This section 441 defines discovery of the RD using the well-known interface of the 442 CoRE Link Format [RFC6690] as the required mechanism. It is however 443 expected that RDs will also be discoverable via other methods 444 depending on the deployment. 446 Discovery is performed by sending either a multicast or unicast GET 447 request to "/.well-known/core" and including a Resource Type (rt) 448 parameter [RFC6690] with the value "core.rd" in the query string. 449 Likewise, a Resource Type parameter value of "core.rd-lookup" is used 450 to discover the RD Lookup Function Set. Upon success, the response 451 will contain a payload with a link format entry for each RD 452 discovered, with the URL indicating the root resource of the RD. 453 When performing multicast discovery, the multicast IP address used 454 will depend on the scope required and the multicast capabilities of 455 the network. 457 An RD implementation of this specification MUST support query 458 filtering for the rt parameter as defined in [RFC6690]. 460 The discovery request interface is specified as follows: 462 Interaction: EP -> RD 464 Method: GET 466 URI Template: /.well-known/core{?rt} 467 URI Template Variables: 469 rt := Resource Type (optional). MAY contain the value 470 "core.rd", "core.rd-lookup", "core.rd-group" or "core.rd*" 472 Content-Type: application/link-format (if any) 474 The following response codes are defined for this interface: 476 Success: 2.05 "Content" with an application/link-format payload 477 containing one or more matching entries for the RD resource. 479 Failure: 4.04 "Not Found" is returned in case no matching entry is 480 found for a unicast request. 482 Failure: 4.00 "Bad Request" is returned in case of a malformed 483 request for a unicast request. 485 Failure: No error response to a multicast request. 487 The following example shows an endpoint discovering an RD using this 488 interface, thus learning that the base RD resource is, in this 489 example, at /rd. Note that it is up to the RD to choose its base RD 490 resource, although diagnostics and debugging is facilitated by using 491 the base paths specified here where possible. 493 EP RD 494 | | 495 | ----- GET /.well-known/core?rt=core.rd* ------> | 496 | | 497 | | 498 | <---- 2.05 Content "; rt="core.rd" ------ | 499 | | 501 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 503 Res: 2.05 Content 504 ;rt="core.rd", 505 ;rt="core.rd-lookup", 506 ;rt="core.rd-group" 508 5.2. Registration 510 After discovering the location of an RD Function Set, an endpoint MAY 511 register its resources using the registration interface. This 512 interface accepts a POST from an endpoint containing the list of 513 resources to be added to the directory as the message payload in the 514 CoRE Link Format [RFC6690] or JSON Link Format 515 [I-D.ietf-core-links-json] along with query string parameters 516 indicating the name of the endpoint, its domain and the lifetime of 517 the registration. All parameters except the endpoint name are 518 optional. It is expected that other specifications will define 519 further parameters (see Section 11.3). The RD then creates a new 520 resource or updates an existing resource in the RD and returns its 521 location. An endpoint MUST use that location when refreshing 522 registrations using this interface. Endpoint resources in the RD are 523 kept active for the period indicated by the lifetime parameter. The 524 endpoint is responsible for refreshing the entry within this period 525 using either the registration or update interface. The registration 526 interface MUST be implemented to be idempotent, so that registering 527 twice with the same endpoint parameter does not create multiple RD 528 entries. 530 The registration request interface is specified as follows: 532 Interaction: EP -> RD 534 Method: POST 536 URI Template: /{+rd}{?ep,d,et,lt,con} 538 URI Template Variables: 540 rd := RD Function Set path (mandatory). This is the path of the 541 RD Function Set, as obtained from discovery. An RD SHOULD use 542 the value "rd" for this variable whenever possible. 544 ep := Endpoint (mandatory). The endpoint identifier or name of 545 the registering node, unique within that domain. The maximum 546 length of this parameter is 63 bytes. 548 d := Domain (optional). The domain to which this endpoint 549 belongs. This parameter SHOULD be less than 63 bytes. 550 Optional. When this parameter is elided, the RD MAY associate 551 the endpoint with a configured default domain. The domain 552 value is needed to export the endpoint to DNS-SD (see 553 Section 9). 555 et := Endpoint Type (optional). The semantic type of the 556 endpoint. This parameter SHOULD be less than 63 bytes. 557 Optional. 559 lt := Lifetime (optional). Lifetime of the registration in 560 seconds. Range of 60-4294967295. If no lifetime is included, 561 a default value of 86400 (24 hours) SHOULD be assumed. 563 con := Context (optional). This parameter sets the scheme, 564 address and port at which this server is available in the form 565 scheme://host:port. Optional. In the absence of this 566 parameter the scheme of the protocol, source IP address and 567 source port of the register request are assumed. This 568 parameter is mandatory when the directory is filled by a third 569 party such as an installation tool. 571 Content-Type: application/link-format 573 Content-Type: application/link-format+json 575 The following response codes are defined for this interface: 577 Success: 2.01 "Created". The Location header MUST be included with 578 the new resource entry for the endpoint. This Location MUST be a 579 stable identifier generated by the RD as it is used for all 580 subsequent operations on this registration. The resource returned 581 in the Location is only for the purpose of the Update (POST) and 582 Removal (DELETE), and MUST NOT implement GET or PUT methods. 584 Failure: 4.00 "Bad Request". Malformed request. 586 Failure: 5.03 "Service Unavailable". Service could not perform the 587 operation. 589 The following example shows an endpoint with the name "node1" 590 registering two resources to an RD using this interface. The 591 resulting location /rd/4521 is just an example of an RD generated 592 location. 594 EP RD 595 | | 596 | --- POST /rd?ep=node1 " | 597 | | 598 | | 599 | <-- 2.01 Created Location: /rd/4521 ---------- | 600 | | 602 Req: POST coap://rd.example.com/rd?ep=node1 603 Payload: 604 ;ct=41;rt="temperature-c";if="sensor", 605 ;ct=41;rt="light-lux";if="sensor" 607 Res: 2.01 Created 608 Location: /rd/4521 610 5.3. Update 612 The update interface is used by an endpoint to refresh or update its 613 registration with an RD. To use the interface, the endpoint sends a 614 POST request to the resource returned in the Location option in the 615 response to the first registration. An update MAY update the 616 lifetime or context parameters if they have changed since the last 617 registration or update. Parameters that have not changed SHOULD NOT 618 be included in an update. Upon receiving an update request, the RD 619 resets the timeout for that endpoint and updates the scheme, IP 620 address and port of the endpoint (using the source address of the 621 update, or the context parameter if present). 623 An update MAY optionally add or replace links for the endpoint by 624 including those links in the payload of the update as a CoRE Link 625 Format document. Including links in an update message greatly 626 increases the load on an RD and SHOULD be done infrequently. A link 627 is replaced only if both the target URI and relation type match (see 628 Section 10.1). 630 The update request interface is specified as follows: 632 Interaction: EP -> RD 634 Method: POST 636 URI Template: /{+location}{?lt,con} 638 URI Template Variables: 640 location := This is the Location path returned by the RD as a 641 result of a successful earlier registration. 643 lt := Lifetime (optional). Lifetime of the registration in 644 seconds. Range of 60-4294967295. If no lifetime is included, 645 a default value of 86400 (24 hours) SHOULD be assumed. 647 con := Context (optional). This parameter sets the scheme, 648 address and port at which this server is available in the form 649 scheme://host:port. Optional. In the absence of this 650 parameter the scheme of the protocol, source IP address and 651 source port used to register are assumed. This parameter is 652 compulsory when the directory is filled by a third party such 653 as an installation tool. 655 Content-Type: application/link-format (optional) 657 Content-Type: application/link-format+json (optional) 659 The following response codes are defined for this interface: 661 Success: 2.04 "Changed" in the update was successfully processed. 663 Failure: 4.00 "Bad Request". Malformed request. 665 Failure: 4.04 "Not Found". Registration does not exist (e.g. may 666 have expired). 668 Failure: 5.03 "Service Unavailable". Service could not perform the 669 operation. 671 The following example shows an endpoint updating a new set of 672 resources to an RD using this interface. 674 EP RD 675 | | 676 | --- POST /rd/4521 --------------------------> | 677 | | 678 | | 679 | <-- 2.04 Changed ---------------------------- | 680 | | 682 Req: POST /rd/4521 684 Res: 2.04 Changed 686 5.4. Removal 688 Although RD entries have soft state and will eventually timeout after 689 their lifetime, an endpoint SHOULD explicitly remove its entry from 690 the RD if it knows it will no longer be available (for example on 691 shut-down). This is accomplished using a removal interface on the RD 692 by performing a DELETE on the endpoint resource. 694 The removal request interface is specified as follows: 696 Interaction: EP -> RD 698 Method: DELETE 700 URI Template: /{+location} 702 URI Template Variables: 704 location := This is the Location path returned by the RD as a 705 result of a successful earlier registration. 707 The following responses codes are defined for this interface: 709 Success: 2.02 "Deleted" upon successful deletion 711 Failure: 4.00 "Bad Request". Malformed request. 713 Failure: 4.04 "Not Found". Registration does not exist (e.g. may 714 have expired). 716 Failure: 5.03 "Service Unavailable". Service could not perform the 717 operation. 719 The following examples shows successful removal of the endpoint from 720 the RD. 722 EP RD 723 | | 724 | --- DELETE /rd/4521 ------------------------> | 725 | | 726 | | 727 | <-- 2.02 Deleted ---------------------------- | 728 | | 730 Req: DELETE /rd/4521 732 Res: 2.02 Deleted 734 6. Group Function Set 736 This section defines a function set for the creation of groups of 737 endpoints for the purpose of managing and looking up endpoints for 738 group operations. The group function set is similar to the resource 739 directory function set, in that a group may be created or removed. 740 However unlike an endpoint entry, a group entry consists of a list of 741 endpoints and does not have a lifetime associated with it. In order 742 to make use of multicast requests with CoAP, a group MAY have a 743 multicast address associated with it. 745 6.1. Register a Group 747 In order to create a group, a management entity used to configure 748 groups, makes a request to the RD indicating the name of the group to 749 create (or update), optionally the domain the group belongs to, and 750 optionally the multicast address of the group. The registration 751 message includes the list of endpoints that belong to that group. If 752 an endpoint has already registered with the RD, the RD attempts to 753 use the context of the endpoint from its RD endpoint entry. If the 754 client registering the group knows the endpoint has already 755 registered, then it MAY send a blank target URI for that endpoint 756 link when registering the group. Configuration of the endpoints 757 themselves is out of scope of this specification. Such an interface 758 for managing the group membership of an endpoint has been defined in 759 [I-D.ietf-core-groupcomm]. 761 The registration request interface is specified as follows: 763 Interaction: Manager -> RD 765 Method: POST 767 URI Template: /{+rd-group}{?gp,d,con} 769 URI Template Variables: 771 rd-group := RD Group Function Set path (mandatory). This is the 772 path of the RD Group Function Set. An RD SHOULD use the value 773 "rd-group" for this variable whenever possible. 775 gp := Group Name (mandatory). The name of the group to be 776 created or replaced, unique within that domain. The maximum 777 length of this parameter is 63 bytes. 779 d := Domain (optional). The domain to which this group belongs. 780 The maximum length of this parameter is 63 bytes. Optional. 781 When this parameter is elided, the RD MAY associate the 782 endpoint with a configured default domain. The domain value is 783 needed to export the endpoint to DNS-SD (see Section 9) 785 con := Context (optional). This parameter is used to set the IP 786 multicast address at which this server is available in the form 787 scheme://multicast-address:port. Optional. In the absence of 788 this parameter no multicast address is configured. This 789 parameter is compulsory when the directory is filled by an 790 installation tool. 792 Content-Type: application/link-format 794 Content-Type: application/link-format+json 796 The following response codes are defined for this interface: 798 Success: 2.01 "Created". The Location header MUST be included with 799 the new group entry. This Location MUST be a stable identifier 800 generated by the RD as it is used for delete operations on this 801 registration. 803 Failure: 4.00 "Bad Request". Malformed request. 805 Failure: 5.03 "Service Unavailable". Service could not perform the 806 operation. 808 The following example shows a group with the name "lights" 809 registering two endpoints to an RD using this interface. The 810 resulting location /rd-group/12 is just an example of an RD generated 811 group location. 813 EP RD 814 | | 815 | - POST /rd-group?gp=lights "<>;ep=node1..." --> | 816 | | 817 | | 818 | <---- 2.01 Created Location: /rd-group/12 ---- | 819 | | 821 Req: POST coap://rd.example.com/rd-group?gp=lights 822 Payload: 823 <>;ep="node1", 824 <>;ep="node2" 826 Res: 2.01 Created 827 Location: /rd-group/12 829 6.2. Group Removal 831 A group can be removed simply by sending a removal message to the 832 location returned when registering the group. Removing a group MUST 833 NOT remove the endpoints of the group from the RD. 835 The removal request interface is specified as follows: 837 Interaction: Manager -> RD 839 Method: DELETE 841 URI Template: /{+location} 843 URI Template Variables: 845 location := This is the Location path returned by the RD as a 846 result of a successful group registration. 848 The following responses codes are defined for this interface: 850 Success: 2.02 "Deleted" upon successful deletion 852 Failure: 4.00 "Bad Request". Malformed request. 854 Failure: 4.04 "Not Found". Group does not exist. 856 Failure: 5.03 "Service Unavailable". Service could not perform the 857 operation. 859 The following examples shows successful removal of the group from the 860 RD. 862 EP RD 863 | | 864 | --- DELETE /rd-group/412 -------------------> | 865 | | 866 | | 867 | <-- 2.02 Deleted ---------------------------- | 868 | | 870 Req: DELETE /rd-group/12 872 Res: 2.02 Deleted 874 7. RD Lookup Function Set 876 In order for an RD to be used for discovering resources registered 877 with it, a lookup interface can be provided using this function set. 878 This lookup interface is defined as a default, and it is assumed that 879 RDs may also support lookups to return resource descriptions in 880 alternative formats (e.g. Atom or HTML Link) or using more advanced 881 interfaces (e.g. supporting context or semantic based lookup). 883 This function set allows lookups for domains, groups, endpoints and 884 resources using attributes defined in the RD Function Set and for use 885 with the CoRE Link Format. The result of a lookup request is the 886 list of links (if any) corresponding to the type of lookup. Using 887 the Accept Option, the requester can control whether this list is 888 returned in CoRE Link Format ("application/link-format", default) or 889 its JSON form ("application/link-format+json"). The target of these 890 links SHOULD be the actual location of the domain, endpoint or 891 resource, but MAY be an intermediate proxy e.g. in the case of an 892 HTTP lookup interface for CoAP endpoints. Multiple query parameters 893 MAY be included in a lookup, all included parameters MUST match for a 894 resource to be returned. The character '*' MAY be included at the 895 end of a parameter value as a wildcard operator. 897 The lookup interface is specified as follows: 899 Interaction: Client -> RD 901 Method: GET 903 URI Template: /{+rd-lookup-base}/ 904 {lookup-type}{?d,ep,gp,et,rt,page,count,resource-param} 906 Parameters: 908 rd-lookup-base := RD Lookup Function Set path (mandatory). This 909 is the path of the RD Lookup Function Set. An RD SHOULD use the 910 value "rd-lookup" for this variable whenever possible. 912 lookup-type := ("d", "ep", "res", "gp") (mandatory) This 913 variable is used to select the kind of lookup to perform 914 (domain, endpoint, resource, or group). 916 ep := Endpoint (optional). Used for endpoint, group and 917 resource lookups. 919 d := Domain (optional). Used for domain, group, endpoint and 920 resource lookups. 922 page := Page (optional). Parameter can not be used without the 923 count parameter. Results are returned from result set in pages 924 that contains 'count' results starting from index (page * 925 count). 927 count := Count (optional). Number of results is limited to this 928 parameter value. If the parameter is not present, then an RD 929 implementation specific default value SHOULD be used. 931 rt := Resource type (optional). Used for group, endpoint and 932 resource lookups. 934 et := Endpoint type (optional). Used for group, endpoint and 935 resource lookups. 937 resource-param := Link attribute parameters (optional). Any 938 link attribute as defined in Section 4.1 of [RFC6690], used for 939 resource lookups. 941 The following responses codes are defined for this interface: 943 Success: 2.05 "Content" with an "application/link-format" or 944 "application/link-format+json" payload containing a matching 945 entries for the lookup. 947 Failure: 4.04 "Not Found" in case no matching entry is found for a 948 unicast request. 950 Failure: No error response to a multicast request. 952 Failure: 4.00 "Bad Request". Malformed request. 954 Failure: 5.03 "Service Unavailable". Service could not perform the 955 operation. 957 The following example shows a client performing a resource lookup: 959 Client RD 960 | | 961 | ----- GET /rd-lookup/res?rt=temperature -----------------> | 962 | | 963 | | 964 | <-- 2.05 Content ;rt="temperature" | 965 | | 967 Req: GET /rd-lookup/res?rt=temperature 969 Res: 2.05 Content 970 ;rt="temperature" 972 The following example shows a client performing an endpoint lookup: 974 Client RD 975 | | 976 | ----- GET /rd-lookup/ep?et=power-node --------------------> | 977 | | 978 | | 979 | <-- 2.05 Content ;ep="node5" ------------ | 980 | | 982 Req: GET /rd-lookup/ep?et=power-node 984 Res: 2.05 Content 985 ;ep="node5", 986 ;ep="node7" 988 The following example shows a client performing a domain lookup: 990 Client RD 991 | | 992 | ----- GET /rd-lookup/d ----------------------------------> | 993 | | 994 | | 995 | <-- 2.05 Content ;d=domain1,;d=domain2 ---------- | 996 | | 998 Req: GET /rd-lookup/d 1000 Res: 2.05 Content 1001 ;d="domain1", 1002 ;d="domain2" 1004 The following example shows a client performing a group lookup for 1005 all groups: 1007 Client RD 1008 | | 1009 | ----- GET /rd-lookup/gp ---------------------------------> | 1010 | | 1011 | | 1012 | <-- 2.05 Content ;gp="lights1"; ------------- | 1013 | d="example.com" ------------- | 1014 | | 1016 Req: GET /rd-lookup/gp 1018 Res: 2.05 Content 1019 ;gp="lights1";d="example.com" 1021 The following example shows a client performing a lookup for all 1022 endpoints in a particular group: 1024 Client RD 1025 | | 1026 | ----- GET /rd-lookup/ep?gp=lights1-----------------------> | 1027 | | 1028 | | 1029 | <-- 2.05 Content ;ep="node1" ---------- | 1030 | | 1032 Req: GET /rd-lookup/ep?gp=lights1 1034 Res: 2.05 Content 1035 ;ep="node1", 1036 ;ep="node2", 1038 The following example shows a client performing a lookup for all 1039 groups an endpoint belongs to: 1041 Client RD 1042 | | 1043 | ----- GET /rd-lookup/gp?ep=node1 ------------------------> | 1044 | | 1045 | | 1046 | <-- 2.05 Content ;gp="lights1";ep="node1" | 1047 | | 1049 Req: GET /rd-lookup/gp?ep=node1 1051 Res: 2.05 Content 1052 ;gp="lights1";ep="node1", 1054 8. New Link-Format Attributes 1056 When using the CoRE Link Format to describe resources being 1057 discovered by or posted to a resource directory service, additional 1058 information about those resources is useful. This specification 1059 defines the following new attributes for use in the CoRE Link Format 1060 [RFC6690]: 1062 link-extension = ( "ins" "=" quoted-string ) ; Max 63 bytes 1063 link-extension = ( "exp" ) 1065 8.1. Resource Instance attribute 'ins' 1067 The Resource Instance "ins" attribute is an identifier for this 1068 resource, which makes it possible to distinguish it from other 1069 similar resources. This attribute is similar in use to the 1070 portion of a DNS-SD record (see Section 9.1, and SHOULD be 1071 unique across resources with the same Resource Type attribute in the 1072 domain it is used. A Resource Instance might be a descriptive string 1073 like "Ceiling Light, Room 3", a short ID like "AF39" or a unique UUID 1074 or iNumber. This attribute is used by a Resource Directory to 1075 distinguish between multiple instances of the same resource type 1076 within the directory. 1078 This attribute MUST be no more than 63 bytes in length. The resource 1079 identifier attribute MUST NOT appear more than once in a link 1080 description. 1082 8.2. Export attribute 'exp' 1084 The Export "exp" attribute is used as a flag to indicate that a link 1085 description MAY be exported by a resource directory to external 1086 directories. 1088 The CoRE Link Format is used for many purposes between CoAP 1089 endpoints. Some are useful mainly locally, for example checking the 1090 observability of a resource before accessing it, determining the size 1091 of a resource, or traversing dynamic resource structures. However, 1092 other links are very useful to be exported to other directories, for 1093 example the entry point resource to a functional service. 1095 9. DNS-SD Mapping 1097 CoRE Resource Discovery is intended to support fine-grained discovery 1098 of hosted resources, their attributes, and possibly other resource 1099 relations [RFC6690]. In contrast, service discovery generally refers 1100 to a coarse-grained resolution of an endpoint's IP address, port 1101 number, and protocol. 1103 Resource and service discovery are complementary in the case of large 1104 networks, where the latter can facilitate scaling. This document 1105 defines a mapping between CoRE Link Format attributes and DNS-Based 1106 Service Discovery [RFC6763] fields that permits discovery of CoAP 1107 services by either means. 1109 9.1. DNS-based Service discovery 1111 DNS-Based Service Discovery (DNS-SD) defines a conventional method of 1112 configuring DNS PTR, SRV, and TXT resource records to facilitate 1113 discovery of services (such as CoAP servers in a subdomain) using the 1114 existing DNS infrastructure. This section gives a brief overview of 1115 DNS-SD; see [RFC6763] for a detailed specification. 1117 DNS-SD service names are limited to 255 octets and are of the form: 1119 Service Name = ... 1121 The service name is the label of SRV/TXT resource records. The SRV 1122 RR specifies the host and the port of the endpoint. The TXT RR 1123 provides additional information. 1125 The part of the service name is identical to the global (DNS 1126 subdomain) part of the authority in URIs that identify servers or 1127 groups of servers. 1129 The part is composed of at least two labels. The first 1130 label of the pair is the application protocol name [RFC6335] preceded 1131 by an underscore character. The second label indicates the transport 1132 and is always "_udp" for UDP-based CoAP services. In cases where 1133 narrowing the scope of the search may be useful, these labels may be 1134 optionally preceded by a subtype name followed by the "_sub" label. 1135 An example of this more specific is 1136 "lamp._sub._dali._udp". 1138 The default part of the service name may be set at the 1139 factory or during the commissioning process. It SHOULD uniquely 1140 identify an instance of within a . Taken 1141 together, these three elements comprise a unique name for an SRV/ TXT 1142 record pair within the DNS subdomain. 1144 The granularity of a service name MAY be that of a host or group, or 1145 it could represent a particular resource within a CoAP server. The 1146 SRV record contains the host name (AAAA record name) and port of the 1147 service while protocol is part of the service name. In the case 1148 where a service name identifies a particular resource, the path part 1149 of the URI must be carried in a corresponding TXT record. 1151 A DNS TXT record is in practice limited to a few hundred octets in 1152 length, which is indicated in the resource record header in the DNS 1153 response message. The data consists of one or more strings 1154 comprising a key=value pair. By convention, the first pair is 1155 txtver= (to support different versions of a service 1156 description). 1158 9.2. mapping ins to 1160 The Resource Instance "ins" attribute maps to the part of 1161 a DNS-SD service name. It is stored directly in the DNS as a single 1162 DNS label of canonical precomposed UTF-8 [RFC3629] "Net-Unicode" 1163 (Unicode Normalization Form C) [RFC5198] text. However, to the 1164 extent that the "ins" attribute may be chosen to match the DNS host 1165 name of a service, it SHOULD use the syntax defined in Section 3.5 of 1166 [RFC1034] and Section 2.1 of [RFC1123]. 1168 The part of the name of a service being offered on the 1169 network SHOULD be configurable by the user setting up the service, so 1170 that he or she may give it an informative name. However, the device 1171 or service SHOULD NOT require the user to configure a name before it 1172 can be used. A sensible choice of default name can allow the device 1173 or service to be accessed in many cases without any manual 1174 configuration at all. The default name should be short and 1175 descriptive, and MAY include a collision-resistant substring such as 1176 the lower bits of the device's MAC address, serial number, 1177 fingerprint, or other identifier in an attempt to make the name 1178 relatively unique. 1180 DNS labels are currently limited to 63 octets in length and the 1181 entire service name may not exceed 255 octets. 1183 9.3. Mapping rt to 1185 The resource type "rt" attribute is mapped into the 1186 part of a DNS-SD service name and SHOULD conform to the reg-rel-type 1187 production of the Link Format defined in Section 2 of [RFC6690]. The 1188 "rt" attribute MUST be composed of at least a single Net-Unicode text 1189 string, without underscore '_' or period '.' and limited to 15 octets 1190 in length, which represents the application protocol name. This 1191 string is mapped to the DNS-SD by prepending an 1192 underscore and appending a period followed by the "_udp" label. For 1193 example, rt="dali" is mapped into "_dali._udp". 1195 The application protocol name may be optionally followed by a period 1196 and a service subtype name consisting of a Net-Unicode text string, 1197 without underscore or period and limited to 63 octets. This string 1198 is mapped to the DNS-SD by appending a period followed 1199 by the "_sub" label and then appending a period followed by the 1200 service type label pair derived as in the previous paragraph. For 1201 example, rt="dali.light" is mapped into "light._sub._dali._udp". 1203 The resulting string is used to form labels for DNS-SD records which 1204 are stored directly in the DNS. 1206 9.4. Domain mapping 1208 DNS domains are defined from the "d" attribute.The domain attribute 1209 is suffixed to the host name and should be consistent with the domain 1210 name attributed to the hosting network segment. 1212 9.5. TXT Record key=value strings 1214 A number of [RFC6763] key/value pairs are derived from link-format 1215 information, to be exported in the DNS-SD as key=value strings in a 1216 TXT record ([RFC6763], Section 6.3). 1218 The resource is exported as key/value pair "path=". 1220 The Interface Description "if" attribute is exported as key/value 1221 pair "if=". 1223 The DNS TXT record can be further populated by importing any other 1224 resource description attributes as they share the same key=value 1225 format specified in Section 6 of [RFC6763]. 1227 9.6. Importing resource links into DNS-SD 1229 Assuming the ability to query a Resource Directory or multicast a GET 1230 (?exp) over the local link, CoAP resource discovery may be used to 1231 populate the DNS-SD database in an automated fashion. CoAP resource 1232 descriptions (links) can be exported to DNS-SD for exposure to 1233 service discovery by using the Resource Instance attribute as the 1234 basis for a unique service name, composed with the Resource Type as 1235 the , and registered in the correct . The agent 1236 responsible for exporting records to the DNS zone file SHOULD be 1237 authenticated to the DNS server. The following example shows an 1238 agent discovering a resource to be exported: 1240 Agent RD 1241 | | 1242 | --- GET /rd-lookup/res?exp ------------------------------> | 1243 | | 1244 | | 1245 | <-- 2.05 Content ";exp; ------------ | 1246 | rt="dali.light";ins="FrontSpot" | 1247 | d="example.com" | 1248 | | 1250 Req: GET /rd-lookup/res?exp 1252 Res: 2.05 Content 1253 ; 1254 exp;ct=41;rt="dali.light";ins="FrontSpot"; 1255 d="example.com" 1257 The agent subsequently registers the following DNS-SD RRs: 1259 node1.example.com. IN AAAA 1260 FDFD::1234 1261 _dali._udp.example.com IN PTR 1262 FrontSpot._dali._udp.example.com 1263 light._sub._dali._udp.example.com IN PTR 1264 FrontSpot._dali._udp.example.com 1265 FrontSpot._dali._udp.example.com IN SRV 0 0 5678 1266 node1.example.com. 1267 FrontSpot._dali._udp.example.com IN TXT 1268 txtver=1;path=/light/1 1270 In the above figure the Service Name is chosen as 1271 FrontSpot._dali._udp.example.com without the light._sub service 1272 prefix. An alternative Service Name would be: 1273 FrontSpot.light._sub._dali._udp.example.com. 1275 10. Security Considerations 1277 The security considerations as described in Section 7 of [RFC5988] 1278 and Section 6 of [RFC6690] apply. The "/.well-known/core" resource 1279 may be protected e.g. using DTLS when hosted on a CoAP server as 1280 described in [RFC7252]. DTLS or TLS based security SHOULD be used on 1281 all resource directory interfaces defined in this document (TODO: 1282 Improve the exact DTLS or TLS security requirements and references). 1284 10.1. Endpoint Identification and Authentication 1286 An Endpoint is determined to be unique by an RD by the Endpoint 1287 identifier parameter included during Registration, and any associated 1288 TLS or DTLS security bindings. An Endpoint MUST NOT be identified by 1289 its protocol, port or IP address as these may change over the 1290 lifetime of an Endpoint. 1292 Every operation performed by an Endpoint or Client on a resource 1293 directory SHOULD be mutually authenticated using Pre-Shared Key, Raw 1294 Public Key or Certificate based security. Endpoints using a 1295 Certificate MUST include the Endpoint identifier as the Subject of 1296 the Certificate, and this identifier MUST be checked by a resource 1297 directory to match the Endpoint identifier included in the 1298 Registration message. 1300 10.2. Access Control 1302 Access control SHOULD be performed separately for the RD Function Set 1303 and the RD Lookup Function Set, as different endpoints may be 1304 authorized to register with an RD from those authorized to lookup 1305 endpoints from the RD. Such access control SHOULD be performed in as 1306 fine-grained a level as possible. For example access control for 1307 lookups could be performed either at the domain, endpoint or resource 1308 level. 1310 10.3. Denial of Service Attacks 1312 Services that run over UDP unprotected are vulnerable to unknowingly 1313 become part of a DDoS attack as UDP does not require return 1314 routability check. Therefore, an attacker can easily spoof the 1315 source IP of the target entity and send requests to such a service 1316 which would then respond to the target entity. This can be used for 1317 large-scale DDoS attacks on the target. Especially, if the service 1318 returns a response that is order of magnitudes larger than the 1319 request, the situation becomes even worse as now the attack can be 1320 amplified. DNS servers have been widely used for DDoS amplification 1321 attacks. Recently, it has been observed that NTP Servers, that also 1322 run on unprotected UDP have been used for DDoS attacks (http:// 1323 tools.cisco.com/security/center/content/CiscoSecurityNotice/ 1324 CVE-2013-5211) [TODO: Ref, and cut down the verbiage, as this is 1325 already discussed in RFC 7252] since there is no return routability 1326 check and can have a large amplification factor. The responses from 1327 the NTP server were found to be 19 times larger than the request. A 1328 Resource Directory (RD) which responds to wild-card lookups is 1329 potentially vulnerable if run with CoAP over UDP. Since there is no 1330 return routability check and the responses can be significantly 1331 larger than requests, RDs can unknowingly become part of a DDoS 1332 amplification attack. Therefore, it is RECOMMENDED that 1333 implementations ensure return routability. This can be done, for 1334 example by responding to wild card lookups only over DTLS or TLS or 1335 TCP. 1337 11. IANA Considerations 1339 11.1. Resource Types 1341 "core.rd", "core.rd-group" and "core.rd-lookup" resource types need 1342 to be registered with the resource type registry defined by 1343 [RFC6690]. 1345 11.2. Link Extension 1347 The "exp" attribute needs to be registered when a future Web Linking 1348 link-extension registry is created (e.g. in RFC5988bis). 1350 11.3. RD Parameter Registry 1352 This specification defines a new sub-registry for registration and 1353 lookup parameters called "RD Parameters" under "CoRE Parameters". 1354 Although this specification defines a basic set of parameters, it is 1355 expected that other standards that make use of this interface will 1356 define new ones. 1358 Each entry in the registry must include the human readable name of 1359 the parameter, the query parameter, validity requirements if any and 1360 a description. The query parameter MUST be a valid URI query key 1361 [RFC3986]. 1363 Initial entries in this sub-registry are as follows: 1365 +----------+-------+---------------+--------------------------------+ 1366 | Name | Query | Validity | Description | 1367 +----------+-------+---------------+--------------------------------+ 1368 | Endpoint | ep | | Name of the endpoint | 1369 | Name | | | | 1370 | Lifetime | lt | 60-4294967295 | Lifetime of the registration | 1371 | | | | in seconds | 1372 | Domain | d | | Domain to which this endpoint | 1373 | | | | belongs | 1374 | Endpoint | et | | Semantic name of the endpoint | 1375 | Type | | | | 1376 | Context | con | URI | The scheme, address and port | 1377 | | | | at which this server is | 1378 | | | | available | 1379 | Endpoint | ep | | Name of the endpoint, max 63 | 1380 | Name | | | bytes | 1381 | Group | gp | | Name of a group in the RD | 1382 | Name | | | | 1383 | Page | page | Integer | Used for pagination | 1384 | Count | count | Integer | Used for pagination | 1385 +----------+-------+---------------+--------------------------------+ 1387 Table 1: RD Parameters 1389 The IANA policy for future additions to the sub-registry is "Expert 1390 Review" as described in [RFC5226]. 1392 12. Examples 1393 13. Acknowledgments 1395 Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Peter van der Stok, 1396 Anders Brandt, Matthieu Vial, Michael Koster, Mohit Sethi, Sampo 1397 Ukkola and Linyi Tian have provided helpful comments, discussions and 1398 ideas to improve and shape this document. Zach would also like to 1399 thank his collagues from the EU FP7 SENSEI project, where many of the 1400 resource directory concepts were originally developed. 1402 14. Changelog 1404 Changes from -01 to -02: 1406 o Added a catalogue use case. 1408 o Changed the registration update to a POST with optional link 1409 format payload. Removed the endpoint type update from the update. 1411 o Additional examples section added for more complex use cases. 1413 o New DNS-SD mapping section. 1415 o Added text on endpoint identification and authentication. 1417 o Error code 4.04 added to Registration Update and Delete 1418 requests. 1420 o Made 63 bytes a SHOULD rather than a MUST for endpoint name and 1421 resource type parameters. 1423 Changes from -00 to -01: 1425 o Removed the ETag validation feature. 1427 o Place holder for the DNS-SD mapping section. 1429 o Explicitly disabled GET or POST on returned Location. 1431 o New registry for RD parameters. 1433 o Added support for the JSON Link Format. 1435 o Added reference to the Groupcomm WG draft. 1437 Changes from -05 to WG Document -00: 1439 o Updated the version and date. 1441 Changes from -04 to -05: 1443 o Restricted Update to parameter updates. 1445 o Added pagination support for the Lookup interface. 1447 o Minor editing, bug fixes and reference updates. 1449 o Added group support. 1451 o Changed rt to et for the registration and update interface. 1453 Changes from -03 to -04: 1455 o Added the ins= parameter back for the DNS-SD mapping. 1457 o Integrated the Simple Directory Discovery from Carsten. 1459 o Editorial improvements. 1461 o Fixed the use of ETags. 1463 Changes from -02 to -03: 1465 o Changed the endpoint name back to a single registration 1466 parameter ep= and removed the h= and ins= parameters. 1468 o Updated REST interface descriptions to use RFC6570 URI Template 1469 format. 1471 o Introduced an improved RD Lookup design as its own function set. 1473 o Improved the security considerations section. 1475 o Made the POST registration interface idempotent by requiring the 1476 ep= parameter to be present. 1478 Changes from -01 to -02: 1480 o Added a terminology section. 1482 o Changed the inclusion of an ETag in registration or update to a 1483 MAY. 1485 o Added the concept of an RD Domain and a registration parameter 1486 for it. 1488 o Recommended the Location returned from a registration to be 1489 stable, allowing for endpoint and Domain information to be changed 1490 during updates. 1492 o Changed the lookup interface to accept endpoint and Domain as 1493 query string parameters to control the scope of a lookup. 1495 15. References 1497 15.1. Normative References 1499 [I-D.ietf-core-links-json] 1500 Bormann, C., "Representing CoRE Link Collections in JSON", 1501 draft-ietf-core-links-json-02 (work in progress), 1502 July 2014. 1504 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1505 Requirement Levels", BCP 14, RFC 2119, March 1997. 1507 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1508 Resource Identifier (URI): Generic Syntax", STD 66, 1509 RFC 3986, January 2005. 1511 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1512 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1513 May 2008. 1515 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1517 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1518 Cheshire, "Internet Assigned Numbers Authority (IANA) 1519 Procedures for the Management of the Service Name and 1520 Transport Protocol Port Number Registry", BCP 165, 1521 RFC 6335, August 2011. 1523 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1524 and D. Orchard, "URI Template", RFC 6570, March 2012. 1526 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1527 Format", RFC 6690, August 2012. 1529 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1530 Discovery", RFC 6763, February 2013. 1532 15.2. Informative References 1534 [I-D.ietf-core-groupcomm] 1535 Rahman, A. and E. Dijk, "Group Communication for CoAP", 1536 draft-ietf-core-groupcomm-25 (work in progress), 1537 September 2014. 1539 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1540 STD 13, RFC 1034, November 1987. 1542 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 1543 and Support", STD 3, RFC 1123, October 1989. 1545 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1546 10646", STD 63, RFC 3629, November 2003. 1548 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 1549 Interchange", RFC 5198, March 2008. 1551 [RFC6775] Shelby, Z., Chakrabarti, S., Nordmark, E., and C. Bormann, 1552 "Neighbor Discovery Optimization for IPv6 over Low-Power 1553 Wireless Personal Area Networks (6LoWPANs)", RFC 6775, 1554 November 2012. 1556 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1557 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 1558 June 2014. 1560 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1561 Application Protocol (CoAP)", RFC 7252, June 2014. 1563 Authors' Addresses 1565 Zach Shelby 1566 ARM 1567 150 Rose Orchard 1568 San Jose 95134 1569 FINLAND 1571 Phone: +1-408-203-9434 1572 Email: zach.shelby@arm.com 1573 Carsten Bormann 1574 Universitaet Bremen TZI 1575 Postfach 330440 1576 Bremen D-28359 1577 Germany 1579 Phone: +49-421-218-63921 1580 Email: cabo@tzi.org