idnits 2.17.1 draft-ietf-core-resource-directory-01.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 (December 11, 2013) is 3761 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-00 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-25) exists of draft-ietf-core-groupcomm-16 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) 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: June 14, 2014 Universitaet Bremen TZI 6 S. Krco 7 Ericsson 8 December 11, 2013 10 CoRE Resource Directory 11 draft-ietf-core-resource-directory-01 13 Abstract 15 In many M2M applications, direct discovery of resources is not 16 practical due to sleeping nodes, disperse networks, or networks where 17 multicast traffic is inefficient. These problems can be solved by 18 employing an entity called a Resource Directory (RD), which hosts 19 descriptions of resources held on other servers, allowing lookups to 20 be performed for those resources. This document specifies the web 21 interfaces that a Resource Directory supports in order for web 22 servers to discover the RD and to register, maintain, lookup and 23 remove resources descriptions. Furthermore, new link attributes 24 useful in conjunction with an RD are defined. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on June 14, 2014. 43 Copyright Notice 45 Copyright (c) 2013 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . . 4 63 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . . 5 64 3.2. Use Case: Home and Building Automation . . . . . . . . . . 6 65 4. Simple Directory Discovery . . . . . . . . . . . . . . . . . . 6 66 4.1. Finding a Directory Server . . . . . . . . . . . . . . . . 7 67 5. Resource Directory Function Set . . . . . . . . . . . . . . . 8 68 5.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 8 69 5.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 10 70 5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 12 71 5.4. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 6. Group Function Set . . . . . . . . . . . . . . . . . . . . . . 15 73 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . . 15 74 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 17 75 7. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . . 18 76 8. New Link-Format Attributes . . . . . . . . . . . . . . . . . . 22 77 8.1. Resource Instance 'ins' attribute . . . . . . . . . . . . 22 78 8.2. Export 'exp' attribute . . . . . . . . . . . . . . . . . . 23 79 9. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . . 23 80 10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 81 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 82 11.1. Resource Types . . . . . . . . . . . . . . . . . . . . . . 23 83 11.2. Link Extension . . . . . . . . . . . . . . . . . . . . . . 24 84 11.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 24 85 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 86 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 25 87 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 88 14.1. Normative References . . . . . . . . . . . . . . . . . . . 26 89 14.2. Informative References . . . . . . . . . . . . . . . . . . 27 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 92 1. Introduction 94 The Constrained RESTful Environments (CoRE) work aims at realizing 95 the REST architecture in a suitable form for the most constrained 96 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 97 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 98 applications such as smart energy and building automation. 100 The discovery of resources offered by a constrained server is very 101 important in machine-to-machine applications where there are no 102 humans in the loop and static interfaces result in fragility. The 103 discovery of resources provided by an HTTP Web Server is typically 104 called Web Linking [RFC5988]. The use of Web Linking for the 105 description and discovery of resources hosted by constrained web 106 servers is specified by the CoRE Link Format [RFC6690]. This 107 specification however only describes how to discover resources from 108 the web server that hosts them by requesting /.well-known/core. In 109 many M2M scenarios, direct discovery of resources is not practical 110 due to sleeping nodes, disperse networks, or networks where multicast 111 traffic is inefficient. These problems can be solved by employing an 112 entity called a Resource Directory (RD), which hosts descriptions of 113 resources held on other servers, allowing lookups to be performed for 114 those resources. 116 This document specifies the web interfaces that a Resource Directory 117 supports in order for web servers to discover the RD and to register, 118 maintain, lookup and remove resource descriptions. Furthermore, new 119 link attributes useful in conjunction with a Resource Directory are 120 defined. Although the examples in this document show the use of 121 these interfaces with CoAP [I-D.ietf-core-coap], they can be applied 122 in an equivalent manner to HTTP [RFC2616]. 124 2. Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. The term 129 "byte" is used in its now customary sense as a synonym for "octet". 131 This specification requires readers to be familiar with all the terms 132 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 133 should also be familiar with the terms and concepts discussed in 134 [I-D.ietf-core-coap]. The URI Template format is used to describe 135 the REST interfaces defined in this specification [RFC6570]. This 136 specification makes use of the following additional terminology: 138 Resource Directory 139 An web entity that stores information about web resources and 140 implements the REST interfaces defined in this specification for 141 registration and lookup of those resources. 143 Domain 144 In the context of a Resource Directory, a domain is a logical 145 grouping of endpoints. This specification assumes that the list 146 of Domains supported by an RD is pre-configured by that RD. 148 Group 149 In the context of a Resource Directory, a group is a logical 150 grouping of endpoints for the purpose of group communications. 151 All groups within a domain are unique. 153 Endpoint 154 An endpoint (EP) is a term used to describe a web server or client 155 in [I-D.ietf-core-coap]. In the context of this specification an 156 endpoint is used to describe a web server that registers resources 157 to the Resource Directory. An endpoint is identified by its 158 endpoint name, which is included during registration, and is 159 unique within the associated domain of the registration. 161 3. Architecture and Use Cases 163 The resource directory architecture is shown in Figure 1. A Resource 164 Directory (RD) is used as a repository for Web Links [RFC5988] about 165 resources hosted on other web servers, which are called endpoints 166 (EP). An endpoint is a web server associated with an IP address and 167 port, thus a physical node may host one or more endpoints. The RD 168 implements a set of REST interfaces for endpoints to register and 169 maintain sets of Web Links (called resource directory entries), for 170 the RD to validate entries, and for clients to lookup resources from 171 the RD. Endpoints themselves can also act as clients. An RD can be 172 logically segmented by the use of Domains. The domain an endpoint is 173 associated with can be defined by the RD or configured by an outside 174 entity. 176 Endpoints are assumed to proactively register and maintain resource 177 directory entries on the RD, which are soft state and need to be 178 periodically refreshed. An endpoint is provided with interfaces to 179 register, update and remove a resource directory entry. Furthermore, 180 a mechanism to discover a RD using the CoRE Link Format is defined. 181 It is also possible for an RD to proactively discover Web Links from 182 endpoints and add them as resource directory entries, or to validate 183 existing resource directory entries. A lookup interface for 184 discovering any of the Web Links held in the RD is provided using the 185 CoRE Link Format. 187 Registration Lookup 188 +----+ | | 189 | EP |---- | | 190 +----+ ---- | | 191 --|- +------+ | 192 +----+ | ----| | | +--------+ 193 | EP | ---------|-----| RD |----|-----| Client | 194 +----+ | ----| | | +--------+ 195 --|- +------+ | 196 +----+ ---- | | 197 | EP |---- | | 198 +----+ 200 Figure 1: The resource directory architecture. 202 3.1. Use Case: Cellular M2M 204 Over the last few years, mobile operators around the world have 205 focused on development of M2M solutions in order to expand the 206 business to the new type of users, i.e. machines. The machines are 207 connected directly to a mobile network using appropriate embedded air 208 interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short and 209 wide range wireless interfaces. From the system design point of 210 view, the ambition is to design horizontal solutions that can enable 211 utilization of machines in different applications depending on their 212 current availability and capabilities as well as application 213 requirements, thus avoiding silo like solutions. One of the crucial 214 enablers of such design is the ability to discover resources 215 (machines - endpoints) capable of providing required information at a 216 given time or acting on instructions from the end users. 218 In a typical scenario, during a boot-up procedure (and periodically 219 afterwards), the machines (endpoints) register with a Resource 220 Directory (for example EPs installed on vehicles enabling tracking of 221 their position for the fleet management purposes and monitoring 222 environment parameters) hosted by the mobile operator or somewhere 223 else in the network, periodically a description of its own 224 capabilities. Due to the usual network configuration of mobile 225 networks, the EPs attached to the mobile network do not have routable 226 addresses. Therefore, a remote server is usually used to provide 227 proxy access to the EPs. The address of each (proxy) endpoint on 228 this server is included in the resource description stored in the RD. 229 The users, for example mobile applications for environment 230 monitoring, contact the RD, look-up the endpoints capable of 231 providing information about the environment using appropriate set of 232 link parameters, obtain information on how to contact them (URLs of 233 the proxy server) and then initiate interaction to obtain information 234 that is finally processed, displayed on the screen and usually stored 235 in a database. Similarly, fleet management systems provide the 236 appropriate link parameters to the RD to look-up for EPs deployed on 237 the vehicles the application is responsible for. 239 3.2. Use Case: Home and Building Automation 241 Home and commercial building automation systems can benefit from the 242 use of M2M web services. The use of CoRE in home automation across 243 multiple subnets is described in [I-D.brandt-coap-subnet-discovery] 244 and in commercial building automation in [I-D.vanderstok-core-bc]. 245 The discovery requirements of these applications are demanding. Home 246 automation usually relies on run-time discovery to commission the 247 system, whereas in building automation a combination of professional 248 commissioning and run-time discovery is used. Both home and building 249 automation involve peer-to-peer interactions between endpoints, and 250 involve battery-powered sleeping devices. 252 The exporting of resource information to other discovery systems is 253 also important in these automation applications. In home automation 254 there is a need to interact with other consumer electronics, which 255 may already support DNS-SD, and in building automation larger 256 resource directories or DNS-SD covering multiple buildings. 258 4. Simple Directory Discovery 260 Not all endpoints hosting resources are expected to know how to 261 implement the Resource Directory Function Set and thus explicitly 262 register with a Resource Directory (or other such directory server). 263 Instead, simple endpoints can implement the generic Simple Directory 264 Discovery approach described in this section. An RD implementing 265 this specification MUST implement Simple Directory Discovery. 266 However, there may be security reasons why this form of directory 267 discovery would be disabled. 269 This approach requires that the endpoint makes available the hosted 270 resources that it wants to be discovered, as links on its /.well- 271 known/core interface as specified in [RFC6690]. 273 The endpoint then finds one or more IP addresses of the directory 274 server it wants to know about its resources as described in 275 Section 4.1. 277 An endpoint that wants to make itself discoverable occasionally sends 278 a POST request to the /.well-known/core URI of any candidate 279 directory server that it finds. The body of the POST request is 280 either 282 o empty, in which case the directory server is encouraged by this 283 POST request to perform GET requests at the requesting server's 284 default discovery URI. 286 or 288 o a non-empty link-format document, which indicates the specific 289 services that the requesting server wants to make known to the 290 directory server. 292 The directory server integrates the information it received this way 293 into its resource directory. It MAY make the information available 294 to further directories, if it can ensure that a loop does not form. 295 The protocol used between directories to ensure loop-free operation 296 is outside the scope of this document. 298 The following example shows an endpoint using simple resource 299 discovery, by simply sending a POST with its links in the body to a 300 directory. 302 EP RD 303 | | 304 | -- POST /.well-known/core "..." ---> | 305 | | 306 | | 307 | <---- 2.01 Created ------------------------- | 308 | | 310 4.1. Finding a Directory Server 312 Endpoints that want to contact a directory server can obtain 313 candidate IP addresses for such servers in a number of ways. 315 In a 6LoWPAN, good candidates can be taken from: 317 o specific static configuration (e.g., anycast addresses), if any, 319 o the ABRO option of 6LoWPAN-ND [RFC6775], 320 o other ND options that happen to point to servers (such as RDNSS), 322 o DHCPv6 options that might be defined later. 324 In networks with more inexpensive use of multicast, the candidate IP 325 address may be a well-known multicast address, i.e. directory servers 326 are found by simply sending POST requests to that well-known 327 multicast address (details TBD). 329 As some of these sources are just (more or less educated) guesses, 330 endpoints MUST make use of any error messages to very strictly rate- 331 limit requests to candidate IP addresses that don't work out. E.g., 332 an ICMP Destination Unreachable message (and, in particular, the port 333 unreachable code for this message) may indicate the lack of a CoAP 334 server on the candidate host, or a CoAP error response code such as 335 4.05 "Method Not Allowed" may indicate unwillingness of a CoAP server 336 to act as a directory server. 338 5. Resource Directory Function Set 340 This section defines the REST interfaces between an RD and endpoint 341 servers, which is called the Resource Directory Function Set. 342 Although the examples throughout this section assume use of CoAP 343 [I-D.ietf-core-coap], these REST interfaces can also be realized 344 using HTTP [RFC2616]. An RD implementing this specification MUST 345 support the discovery, registration, update, and removal interfaces 346 defined in this section. 348 Resource directory entries are designed to be easily exported to 349 other discovery mechanisms such as DNS-SD. For that reason, 350 parameters that would meaningfully be mapped to DNS are limited to a 351 maximum length of 63 bytes. 353 5.1. Discovery 355 Before an endpoint can make use of an RD, it must first know the RD's 356 IP address, port and the path of its RD Function Set. There can be 357 several mechanisms for discovering the RD including assuming a 358 default location (e.g. on an Edge Router in a LoWPAN), by assigning 359 an anycast address to the RD, using DHCP, or by discovering the RD 360 using the CoRE Link Format (also see Section 4.1). This section 361 defines discovery of the RD using the well-known interface of the 362 CoRE Link Format [RFC6690] as the required mechanism. It is however 363 expected that RDs will also be discoverable via other methods 364 depending on the deployment. 366 Discovery is performed by sending either a multicast or unicast GET 367 request to /.well-known/core and including a Resource Type (rt) 368 parameter [RFC6690] with the value "core.rd" in the query string. 369 Likewise, a Resource Type parameter value of "core.rd-lookup" is used 370 to discover the RD Lookup Function Set. Upon success, the response 371 will contain a payload with a link format entry for each RD 372 discovered, with the URL indicating the root resource of the RD. 373 When performing multicast discovery, the multicast IP address used 374 will depend on the scope required and the multicast capabilities of 375 the network. 377 An RD implementation of this specification MUST support query 378 filtering for the rt parameter as defined in [RFC6690]. 380 The discovery request interface is specified as follows: 382 Interaction: EP -> RD 384 Method: GET 386 URI Template: /.well-known/core{?rt} 388 URI Template Variables: 390 rt := Resource Type (optional). MAY contain the value 391 "core.rd", "core.rd-lookup", "core.rd-group" or "core.rd*" 393 Content-Type: application/link-format (if any) 395 The following response codes are defined for this interface: 397 Success: 2.05 "Content" with an application/link-format payload 398 containing a matching entry for the RD resource. 400 Failure: 4.04 "Not Found" is returned in case no matching entry is 401 found for a unicast request. 403 Failure: 4.00 "Bad Request" is returned in case of a malformed 404 request for a unicast request. 406 Failure: No error response to a multicast request. 408 The following example shows an endpoint discovering an RD using this 409 interface, thus learning that the base RD resource is at /rd. Note 410 that it is up to the RD to choose its base RD resource, although it 411 is recommended to use the base paths specified here where possible. 413 EP RD 414 | | 415 | ----- GET /.well-known/core?rt=core.rd* ------> | 416 | | 417 | | 418 | <---- 2.05 Content "; rt="core.rd" ------ | 419 | | 421 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 423 Res: 2.05 Content 424 ;rt="core.rd", 425 ;rt="core.rd-lookup", 426 ;rt="core.rd-group" 428 5.2. Registration 430 After discovering the location of an RD Function Set, an endpoint MAY 431 register its resources using the registration interface. This 432 interface accepts a POST from an endpoint containing the list of 433 resources to be added to the directory as the message payload in the 434 CoRE Link Format [RFC6690] or JSON Link Format 435 [I-D.ietf-core-links-json] along with query string parameters 436 indicating the name of the endpoint, its domain and the lifetime of 437 the registration. All parameters except the endpoint name are 438 optional. It is expected that other specifications MAY define 439 further parameters (it is to be determined if a registry of 440 parameters is needed for this purpose). The RD then creates a new 441 resource or updates an existing resource in the RD and returns its 442 location. An endpoint MUST use that location when refreshing 443 registrations using this interface. Endpoint resources in the RD are 444 kept active for the period indicated by the lifetime parameter. The 445 endpoint is responsible for refreshing the entry within this period 446 using either the registration or update interface. The registration 447 interface MUST be implemented to be idempotent, so that registering 448 twice with the same endpoint parameter does not create multiple RD 449 entries. 451 The registration request interface is specified as follows: 453 Interaction: EP -> RD 454 Method: POST 456 URI Template: /{+rd}{?ep,d,et,lt,con} 458 URI Template Variables: 460 rd := RD Function Set path (mandatory). This is the path of the 461 RD Function Set. An RD SHOULD use the value "rd" for this 462 variable whenever possible. 464 ep := Endpoint (mandatory). The endpoint identifier or name of 465 the registering node, unique within that domain. The maximum 466 length of this parameter is 63 bytes. 468 d := Domain (optional). The domain to which this endpoint 469 belongs. The maximum length of this parameter is 63 bytes. 470 Optional. When this parameter is elided, the RD MAY associate 471 the endpoint with a configured default domain. 473 et := Endpoint Type (optional). The semantic type of the 474 endpoint. The maximum length of this parameter is 63 bytes. 475 Optional. 477 lt := Lifetime (optional). Lifetime of the registration in 478 seconds. Range of 60-4294967295. If no lifetime is included, 479 a default value of 86400 (24 hours) SHOULD be assumed. 481 con := Context (optional). This parameter sets the scheme, 482 address and port at which this server is available in the form 483 scheme://host:port. Optional. In the absence of this 484 parameter the scheme of the protocol, source IP address and 485 source port of the register request are assumed. 487 Content-Type: application/link-format 489 Content-Type: application/link-format+json 491 The following response codes are defined for this interface: 493 Success: 2.01 "Created". The Location header MUST be included with 494 the new resource entry for the endpoint. This Location MUST be a 495 stable identifier generated by the RD as it is used for all 496 subsequent operations on this registration. The resource returned 497 in the Location is only for the purpose of the Update (PUT) and 498 Removal (DELETE), and MUST NOT implement GET or POST methods. 500 Failure: 4.00 "Bad Request". Malformed request. 502 Failure: 5.03 "Service Unavailable". Service could not perform the 503 operation. 505 The following example shows an endpoint with the name "node1" 506 registering two resources to an RD using this interface. The 507 resulting location /rd/4521 is just an example of an RD generated 508 location. 510 EP RD 511 | | 512 | --- POST /rd?ep=node1 " | 513 | | 514 | | 515 | <-- 2.01 Created Location: /rd/4521 ---------- | 516 | | 518 Req: POST coap://rd.example.com/rd?ep=node1 519 Payload: 520 ;ct=41;rt="temperature-c";if="sensor", 521 ;ct=41;rt="light-lux";if="sensor" 523 Res: 2.01 Created 524 Location: /rd/4521 526 5.3. Update 528 The update interface is used by an endpoint to refresh or update its 529 registration with an RD. To use the interface, the endpoint sends a 530 PUT request to the resource returned in the Location option in the 531 response to the first registration. An update MAY contain 532 registration parameters if there have been changes since the last 533 registration or update. Parameters that have not changed SHOULD NOT 534 be included in an update. Upon receiving an update request, the RD 535 resets the timeout for that endpoint and stores the values of the 536 parameters included in the update (if any). 538 The update request interface is specified as follows: 540 Interaction: EP -> RD 541 Method: PUT 543 URI Template: /{+location}{?et,lt,con} 545 URI Template Variables: 547 location := This is the Location path returned by the RD as a 548 result of a successful registration. 550 et := Endpoint Type (optional). The semantic type of the 551 endpoint. The maximum length of this parameter is 63 btyes. 552 Optional. 554 lt := Lifetime (optional). Lifetime of the registration in 555 seconds. Range of 60-4294967295. If no lifetime is included, 556 a default value of 86400 (24 hours) SHOULD be assumed. 558 con := Context (optional). This parameter sets the scheme, 559 address and port at which this server is available in the form 560 scheme://host:port. Optional. In the absence of this 561 parameter the scheme of the protocol, source IP address and 562 source port used to register are assumed. 564 Content-Type: None 566 The following response codes are defined for this interface: 568 Success: 2.04 "Changed" in the update was successfully processed. 570 Failure: 4.00 "Bad Request". Malformed request. 572 Failure: 5.03 "Service Unavailable". Service could not perform the 573 operation. 575 The following example shows an endpoint updating a new set of 576 resources to an RD using this interface. 578 EP RD 579 | | 580 | --- PUT /rd/4521 --------------------------> | 581 | | 582 | | 583 | <-- 2.04 Changed ---------------------------- | 584 | | 586 Req: PUT /rd/4521 588 Res: 2.04 Changed 590 5.4. Removal 592 Although RD entries have soft state and will eventually timeout after 593 their lifetime, an endpoint SHOULD explicitly remove its entry from 594 the RD if it knows it will no longer be available (for example on 595 shut-down). This is accomplished using a removal interface on the RD 596 by performing a DELETE on the endpoint resource. 598 The removal request interface is specified as follows: 600 Interaction: EP -> RD 602 Method: DELETE 604 URI Template: /{+location} 606 URI Template Variables: 608 location := This is the Location path returned by the RD as a 609 result of a successful registration. 611 The following responses codes are defined for this interface: 613 Success: 2.02 "Deleted" upon successful deletion 615 Failure: 4.00 "Bad Request". Malformed request. 617 Failure: 5.03 "Service Unavailable". Service could not perform the 618 operation. 620 The following examples shows successful removal of the endpoint from 621 the RD. 623 EP RD 624 | | 625 | --- DELETE /rd/4521 ------------------------> | 626 | | 627 | | 628 | <-- 2.02 Deleted ---------------------------- | 629 | | 631 Req: DELETE /rd/4521 633 Res: 2.02 Deleted 635 6. Group Function Set 637 This section defines a function set for the creation of groups of 638 endpoints for the purpose of managing and looking up endpoints for 639 group operations. The group function set is similar to the resource 640 directory function set, in that a group may be created or removed. 641 However unlike an endpoint entry, a group entry consists of a list of 642 endpoints and does not have a lifetime associated with it. In order 643 to make use of multicast requests with CoAP, a group MAY have a 644 multicast address associated with it. 646 6.1. Register a Group 648 In order to create a group, a management entity used to configure 649 groups, makes a request to the RD indicating the name of the group to 650 create (or update), the optional domain the group belongs to, and the 651 optional multicast address of the group. The registration message 652 includes the list of endpoints that belong to that group. If an 653 endpoint has already registered with the RD, the RD attempts to use 654 the context of the endpoint from its RD endpoint entry. If the 655 client registering the group knows the endpoint has already 656 registered, then it MAY send a blank target URI for that endpoint 657 link when registering the group. Configuration of the endpoints 658 themselves is out of scope of this specification. Such an interface 659 for managing the group membership of an endpoint has been defined in 660 [I-D.ietf-core-groupcomm]. 662 The registration request interface is specified as follows: 664 Interaction: Manager -> RD 666 Method: POST 668 URI Template: /{+rd-group}{?gp,d,con} 670 URI Template Variables: 672 rd-group := RD Group Function Set path (mandatory). This is the 673 path of the RD Group Function Set. An RD SHOULD use the value 674 "rd-group" for this variable whenever possible. 676 gp := Group Name (mandatory). The name of the group to be 677 created or replaced, unique within that domain. The maximum 678 length of this parameter is 63 bytes. 680 d := Domain (optional). The domain to which this group belongs. 681 The maximum length of this parameter is 63 bytes. Optional. 682 When this parameter is elided, the RD MAY associate the 683 endpoint with a configured default domain. 685 con := Context (optional). This parameter is used to set the IP 686 multicast address at which this server is available in the form 687 scheme://multicast-address:port. Optional. In the absence of 688 this parameter no multicast address is configured. 690 Content-Type: application/link-format 692 Content-Type: application/link-format+json 694 The following response codes are defined for this interface: 696 Success: 2.01 "Created". The Location header MUST be included with 697 the new group entry. This Location MUST be a stable identifier 698 generated by the RD as it is used for delete operations on this 699 registration. 701 Failure: 4.00 "Bad Request". Malformed request. 703 Failure: 5.03 "Service Unavailable". Service could not perform the 704 operation. 706 The following example shows a group with the name "lights" 707 registering two endpoints to an RD using this interface. The 708 resulting location /rd-group/12 is just an example of an RD generated 709 group location. 711 EP RD 712 | | 713 | - POST /rd-group?gp=lights "<>;ep=node1..." --> | 714 | | 715 | | 716 | <---- 2.01 Created Location: /rd-group/12 ---- | 717 | | 719 Req: POST coap://rd.example.com/rd-group?gp=lights 720 Payload: 721 <>;ep="node1", 722 <>;ep="node2" 724 Res: 2.01 Created 725 Location: /rd-group/12 727 6.2. Group Removal 729 A group can be removed simply by sending a removal message to the 730 location returned when registering the group. Removing a group MUST 731 NOT remove the endpoints of the group from the RD. 733 The removal request interface is specified as follows: 735 Interaction: Manager -> RD 737 Method: DELETE 739 URI Template: /{+location} 741 URI Template Variables: 743 location := This is the Location path returned by the RD as a 744 result of a successful group registration. 746 The following responses codes are defined for this interface: 748 Success: 2.02 "Deleted" upon successful deletion 750 Failure: 4.00 "Bad Request". Malformed request. 752 Failure: 5.03 "Service Unavailable". Service could not perform the 753 operation. 755 The following examples shows successful removal of the group from the 756 RD. 758 EP RD 759 | | 760 | --- DELETE /rd-group/412 -------------------> | 761 | | 762 | | 763 | <-- 2.02 Deleted ---------------------------- | 764 | | 766 Req: DELETE /rd-group/12 768 Res: 2.02 Deleted 770 7. RD Lookup Function Set 772 In order for an RD to be used for discovering resources registered 773 with it, a lookup interface can be provided using this function set. 774 This lookup interface is defined as a default, and it is assumed that 775 RDs may also support lookups to return resource descriptions in 776 alternative formats (e.g. Atom or HTML Link) or using more advanced 777 interfaces (e.g. supporting context or semantic based lookup). 779 This function set allows lookups for domains, groups, endpoints and 780 resources using attributes defined in the RD Function Set and for use 781 with the CoRE Link Format. The result of a lookup request is the 782 list of links (if any) in CoRE Link Format corresponding to the type 783 of lookup. The target of these links SHOULD be the actual location 784 of the domain, endpoint or resource, but MAY be an intermediate proxy 785 e.g. in the case of an HTTP lookup interface for CoAP endpoints. 786 Multiple query parameters MAY be included in a lookup, all included 787 parameters MUST match for a resource to be returned. The character 788 '*' MAY be included at the end of a parameter value as a wildcard 789 operator. 791 The lookup interface is specified as follows: 793 Interaction: Client -> RD 795 Method: GET 797 URI Template: /{+rd-lookup-base}/ 798 {lookup-type}{?d,ep,gp,et,rt,page,count,resource-param} 800 Parameters: 802 rd-lookup-base := RD Lookup Function Set path (mandatory). This 803 is the path of the RD Lookup Function Set. An RD SHOULD use the 804 value "rd-lookup" for this variable whenever possible. 806 lookup-type := ("d", "ep", "res", "gp") (mandatory) This 807 variable is used to select the kind of lookup to perform 808 (domain, endpoint or resource). 810 ep := Endpoint (optional). Used for endpoint, group and 811 resource lookups. 813 d := Domain (optional). Used for domain, group, endpoint and 814 resource lookups. 816 page := Page (optional). Parameter can not be used without the 817 count parameter. Results are returned from result set in pages 818 that contains 'count' results starting from index (page * 819 count). 821 count := Count (optional). Number of results is limited to this 822 parameter value. If the parameter is not present, then an RD 823 implementation specific default value SHOULD be used. 825 rt := Resource type (optional). Used for group, endpoint and 826 resource lookups. 828 et := Endpoint type (optional). Used for group, endpoint and 829 resource lookups. 831 resource-param := Link attribute parameters (optional). Any 832 link attribute as defined in Section 4.1 of [RFC6690], used for 833 resource lookups. 835 The following responses codes are defined for this interface: 837 Success: 2.05 "Content" with an application/link-format or 838 application/link-format+json payload containing a matching entries 839 for the lookup. 841 Failure: 4.04 "Not Found" in case no matching entry is found for a 842 unicast request. 844 Failure: No error response to a multicast request. 846 Failure: 4.00 "Bad Request". Malformed request. 848 Failure: 5.03 "Service Unavailable". Service could not perform the 849 operation. 851 The following example shows a client performing a resource lookup: 853 Client RD 854 | | 855 | ----- GET /rd-lookup/res?rt=temperature -----------------> | 856 | | 857 | | 858 | <-- 2.05 Content ";rt="temperature" ---- | 859 | | 861 Req: GET /rd-lookup/res?rt=temperature 863 Res: 2.05 Content 864 866 The following example shows a client performing an endpoint lookup: 868 Client RD 869 | | 870 | ----- GET /rd-lookup/ep?et=power-node --------------------> | 871 | | 872 | | 873 | <-- 2.05 Content ";ep="node5" ----------- | 874 | | 876 Req: GET /rd-lookup/ep?et=power-node 878 Res: 2.05 Content 879 ;ep="node5", 880 ;ep="node7" 882 The following example shows a client performing a domain lookup: 884 Client RD 885 | | 886 | ----- GET /rd-lookup/d ----------------------------------> | 887 | | 888 | | 889 | <-- 2.05 Content ";d=domain1,;d=domain2 --------- | 890 | | 892 Req: GET /rd-lookup/d 894 Res: 2.05 Content 895 ;d="domain1", 896 ;d="domain2" 898 The following example shows a client performing a group lookup for 899 all groups: 901 Client RD 902 | | 903 | ----- GET /rd-lookup/gp ---------------------------------> | 904 | | 905 | | 906 | <-- 2.05 Content ;gp="lights1";d="domain1" -- | 907 | | 909 Req: GET /rd-lookup/gp 911 Res: 2.05 Content 912 ;gp="lights1";d="domain1" 914 The following example shows a client performing a lookup for all 915 endpoints in a particular group: 917 Client RD 918 | | 919 | ----- GET GET /rd-lookup/ep?gp=lights1-------------------> | 920 | | 921 | | 922 | <-- 2.05 Content ";d=domain1,;d=domain2 --------- | 923 | | 925 Req: GET /rd-lookup/ep?gp=lights1 927 Res: 2.05 Content 928 ;ep="node1", 929 ;ep="node2", 930 The following example shows a client performing a lookup for all 931 groups an endpoint belongs to: 933 Client RD 934 | | 935 | ----- GET /rd-lookup/gp?ep=node1 ------------------------> | 936 | | 937 | | 938 | <-- 2.05 Content ";d=domain1,;d=domain2 --------- | 939 | | 941 Req: GET /rd-lookup/gp?ep=node1 943 Res: 2.05 Content 944 ;gp="lights1";ep="node1", 946 8. New Link-Format Attributes 948 When using the CoRE Link Format to describe resources being 949 discovered by or posted to a resource directory service, additional 950 information about those resources is useful. This specification 951 defines the following new attributes for use in the CoRE Link Format 952 [RFC6690]: 954 link-extension = ( "ins" "=" quoted-string ) ; Max 63 bytes 955 link-extension = ( "exp" ) 957 8.1. Resource Instance 'ins' attribute 959 The Resource Instance "ins" attribute is an identifier for this 960 resource, which makes it possible to distinguish from other similar 961 resources. This attribute is similar in use to the "Instance" 962 portion of a DNS-SD record, and SHOULD be unique across resources 963 with the same Resource Type attribute in the domain it is used. A 964 Resource Instance might be a descriptive string like "Ceiling Light, 965 Room 3", a short ID like "AF39" or a unique UUID or iNumber. This 966 attribute is used by a Resource Directory to distinguish between 967 multiple instances of the same resource type within a system. 969 This attribute MUST be no more than 63 bytes in length. The resource 970 identifier attribute MUST NOT appear more than once in a link 971 description. 973 8.2. Export 'exp' attribute 975 The Export "exp" attribute is used as a flag to indicate that a link 976 description MAY be exported by a resource directory to external 977 directories. 979 The CoRE Link Format is used for many purposes between CoAP 980 endpoints. Some are useful mainly locally, for example checking the 981 observability of a resource before accessing it, determining the size 982 of a resource, or traversing dynamic resource structures. However, 983 other links are very useful to be exported to other directories, for 984 example the entry point resource to a functional service. 986 9. DNS-SD Mapping 988 TODO 990 10. Security Considerations 992 This document needs the same security considerations as described in 993 Section 7 of [RFC5988] and Section 6 of [RFC6690]. The /.well-known/ 994 core resource may be protected e.g. using DTLS when hosted on a CoAP 995 server as described in [I-D.ietf-core-coap]. 997 Access control SHOULD be performed separately for the RD Function Set 998 and the RD Lookup Function Set, as different endpoints may be 999 authorized to register with an RD from those authorized to lookup 1000 endpoints from the RD. Such access control SHOULD be performed in as 1001 fine-grained a level as possible. For example access control for 1002 lookups could be performed either at the domain, endpoint or resource 1003 level. 1005 11. IANA Considerations 1007 11.1. Resource Types 1009 "core.rd", "core.rd-group" and "core.rd-lookup" resource types need 1010 to be registered with the resource type registry defined by 1011 [RFC6690]. 1013 11.2. Link Extension 1015 The "exp" attribute needs to be registered when a future Web Linking 1016 link-extension registry is created (e.g. in RFC5988bis). 1018 11.3. RD Parameter Registry 1020 This specification defines a new sub-registry for registration and 1021 lookup parameters called "RD Parameters" under "CoRE Parameters". 1022 Although this specification defines a basic set of parameters, it is 1023 expected that other standards that make use of this interface will 1024 define new ones. 1026 Each entry in the registry must include the human readable name of 1027 the parameter, the query parameter, validity requirements if any and 1028 a description. The query parameter MUST be a valid URI query key 1029 [RFC3986]. 1031 Initial entries in this sub-registry are as follows: 1033 +----------+-------+---------------+--------------------------------+ 1034 | Name | Query | Validity | Description | 1035 +----------+-------+---------------+--------------------------------+ 1036 | Endpoint | ep | < 63 bytes | Name of the endpoint | 1037 | Name | | | | 1038 | Lifetime | lt | 60-4294967295 | Lifetime of the registration | 1039 | | | | in seconds | 1040 | Domain | d | < 63 bytes | Domain to which this endpoint | 1041 | | | | belongs | 1042 | Endpoint | et | | Semantic name of the endpoint | 1043 | Type | | | | 1044 | Context | con | URI | The scheme, address and port | 1045 | | | | at which this server is | 1046 | | | | available | 1047 | Endpoint | ep | | Name of the endpoint, max 63 | 1048 | Name | | | bytes | 1049 | Group | gp | | Name of a group in the RD | 1050 | Name | | | | 1051 | Page | page | Integer | Used for pagination | 1052 | Count | count | Integer | Used for pagination | 1053 +----------+-------+---------------+--------------------------------+ 1055 Table 1: RD Parameters 1057 The IANA policy for future additions to the sub-registry is "Expert 1058 Review" as described in [RFC5226] 1060 12. Acknowledgments 1062 Szymon Sasin, Kerry Lynn, Esko Dijk, Peter van der Stok, Anders 1063 Brandt, Matthieu Vial, Sampo Ukkola and Linyi Tian have provided 1064 helpful comments, discussions and ideas to improve and shape this 1065 document. The authors would also like to thank their collagues from 1066 the EU FP7 SENSEI project, where many of the resource directory 1067 concepts were originally developed. 1069 13. Changelog 1071 Changes from -00 to -01: 1073 o Removed the ETag validation feature. 1075 o Place holder for the DNS-SD mapping section. 1077 o Explicitly disabled GET or POST on returned Location. 1079 o New registry for RD parameters. 1081 o Added support for the JSON Link Format. 1083 o Added reference to the Groupcomm WG draft. 1085 Changes from -05 to WG Document -00: 1087 o Updated the version and date. 1089 Changes from -04 to -05: 1091 o Restricted Update to parameter updates. 1093 o Added pagination support for the Lookup interface. 1095 o Minor editing, bug fixes and reference updates. 1097 o Added group support. 1099 o Changed rt to et for the registration and update interface. 1101 Changes from -03 to -04: 1103 o Added the ins= parameter back for the DNS-SD mapping. 1105 o Integrated the Simple Directory Discovery from Carsten. 1107 o Editorial improvements. 1109 o Fixed the use of ETags. 1111 Changes from -02 to -03: 1113 o Changed the endpoint name back to a single registration 1114 parameter ep= and removed the h= and ins= parameters. 1116 o Updated REST interface descriptions to use RFC6570 URI Template 1117 format. 1119 o Introduced an improved RD Lookup design as its own function set. 1121 o Improved the security considerations section. 1123 o Made the POST registration interface idempotent by requiring the 1124 ep= paramter to be present. 1126 Changes from -01 to -02: 1128 o Added a terminology section. 1130 o Changed the inclusing of an ETag in registration or update to a 1131 MAY. 1133 o Added the concept of an RD Domain and a registration parameter 1134 for it. 1136 o Recommended the Location returned from a registration to be 1137 stable, allowing for endpoint and Domain information to be changed 1138 during updates. 1140 o Changed the lookup interface to accept endpoint and Domain as 1141 query string parameters to control the scope of a lookup. 1143 14. References 1145 14.1. Normative References 1147 [I-D.ietf-core-links-json] 1148 Bormann, C., "Representing CoRE Link Collections in JSON", 1149 draft-ietf-core-links-json-00 (work in progress), 1150 June 2013. 1152 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1153 Requirement Levels", BCP 14, RFC 2119, March 1997. 1155 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1156 Resource Identifier (URI): Generic Syntax", STD 66, 1157 RFC 3986, January 2005. 1159 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1160 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1161 May 2008. 1163 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1165 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1166 and D. Orchard, "URI Template", RFC 6570, March 2012. 1168 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1169 Format", RFC 6690, August 2012. 1171 14.2. Informative References 1173 [I-D.brandt-coap-subnet-discovery] 1174 Brandt, A., "Discovery of CoAP servers across subnets", 1175 draft-brandt-coap-subnet-discovery-00 (work in progress), 1176 March 2011. 1178 [I-D.ietf-core-coap] 1179 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 1180 Application Protocol (CoAP)", draft-ietf-core-coap-18 1181 (work in progress), June 2013. 1183 [I-D.ietf-core-groupcomm] 1184 Rahman, A. and E. Dijk, "Group Communication for CoAP", 1185 draft-ietf-core-groupcomm-16 (work in progress), 1186 October 2013. 1188 [I-D.vanderstok-core-bc] 1189 Stok, P. and K. Lynn, "CoAP Utilization for Building 1190 Control", draft-vanderstok-core-bc-05 (work in progress), 1191 October 2011. 1193 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1194 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1195 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1197 [RFC6775] Shelby, Z., Chakrabarti, S., Nordmark, E., and C. Bormann, 1198 "Neighbor Discovery Optimization for IPv6 over Low-Power 1199 Wireless Personal Area Networks (6LoWPANs)", RFC 6775, 1200 November 2012. 1202 Authors' Addresses 1204 Zach Shelby 1205 ARM 1206 150 Rose Orchard 1207 San Jose 95134 1208 FINLAND 1210 Phone: +1-408-203-9434 1211 Email: zach.shelby@arm.com 1213 Carsten Bormann 1214 Universitaet Bremen TZI 1215 Postfach 330440 1216 Bremen D-28359 1217 Germany 1219 Phone: +49-421-218-63921 1220 Email: cabo@tzi.org 1222 Srdjan Krco 1223 Ericsson 1225 Phone: 1226 Email: srdjan.krco@ericsson.com