idnits 2.17.1 draft-shelby-core-resource-directory-04.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 (July 16, 2012) is 4295 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) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-21) exists of draft-ietf-6lowpan-nd-18 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-10 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 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 Sensinode 4 Intended status: Standards Track S. Krco 5 Expires: January 17, 2013 Ericsson 6 C. Bormann 7 Universitaet Bremen TZI 8 July 16, 2012 10 CoRE Resource Directory 11 draft-shelby-core-resource-directory-04 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 January 17, 2013. 43 Copyright Notice 45 Copyright (c) 2012 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. Validation . . . . . . . . . . . . . . . . . . . . . . . . 13 72 5.5. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 14 73 6. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . . 15 74 7. New Link-Format Attributes . . . . . . . . . . . . . . . . . . 18 75 7.1. Resource Instance 'ins' attribute . . . . . . . . . . . . 18 76 7.2. Export 'exp' attribute . . . . . . . . . . . . . . . . . . 19 77 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 78 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 79 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 80 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 20 81 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 82 12.1. Normative References . . . . . . . . . . . . . . . . . . . 21 83 12.2. Informative References . . . . . . . . . . . . . . . . . . 21 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 86 1. Introduction 88 The Constrained RESTful Environments (CoRE) work aims at realizing 89 the REST architecture in a suitable form for the most constrained 90 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 91 networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) 92 applications such as smart energy and building automation. 94 The discovery of resources offered by a constrained server is very 95 important in machine-to-machine applications where there are no 96 humans in the loop and static interfaces result in fragility. The 97 discovery of resources provided by an HTTP Web Server is typically 98 called Web Linking [RFC5988]. The use of Web Linking for the 99 description and discovery of resources hosted by constrained web 100 servers is specified by the CoRE Link Format 101 [I-D.ietf-core-link-format]. This specification however only 102 describes how to discover resources from the web server that hosts 103 them by requesting /.well-known/core. In many M2M scenarios, direct 104 discovery of resources is not practical due to sleeping nodes, 105 disperse networks, or networks where multicast traffic is 106 inefficient. These problems can be solved by employing an entity 107 called a Resource Directory (RD), which hosts descriptions of 108 resources held on other servers, allowing lookups to be performed for 109 those resources. 111 This document specifies the web interfaces that a Resource Directory 112 supports in order for web servers to discover the RD and to 113 registrer, maintain, lookup and remove resources descriptions. 114 Furthermore, new link attributes useful in conjunction with a 115 Resource Directory are defined. Although the examples in this 116 document show the use of these interfaces with CoAP 117 [I-D.ietf-core-coap], they may be applied in an equivalent manner to 118 HTTP [RFC2616]. 120 2. Terminology 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. The term 125 "byte" is used in its now customary sense as a synonym for "octet". 127 This specification requires readers to be familiar with all the terms 128 and concepts that are discussed in [RFC5988] and 129 [I-D.ietf-core-link-format]. Readers should also be familiar with 130 the terms and concepts discussed in [I-D.ietf-core-coap]. The URI 131 Template format is used to describe the REST interfaces defined in 132 this specification [RFC6570]. This specification makes use of the 133 following additional terminology: 135 Resource Directory 136 An web entity that stores information about web resources and 137 implements the REST interfaces defined in this specification for 138 registration and lookup of those resources. 140 Domain 141 In the context of a Resource Directory, a Domain is a logical 142 grouping of endpoints. All endpoint within a Domain MUST be 143 unique. This specification assumes that the list of Domains 144 supported by an RD is pre-configured by that RD. 146 Endpoint 147 An endpoint (EP) is a term used to describe a web server or client 148 in [I-D.ietf-core-coap]. In the context of this specification an 149 endpoint is used to describe a web server that registers resources 150 to the Resource Directory. An endpoint is identified by its 151 endpoint name, which is included during registration, and MUST be 152 unique within the associated Domain of the registration. 154 3. Architecture and Use Cases 156 The resource directory architecture is shown in Figure 1. A Resource 157 Directory (RD) is used as a repository for Web Links [RFC5988] about 158 resources hosted on other web servers, which are called endpoints 159 (EP). An endpoint is a web server associated with a port, thus a 160 physical node may host one or more endpoints. The RD implements a 161 set of REST interfaces for endpoints to register and maintain sets of 162 Web Links (called resource directory entries), for the RD to validate 163 entries, and for clients to lookup resources from the RD. Endpoints 164 themselves can also act as clients. An RD can be logically segmented 165 by the use of Domains. The Domain an endpoint is associated with can 166 be defined by the RD or configured by an outside entity. 168 Endpoints are assumed to proactively register and maintain resource 169 directory entries on the RD, which are soft state and need to be 170 periodially refreshed. An endpoint is provided with interfaces to 171 register, update and remove a resource directory entry. Furthermore, 172 a mechanism to discover a RD using the CoRE Link Format is defined. 173 It is also possible for an RD to proactively discover Web Links from 174 endpoints and add them as resource directory entries, or to validate 175 existing resource directory entries. A lookup interface for 176 discovering any of the Web Links held in the RD is provided using the 177 CoRE Link Format. 179 Registration Lookup 180 +----+ | | 181 | EP |---- | | 182 +----+ ---- | | 183 --|- +------+ | 184 +----+ | ----| | | +--------+ 185 | EP | ---------|-----| RD |----|-----| Client | 186 +----+ | ----| | | +--------+ 187 --|- +------+ | 188 +----+ ---- | | 189 | EP |---- | | 190 +----+ 192 Figure 1: The resource directory architecture. 194 3.1. Use Case: Cellular M2M 196 Over the last few years, mobile operators around the world have 197 focused on development of M2M solutions in order to expand the 198 business to the new type of users, i.e. machines. The machines are 199 connected directly to a mobile network using appropriate embedded air 200 interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short and 201 wide range wireless interfaces. From the system design point of 202 view, the ambition is to design horizontal solutions that can enable 203 utilization of machines in different applications depending on their 204 current availability and capabilities as well as application 205 requirements, thus avoiding silo like solutions. One of the crucial 206 enablers of such design is the ability to discover resources 207 (machines - endpoints) capable of providing required information at a 208 given time or acting on instructions from the end users. 210 In a typical scenario, during a boot-up procedure (and periodically 211 afterwards), the machines (endpoints) register with a Resource 212 Directory (for example EPs installed on vehicles enabling tracking of 213 their position for the fleet management purposes and monitoring 214 environment parameters) hosted by the mobile operator or somewhere 215 else in the network, submiting a description of own capabilities. 216 Due to the usual network configuration of mobile networks, the EPs 217 attached to the mobile network do not have routable addresses. 218 Therefore, a remote server is usually used to provide proxy access to 219 the EPs. The address of each (proxy) endpoint on this server is 220 included in the resource description stored in the RD. The users, 221 for example mobile applications for environment monitoring, contact 222 the RD, look-up the endpoints capable of providing information about 223 the environment using appropriate set of tags, obtain information on 224 how to contact them (URLs of the proxy server) and then initate 225 interaction to obtain information that is finally processed, 226 displayed on the screen and usually stored in a database. Similarly, 227 fleet management systems provide a set of credentials along with the 228 appropriate tags to the RD to look-up for EPs deployed on the 229 vehicles the application is responsible for. 231 3.2. Use Case: Home and Building Automation 233 Home and commercial building automation systems can benefit from the 234 use of M2M web services. The use of CoRE in home automation across 235 multiple subnets is described in [I-D.brandt-coap-subnet-discovery] 236 and in commercial building automation in [I-D.vanderstok-core-bc]. 237 The discovery requirements of these applications are demanding. Home 238 automation usually relies on run-time discovery to commision the 239 system, whereas in building automation a combination of professional 240 commissioning and run-time discovery is used. Both home and building 241 automation involve peer-to-peer interactions between endpoints, and 242 involve battery-powered sleeping devices. 244 The exporting of resource information to other discovery systems is 245 also important in these automation applications. In home automation 246 there is a need to interact with other consumer electronics, which 247 may already support DNS-SD, and in building automation larger 248 resource directories or DNS-SD covering multiple buildings. 250 4. Simple Directory Discovery 252 Not all endpoints hosting resources are expected to know how to 253 implement the Resource Directory Function Set and thus explicitly 254 register with a Resource Directory (or other such directory server). 255 Instead, simple endpoints can implement the generic Simple Directory 256 Discovery approach described in this section. An RD implementing 257 this specification MUST implement Simple Directory Discovery. 258 However, there may be security reasons why this form of directory 259 discovery would be disabled. 261 This approach requires that the endpoint makes the hosted resources 262 that it wants discovered available as links on its /.well-known/core 263 interface as specified in [I-D.ietf-core-link-format]. 265 The endpoint then finds one or more IP addresses of the directory 266 server it wants to know about its resources as described in 267 Section 4.1. 269 An endpoint that wants to make itself discoverable occasionally sends 270 a POST request to the /.well-known/core URI of any candidate 271 directory server that it finds. The body of the POST request is 272 either 273 o empty, in which case the directory server is encouraged by this 274 POST request to perform GET requests at the requesting server's 275 default discovery URI. 277 or 279 o a link-format document, which indicates the specific services that 280 the requesting server wants to make known to the directory server. 282 The directory server integrates the information it received this way 283 into its resource directory. It MAY make the information available 284 to further directories, if it can ensure that a loop does not form. 285 The protocol used between directories to ensure loop-free operation 286 is outside the scope of this document. 288 The following example shows an endpoint using simple resource 289 discovery, by simply sending a POST with its links in the body to a 290 directory. 292 EP RD 293 | | 294 | -- POST /.well-known/core "..." ---> | 295 | | 296 | | 297 | <---- 2.01 Created ------------------------- | 298 | | 300 4.1. Finding a Directory Server 302 Endpoints that want to contact a directory server can obtain 303 candidate IP addresses for such servers in a number of ways. 305 In a 6LoWPAN, good candidates can be taken from: 307 o specific static configuration (e.g., anycast addresses), if any, 309 o the ABRO option of 6LoWPAN-ND [I-D.ietf-6lowpan-nd], 311 o other ND options that happen to point to servers (such as RDNSS), 313 o DHCPv6 options that might be defined later. 315 In networks with more inexpensive use of multicast, the candidate IP 316 address may be a well-known multicast address, i.e. directory servers 317 are found by simply sending POST requests to that well-known 318 multicast address (details TBD). 320 As some of these sources are just (more or less educated) guesses, 321 endpoints MUST make use of any error messages to very strictly rate- 322 limit requests to candidate IP addresses that don't work out. E.g., 323 an ICMP Destination Unreachable message (and, in particular, the port 324 unreachable code for this message) may indicate the lack of a CoAP 325 server on the candidate host, or a CoAP error response code such as 326 4.05 "Method Not Allowed" may indicate unwillingness of a CoAP server 327 to act as a directory server. 329 5. Resource Directory Function Set 331 This section defines the REST interfaces between an RD and endpoint 332 servers, which is called the Resource Directory Function Set. 333 Although the examples throughout this section assume use of CoAP 334 [I-D.ietf-core-coap], these REST interfaces can also be realized 335 using HTTP [RFC2616]. An RD implementing this specification MUST 336 support the discovery, registration, update, and removal interfaces 337 defined in this section and MAY support the validation interface. 338 For the purpose of validation, an endpoint implementing this 339 specification SHOULD support ETag validation on /.well-known/core 340 (which is very straightforward for static /.well-known/core link 341 documents). 343 Resource directory entries are designed to be easily exported to 344 other discovery mechanisms such as DNS-SD. For that reason, 345 parameters that would meaningfully be mapped to DNS are limited to a 346 maximum length of 63 bytes. 348 5.1. Discovery 350 Before an endpoint can make use of an RD, it must first know the RD's 351 IP address, port and the path of its RD Function Set. There can be 352 several mechanisms for discovering the RD including assuming a 353 default location (e.g. on an Edge Router in a LoWPAN), by assigning 354 an anycast address to the RD, using DHCP, or by discovering the RD 355 using the CoRE Link Format (also see Section 4.1). This section 356 defines discovery of the RD using the well-known interface of the 357 CoRE Link Format [I-D.ietf-core-link-format] as the required 358 mechanism. It is however expected that RDs will also be discoverable 359 via other methods depending on the deployment. 361 Discovery is performed by sending either a multicast or unicast GET 362 request to /.well-known/core and including a Resource Type (rt) 363 parameter [I-D.ietf-core-link-format] with the value "core.rd" in the 364 query string. Likewise, a Resource Type parameter value of "core.rd- 365 lookup" is used to discover the RD Lookup Function Set. Upon success, 366 the response will contain a payload with a link format entry for each 367 RD discovered, with the URL indicating the root resource of the RD. 368 When performing multicast discovery, the multicast IP address used 369 will depend on the scope required and the multicast capabilities of 370 the network. 372 An RD implementation of this specification MUST support query 373 filtering for the rt parameter as defined in 374 [I-D.ietf-core-link-format]. 376 The discovery request interface is specified as follows: 378 Interaction: EP -> RD 380 Method: GET 382 URI Template: /.well-known/core{?rt} 384 URI Template Variables: 386 rt := Resource Type (optional). MAY contain the value 387 "core.rd", "core.rd-lookup" or "core.rd*" 389 Content-Type: application/link-format (if any) 391 The following response codes are defined for this interface: 393 Success: 2.05 "Content" with an application/link-format payload 394 containing a matching entry for the RD resource. 396 Failure: 4.04 "Not Found" is returned in case no matching entry is 397 found for a unicast request. 399 Failure: No error response to a multicast request. 401 Failure: 4.00 "Bad Request" 403 The following example shows an endpoint discovering an RD using this 404 interface, thus learning that the base RD resource is at /rd. Note 405 that it is up to the RD to choose its base RD resource, although it 406 is recommended to use default locations where possible. 408 EP RD 409 | | 410 | ----- GET /.well-known/core?rt=core.rd* ------> | 411 | | 412 | | 413 | <---- 2.05 Content "; rt="core.rd" ------ | 414 | | 416 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 418 Res: 2.05 Content 419 ;rt="core.rd", 420 ;rt="core.rd-lookup" 422 5.2. Registration 424 After discovering the location of an RD Function Set, an endpoint MAY 425 register its resources using the registration interface. This 426 interface accepts a POST from an endpoint containing the list of 427 resources to be added to the directory as the message payload in the 428 CoRE Link Format along with query string parameters indicating the 429 name of the endpoint, its Domain and the lifetime of the 430 registration. All parameters except the endpoint name are optional. 431 The RD then creates a new resource or updates an existing resource in 432 the RD and returns its location. An endpoint MUST use that location 433 when refreshing registrations using this interface. endpoint 434 resources in the RD are kept active for the period indicated by the 435 lifetime parameter. The endpoint is responsible for refreshing the 436 entry within this period using either the registration or update 437 interface. The registration interface MUST be implemented to be 438 idempotent, so that registering twice with the same endpoint 439 parameter does not create multiple RD entries. 441 The registration request interface is specified as follows: 443 Interaction: EP -> RD 445 Method: POST 447 URI Template: /{+rd}{?ep,d,rt,lt,con} 449 URI Template Variables: 451 rd := RD Function Set path (mandatory). This is the path of the 452 RD Function Set. An RD SHOULD use the value "rd" for this 453 variable whenever possible. 455 ep := Endpoint (mandatory). The endpoint identifier or name of 456 the registering node, unique within that Domain. The maximum 457 length of this parameter is 63 bytes. 459 d := Domain (optional). The Domain to which this endpoint 460 belongs. The maximum length of this parameter is 63 bytes. 461 Optional. When this parameter is elided, the RD MAY associate 462 the endpoint with a configured default Domain. 464 rt := Endpoint Type (optional). The semantic type of the 465 endpoint. The maximum length of this parameter is 63 bytes. 466 Optional. 468 lt := Lifetime (optional). Lifetime of the registration in 469 seconds. Range of 60-4294967295. If no lifetime is included, 470 a default value of 86400 (24 hours) SHOULD be assumed. 472 con := Context (optional). This parameter sets the scheme, 473 address and port at which this server is available in the form 474 scheme://host:port. Optional. In the absence of this 475 parameter the scheme of the protocol, source IP address and 476 source port used to register are assumed. 478 Content-Type: application/link-format 480 The following response codes are defined for this interface: 482 Success: 2.01 "Created". The Location header MUST be included with 483 the new resource entry for the endpoint. This Location MUST be a 484 stable identifier generated by the RD as it is used for all 485 subsequent operations on this registration (update, delete). 487 Failure: 4.00 "Bad Request". Malformed request. 489 Failure: 5.03 "Service Unavailable". Service could not perform the 490 operation. 492 The following example shows an endpoint with the name "node1" 493 registering two resources to an RD using this interface. The 494 resulting location /rd/4521 is just an example of an RD generated 495 location. 497 EP RD 498 | | 499 | --- POST /rd?ep=node1 " | 500 | | 501 | | 502 | <-- 2.01 Created Location: /rd/4521 ---------- | 503 | | 505 Req: POST coap://rd.example.com/rd?ep=node1 506 Payload: 507 ;ct=41;rt="TemperatureC";if="sensor", 508 ;ct=41;rt="LightLux";if="sensor" 510 Res: 2.01 Created 511 Location: /rd/4521 513 5.3. Update 515 The update interface is used by an endpoint to refresh or update its 516 registration with an RD. To use the interface, the endpoint sends a 517 PUT request to the resource returned in the Location option in the 518 response to the first registration. An update MAY contain 519 registration parameters or a payload in CoRE Link Format if there 520 have been changes since the last registration or update. Paremeters 521 that have not changed SHOULD NOT be included in an update. 523 The update request interface is specified as follows: 525 Interaction: EP -> RD 527 Method: PUT 529 URI Template: /{+location}{?rt,lt,con} 531 URI Template Variables: 533 location := This is the Location path returned by the RD as a 534 result of a successful registration. 536 rt := Endpoint Type (optional). The semantic type of the 537 endpoint. The maximum length of this parameter is 63 btyes. 538 Optional. 540 lt := Lifetime (optional). Lifetime of the registration in 541 seconds. Range of 60-4294967295. If no lifetime is included, 542 a default value of 86400 (24 hours) SHOULD be assumed. 544 con := Context (optional). This parameter sets the scheme, 545 address and port at which this server is available in the form 546 scheme://host:port. Optional. In the absence of this 547 parameter the scheme of the protocol, source IP address and 548 source port used to register are assumed. 550 Content-Type: application/link-format (if any) 552 The following response codes are defined for this interface: 554 Success: 2.04 "Changed" in case the resource and/or lifetime was 555 successfully updated 557 Failure: 4.00 "Bad Request". Malformed request. 559 Failure: 5.03 "Service Unavailable". Service could not perform the 560 operation. 562 The following example shows an endpoint updating a new set of 563 resources to an RD using this interface. 565 EP RD 566 | | 567 | --- PUT /rd/4521 " | 568 | | 569 | | 570 | <-- 2.04 Changed ---------------------------- | 571 | | 573 Req: PUT /rd/4521 574 Payload: 575 ;ct=41;ins="Indoor";rt="TemperatureC";if="sensor", 576 ;ct=41;ins="Outdoor";rt="TemperatureC";if="sensor", 577 ;ct=41;rt="LightLux";if="sensor" 579 Res: 2.04 Changed 581 5.4. Validation 583 In some cases, an RD may want to validate that it has the latest 584 version of an endpoint's resources. This can be performed with a GET 585 on the well-known interface of the CoRE Link Format including the 586 latest ETag stored for that endpoint. For the purpose of validation, 587 an endpoint implementing this specification SHOULD support ETag 588 validation on /.well-known/core. 590 The validation request interface is specified as follows: 592 Interaction: RD -> EP 594 Method: GET 596 Path: /.well-known/core 598 Parameters: None 600 ETag: The ETag option MUST be included 602 The following responses codes are defined for this interface: 604 Success: 2.03 "Valid" in case the ETag matches 606 Success: 2.05 "Content" in case the ETag does not match, the 607 response MUST include the most recent resource representation 608 (application/link-format) and its corresponding ETag. 610 Failure: 4.00 "Bad Request". Malformed request. 612 The following examples shows a successful validation. 614 EP RD 615 | | 616 | <--- GET /.well-known/core ETag: 0x40 -------- | 617 | | 618 | | 619 | --- 2.03 Valid -----------------------------> | 620 | | 622 Req: GET /.well-known/core 623 ETag: 0x40 625 Res: 2.03 Valid 627 5.5. Removal 629 Although RD entries have soft state and will eventually timeout after 630 their lifetime, an endpoint SHOULD explicitly remove its entry from 631 the RD if it knows it will no longer be available (for example on 632 shut-down). This is accomplished using a removal interface on the RD 633 by performing a DELETE on the endpoint resource. 635 The removal request interface is specified as follows: 637 Interaction: EP -> RD 639 Method: DELETE 641 URI Template: /{+location} 643 URI Template Variables: 645 location := This is the Location path returned by the RD as a 646 result of a successful registration. 648 The following responses codes are defined for this interface: 650 Success: 2.02 "Deleted" upon successful deletion 652 Failure: 4.00 "Bad Request". Malformed request. 654 Failure: 5.03 "Service Unavailable". Service could not perform the 655 operation. 657 The following examples shows successful removal of the endpoint from 658 the RD. 660 EP RD 661 | | 662 | --- DELETE /rd/4521 ------------------------> | 663 | | 664 | | 665 | <-- 2.02 Deleted ---------------------------- | 666 | | 668 Req: DELETE /rd/4521 670 Res: 2.02 Deleted 672 6. RD Lookup Function Set 674 In order for an RD to be used for discovering resources registered 675 with it, a lookup interface can be provided using this function set. 676 This lookup interface is defined as a default, and it is assumed that 677 RDs may also support lookups to return resource descriptions in 678 alternative formats (e.g. Atom or HTML Link) or using more advanced 679 interfaces (e.g. supporting context or semantic based lookup). 681 This function set allows lookups for Domains, endpoints and resources 682 using attributes defined in the RD Function Set and for use with the 683 CoRE Link Format. The result of a lookup request is the list of 684 links (if any) in CoRE Link Format corresponding to the type of 685 lookup. The target of these links SHOULD be the actual location of 686 the Domain, endpoint or resource, but MAY be an intermediate proxy 687 e.g. in the case of an HTTP lookup interface for CoAP endpoints. 689 The lookup interface is specified as follows: 691 Interaction: Client -> RD 693 Method: GET 695 URI Template: /{+rd-lookup-base}/{lookup-type}{?d,ep,resource-param} 697 Parameters: 699 rd-lookup-base := RD Lookup Function Set path (mandatory). This 700 is the path of the RD Lookup Function Set. An RD SHOULD use the 701 value "rd-lookup" for this variable whenever possible. 703 lookup-type := ("d", "ep", "res") (mandatory) This variable is 704 used to select the kind of lookup to perform (Domain, endpoint 705 or resource). 707 ep := endpoint (optional). Used for endpoint and resource 708 lookups. 710 d := Domain (optional). Used for Domain, endpoint and resource 711 lookups. 713 rt := endpoint type (optional). Used for endpoint lookups. 715 resource-param := Link attribute parameters (optional). Any 716 link attribute as defined in Section 4.1 of 717 [I-D.ietf-core-link-format], used for resource lookups. 719 The following responses codes are defined for this interface: 721 Success: 2.05 "Content" with an application/link-format payload 722 containing a matching entries for the lookup. 724 Failure: 4.04 "Not Found" in case no matching entry is found for a 725 unicast request. 727 Failure: No error response to a multicast request. 729 Failure: 4.00 "Bad Request". Malformed request. 731 Failure: 5.03 "Service Unavailable". Service could not perform the 732 operation. 734 The following example shows a client performing a resource lookup: 736 Client RD 737 | | 738 | ----- GET /rd-lookup/res?rt=Temperature -----------------> | 739 | | 740 | | 741 | <-- 2.05 Content ";rt="Temperature" ---- | 742 | | 744 Req: GET /rd-lookup/res?rt=Temperature 746 Res: 2.05 Content 747 ;rt="Temperature" 749 The following example shows a client performing an endpoint lookup: 751 Client RD 752 | | 753 | ----- GET /rd-lookup/ep?rt=PowerNode --------------------> | 754 | | 755 | | 756 | <-- 2.05 Content ";ep="node5" ----------- | 757 | | 759 Req: GET /rd-lookup/ep?rt=PowerNode 761 Res: 2.05 Content 762 ;ep="node5" 763 ;ep="node7" 765 The following example shows a client performing a Domain lookup: 767 Client RD 768 | | 769 | ----- GET /rd-lookup/domain -----------------------------> | 770 | | 771 | | 772 | <-- 2.05 Content ";d=domain1,;d=domain2 --------- | 773 | | 775 Req: GET /rd-lookup/domain 777 Res: 2.05 Content 778 ;d=domain1, 779 ;d=domain2 781 7. New Link-Format Attributes 783 When using the CoRE Link Format to describe resources being 784 discovered by or posted to a resource directory service, additional 785 information about those resources is useful. This specification 786 defines the following new attributes for use in the CoRE Link Format 787 [I-D.ietf-core-link-format]: 789 link-extension = ( "ins" "=" quoted-string ) ; Max 63 bytes 790 link-extension = ( "exp" ) 792 7.1. Resource Instance 'ins' attribute 794 The Resource Instance "ins" attribute is an identifier for this 795 resource, which makes it possible to distinguish from other similar 796 resources. This attribute is similar in use to the "Instance" 797 portion of a DNS-SD record, and SHOULD be unique across resources 798 with the same Resource Type attribute in the Domain it is used. A 799 Resource Instance might be a descriptive string like "Ceiling Light, 800 Room 3", a short ID like "AF39" or a unique UUID or iNumber. This 801 attribute is used by a Resource Directory to distinguish between 802 multiple instances of the same resource type within a system. 804 This attribute MUST be no more than 63 bytes in length. The resource 805 identifier attribute MUST NOT appear more than once in a link 806 description. 808 7.2. Export 'exp' attribute 810 The Export "exp" attribute is used as a flag to indicate that a link 811 description MAY be exported by a resource directory to external 812 directories. 814 The CoRE Link Format is used for many purposes between CoAP 815 endpoints. Some are useful mainly locally, for example checking the 816 observability of a resource before accessing it, determining the size 817 of a resource, or traversing dynamic resource structures. However, 818 other links are very useful to be exported to other directories, for 819 example the entry point resource to a functional service. 821 8. Security Considerations 823 This document needs the same security considerations as described in 824 Section 7 of [RFC5988] and Section 6 of [I-D.ietf-core-link-format]. 825 The /.well-known/core resource may be protected e.g. using DTLS when 826 hosted on a CoAP server as described in [I-D.ietf-core-coap]. 828 Access control SHOULD be performed separately for the RD Function Set 829 and the RD Lookup Function Set, as different endpoints may be 830 authorized to register with an RD from those authorized to lookup 831 endpoints from the RD. Such access control SHOULD be performed in as 832 fine-grained a level as possible. For example access control for 833 lookups could be performed either at the Domain, endpoint or resource 834 level. 836 9. IANA Considerations 838 "core.rd" and "core.rd-lookup" resource type needs to be registered 839 when the appropriate registry is created by 840 [I-D.ietf-core-link-format]. 842 The "exp" attribute needs to be registered when a future Web Linking 843 attribute is created. 845 10. Acknowledgments 847 Szymon Sasin, Kerry Lynn, Peter van der Stok, Anders Brandt, Matthieu 848 Vial, Sampo Ukkola and Linyi Tian have provided helpful comments, 849 discussions and ideas to improve and shape this document. The 850 authors would also like to thank their collagues from the EU FP7 851 SENSEI project, where many of the resource directory concepts were 852 originally developed. 854 11. Changelog 856 Changes from -03 to -04: 858 o Added the ins= parameter back for the DNS-SD mapping. 860 o Integrated the Simple Directory Discovery from Carsten. 862 o Editorial improvements. 864 o Fixed the use of ETags. 866 Changes from -02 to -03: 868 o Changed the endpoint name back to a single registration 869 parameter ep= and removed the h= and ins= parameters. 871 o Updated REST interface descriptions to use RFC6570 URI Template 872 format. 874 o Introduced an improved RD Lookup design as its own function set. 876 o Improved the security considerations section. 878 o Made the POST registration interface idempotent by requiring the 879 ep= paramter to be present. 881 Changes from -01 to -02: 883 o Added a terminology section. 885 o Changed the inclusing of an ETag in registration or update to a 886 MAY. 888 o Added the concept of an RD Domain and a registration parameter 889 for it. 891 o Recommended the Location returned from a registration to be 892 stable, allowing for endpoint and Domain information to be changed 893 during updates. 895 o Changed the lookup interface to accept endpoint and Domain as 896 query string parameters to control the scope of a lookup. 898 12. References 900 12.1. Normative References 902 [I-D.ietf-core-link-format] 903 Shelby, Z., "CoRE Link Format", 904 draft-ietf-core-link-format-14 (work in progress), 905 June 2012. 907 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 908 Requirement Levels", BCP 14, RFC 2119, March 1997. 910 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 912 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 913 and D. Orchard, "URI Template", RFC 6570, March 2012. 915 12.2. Informative References 917 [I-D.brandt-coap-subnet-discovery] 918 Brandt, A., "Discovery of CoAP servers across subnets", 919 draft-brandt-coap-subnet-discovery-00 (work in progress), 920 March 2011. 922 [I-D.ietf-6lowpan-nd] 923 Shelby, Z., Chakrabarti, S., and E. Nordmark, "Neighbor 924 Discovery Optimization for Low Power and Lossy Networks 925 (6LoWPAN)", draft-ietf-6lowpan-nd-18 (work in progress), 926 October 2011. 928 [I-D.ietf-core-coap] 929 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 930 "Constrained Application Protocol (CoAP)", 931 draft-ietf-core-coap-10 (work in progress), June 2012. 933 [I-D.vanderstok-core-bc] 934 Stok, P. and K. Lynn, "CoAP Utilization for Building 935 Control", draft-vanderstok-core-bc-05 (work in progress), 936 October 2011. 938 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 939 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 940 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 942 Authors' Addresses 944 Zach Shelby 945 Sensinode 946 Kidekuja 2 947 Vuokatti 88600 948 FINLAND 950 Phone: +358407796297 951 Email: zach@sensinode.com 953 Srdjan Krco 954 Ericsson 956 Phone: 957 Email: srdjan.krco@ericsson.com 959 Carsten Bormann 960 Universitaet Bremen TZI 961 Postfach 330440 962 Bremen D-28359 963 Germany 965 Phone: +49-421-218-63921 966 Fax: +49-421-218-7000 967 Email: cabo@tzi.org