idnits 2.17.1 draft-shelby-core-resource-directory-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 17, 2012) is 4359 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 (-14) exists of draft-ietf-core-link-format-06 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-06 == Outdated reference: A later version (-05) exists of draft-vanderstok-core-bc-03 -- 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 (~~), 4 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: November 18, 2012 Ericsson 6 May 17, 2012 8 CoRE Resource Directory 9 draft-shelby-core-resource-directory-03 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 November 18, 2012. 41 Copyright Notice 43 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . . 4 61 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . . 5 62 3.2. Use Case: Home and Building Automation . . . . . . . . . . 6 63 4. Resource Directory Function Set . . . . . . . . . . . . . . . 6 64 4.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4.4. Validation . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4.5. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 5. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . . 14 70 6. New Link-Format Attributes . . . . . . . . . . . . . . . . . . 16 71 6.1. Export 'exp' attribute . . . . . . . . . . . . . . . . . . 16 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 73 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 74 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 75 10. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 17 76 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 77 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 78 11.2. Informative References . . . . . . . . . . . . . . . . . . 19 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 81 1. Introduction 83 The Constrained RESTful Environments (CoRE) working group aims at 84 realizing the REST architecture in a suitable form for the most 85 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 86 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 87 machine (M2M) applications such as smart energy and building 88 automation. 90 The discovery of resources offered by a constrained server is very 91 important in machine-to-machine applications where there are no 92 humans in the loop and static interfaces result in fragility. The 93 discovery of resources provided by an HTTP Web Server is typically 94 called Web Linking [RFC5988]. The use of Web Linking for the 95 description and discovery of resources hosted by constrained web 96 servers is specified by the CoRE Link Format 97 [I-D.ietf-core-link-format]. This specification however only 98 describes how to discover resources from the web server that hosts 99 them by requesting /.well-known/core. In many M2M scenarios, direct 100 discovery of resources is not practical due to sleeping nodes, 101 disperse networks, or networks where multicast traffic is 102 inefficient. These problems can be solved by employing an entity 103 called a Resource Directory (RD), which hosts descriptions of 104 resources held on other servers, allowing lookups to be performed for 105 those resources. 107 This document specifies the web interfaces that a Resource Directory 108 supports in order for web servers to discover the RD and to 109 registrer, maintain, lookup and remove resources descriptions. 110 Furthermore, new link attributes useful in conjunction with a 111 Resource Directory are defined. Although the examples in this 112 document show the use of these interfaces with CoAP 113 [I-D.ietf-core-coap], they may be applied in an equivalent manner to 114 HTTP [RFC2616]. 116 2. Terminology 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in [RFC2119]. 122 This specification requires readers to be familiar with all the terms 123 and concepts that are discussed in [RFC5988] and 124 [I-D.ietf-core-link-format]. Readers should also be familiar with 125 the terms and concepts discussed in [I-D.ietf-core-coap]. The URI 126 Template format is used to describe the REST interfaces defined in 127 this specification [RFC6570]. This specification makes use of the 128 following additional terminology: 130 Resource Directory 131 An web entity that stores information about web resources and 132 implements the REST interfaces defined in this specification for 133 registration and lookup of those resources. 135 Domain 136 In the context of a Resource Directory, a domain is a logical 137 grouping of end-points. All end-point within a domain MUST be 138 unique. This specification assumes that the list of domains 139 supported by an RD is pre-configured by that RD. 141 End-point 142 An end-point (EP) is a term used to describe a web server or 143 client in [I-D.ietf-core-coap]. In the context of this 144 specificaiton an end-point is used to describe a web server that 145 registers resources to the Resource Directory. An end-point is 146 identified by its end-point name, which is included during 147 registration, and MUST be unique within the associated domain of 148 the registration. 150 3. Architecture and Use Cases 152 The resource directory architecture is shown in Figure 1. A Resource 153 Directory (RD) is used as a repository for Web Links [RFC5988] about 154 resources hosted on other web servers, which are called end-points 155 (EP). An end-point is a web server associated with a port, thus a 156 physical node may host one or more end-points. The RD implements a 157 set of REST interfaces for end-points to register and maintain sets 158 of Web Links (called resource directory entries), for the RD to 159 validate entries, and for clients to lookup resources from the RD. 160 End-points themselves can also act as clients. An RD can be 161 logically segmented by the use of Domains. The domain an end-point 162 is associated with can be defined by the RD or configured by an 163 outside entity. 165 End-points are assumed to proactively register and maintain resource 166 directory entries on the RD, which are soft state and need to be 167 periodially refreshed. An EP is provided with interfaces to 168 register, update and remove a resource directory entry. Furthermore, 169 a mechanism to discover a RD using the CoRE Link Format is defined. 170 It is also possible for an RD to proactively discover Web Links from 171 EPs and add them as resource directory entries, or to validate 172 existing resource directory entries. A lookup interface for 173 discovering any of the Web Links held in the RD is provided using the 174 CoRE Link Format. 176 Registration Lookup 177 +----+ | | 178 | EP |---- | | 179 +----+ ---- | | 180 --|- +------+ | 181 +----+ | ----| | | +--------+ 182 | EP | ---------|-----| RD |----|-----| Client | 183 +----+ | ----| | | +--------+ 184 --|- +------+ | 185 +----+ ---- | | 186 | EP |---- | | 187 +----+ 189 Figure 1: The resource directory architecture. 191 3.1. Use Case: Cellular M2M 193 Over the last few years, mobile operators around the world have 194 focused on development of M2M solutions in order to expand the 195 business to the new type of users, i.e. machines. The machines are 196 connected directly to a mobile network using appropriate embedded air 197 interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short and 198 wide range wireless interfaces. From the system design point of 199 view, the ambition is to design horizontal solutions that can enable 200 utilization of machines in different applications depending on their 201 current availability and capabilities as well as application 202 requirements, thus avoiding silo like solutions. One of the crucial 203 enablers of such design is the ability to discover resources 204 (machines - End Points) capable of providing required information at 205 a given time or acting on instructions from the end users. 207 In a typical scenario, during a boot-up procedure (and periodically 208 afterwards), the machines (EPs) register with a Resource Directory 209 (for example EPs installed on vehicles enabling tracking of their 210 position for the fleet management purposes and monitoring environment 211 parameters) hosted by the mobile operator or somewhere else in the 212 network, submiting a description of own capabilities. Due to the 213 usual network configuration of mobile networks, the EPs attached to 214 the mobile network do not have routable addresses. Therefore, a 215 remote server is usually used to provide proxy access to the EPs. 216 The address of each (proxy) EP on this server is included in the 217 resource description stored in the RD. The users, for example mobile 218 applications for environment monitoring, contact the RD, look-up the 219 EPs capable of providing information about the environment using 220 appropriate set of tags, obtain information on how to contact them 221 (URLs of the proxy server) and then initate interaction to obtain 222 information that is finally processed, displayed on the screen and 223 usually stored in a database. Similarly, fleet management systems 224 provide a set of credentials along with the appropriate tags to the 225 RD to look-up for EPs deployed on the vehicles the application is 226 responsible for. 228 3.2. Use Case: Home and Building Automation 230 Home and commercial building automation systems can benefit from the 231 use of M2M web services. The use of CoRE in home automation across 232 multiple subnets is described in [I-D.brandt-coap-subnet-discovery] 233 and in commercial building automation in [I-D.vanderstok-core-bc]. 234 The discovery requirements of these applications are demanding. Home 235 automation usually relies on run-time discovery to commision the 236 system, whereas in building automation a combination of professional 237 commissioning and run-time discovery is used. Both home and building 238 automation involve peer-to-peer interactions between end-points, and 239 involve battery-powered sleeping devices. 241 The exporting of resource information to other discovery systems is 242 also important in these automation applications. In home automation 243 there is a need to interact with other consumer electronics, which 244 may already support DNS-SD, and in building automation larger 245 resource directories or DNS-SD covering multiple buildings. 247 4. Resource Directory Function Set 249 This section defines the REST interfaces between an RD and end-point 250 servers, which is called the Resource Directory Function Set. 251 Although the examples throughout this section assume use of CoAP 252 [I-D.ietf-core-coap], these REST interfaces can also be realized 253 using HTTP [RFC2616]. An RD implementing this specification MUST 254 support the discovery, registration, update, and removal interfaces 255 defined in this section and MAY support the validation interface. 256 For the purpose of validation, an end-point implementing this 257 specification SHOULD support Etag validation on /.well-known/core. 259 4.1. Discovery 261 Before an end-point can make use of an RD, it must first know its IP 262 address, port and the path of its RD Function Set. There can be 263 several mechanisms for discovering the RD including assuming a 264 default location (e.g. on an Edge Router in a LoWPAN), by assigning 265 an anycast address to the RD, using DHCP, or by discovering the RD 266 using the CoRE Link Format. This section defines discovery of the RD 267 using the well-known interface of the CoRE Link Format 268 [I-D.ietf-core-link-format] as the required mechanism. It is however 269 expected that RDs will also be discoverable via other methods 270 depending on the deployment. 272 Discovery is performed by sending either a multicast or unicast GET 273 request to /.well-known/core and including a Resource Type (rt) 274 parameter [I-D.ietf-core-link-format] with the value "core.rd" in the 275 query string. Likewise, a Resource Type parameter value of "core.rd- 276 lookup" is used to discover the RD Lookup Function Set. Upon success, 277 the response will contain a payload with a link format entry for each 278 RD discovered, with the URL indicating the root resource of the RD. 279 When performing multicast discovery, the multicast IP address used 280 will depend on the scope required and the multicast capabilities of 281 the network. 283 An implementation of this specification MUST support query filtering 284 for the rt parameter as defined in [I-D.ietf-core-link-format]. 286 The discovery interface is specified as follows: 288 Interaction: EP -> RD 290 Method: GET 292 URI Template: /.well-known/core{?rt} 294 URI Template Variables: 296 rt := Resource Type (optional). MAY contain the value 297 "core.rd", "core.rd-lookup" or "core.rd*" 299 Content-Type: application/link-format (if any) 301 Success: 2.05 "Content" with an application/link-format payload 302 containing a matching entry for the RD resource. 304 Failure: 4.04 "Not Found" is returned in case no matching entry is 305 found for a unicast request. 307 Failure: No error response to a multicast request. 309 Failure: 4.00 "Bad Request" 311 The following example shows an end-point discovering an RD using this 312 interface, thus learning that the base RD resource is at /rd. Note 313 that it is up to the RD to choose its base RD resource, although it 314 is recommended to use default locations where possible. 316 End-point RD 317 | | 318 | ----- GET /.well-known/core?rt=core.rd* ------> | 319 | | 320 | | 321 | <---- 2.05 Content "; rt="core.rd" ------ | 322 | | 324 Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* 326 Res: 2.05 Content 327 ;rt="core.rd", 328 ;rt="core.rd-lookup" 330 4.2. Registration 332 After discovering the location of an RD Function Set, an end-point 333 MAY register its resources using the registration interface. This 334 interface accepts a POST from an end-point containing the list of 335 resources to be added to the directory as the message payload in the 336 CoRE Link Format along with query string parameters indicating the 337 name of the end-point, its domain and the lifetime of the 338 registration. All parameters except the end-point name are optional. 339 The RD then creates a new resource or updates an existing resource in 340 the RD and returns its location. An end-point MUST use that location 341 when refreshing registrations using this interface. End-point 342 resources in the RD are kept active for the period indicated by the 343 lifetime parameter. The end-point is responsible for refreshing the 344 entry within this period using either the registration or update 345 interface. The registration interface MUST be implemented to be 346 idempotent, so that registering twice with the same end-point 347 parameter does not create multiple RD entries. 349 The registration interface is specified as follows: 351 Interaction: EP -> RD 353 Method: POST 355 URI Template: /{+rd}{?ep,d,rt,lt,con} 357 URI Template Variables: 359 rd := RD Function Set path (mandatory). This is the path of the 360 RD Function Set. An RD SHOULD use the value "rd" for this 361 variable whenever possible. 363 ep := End-point (mandatory). The end-point identifier or name 364 of the registering node, unique within that domain. The 365 maximum length of this parameter is 63 octets. 367 d := Domain (optional). The domain to which this end-point 368 belongs. The maximum length of this parameter is 63 octets. 369 Optional. When this parameter is elided, the RD MAY associate 370 the end-point with a configured default domain. 372 rt := End-point Type (optional). The semantic type of the end- 373 point. The maximum length of this parameter is 63 octets. 374 Optional. 376 lt := Lifetime (optional). Lifetime of the registration in 377 seconds. Range of 60-4294967295. If no lifetime is included, 378 a default value of 86400 (24 hours) SHOULD be assumed. 380 con := Context (optional). This parameter sets the scheme, 381 address and port at which this server is available in the form 382 scheme://host:port. Optional. In the absence of this 383 parameter the scheme of the protocol, source IP address and 384 source port used to register are assumed. 386 Content-Type: application/link-format 388 Etag: The Etag option MAY be included to allow an RD to perform 389 validation in the future. 391 Success: 2.01 "Created". The Location header MUST be included with 392 the new resource entry for the end-point. This Location MUST be a 393 stable identifier generated by the RD as it is used for all 394 subsequent operations on this registration (update, delete). 396 Failure: 4.00 "Bad Request". Malformed request. 398 Failure: 5.03 "Service Unavailable". Service could not perform the 399 operation. 401 The following example shows an end-point with the name "node1" 402 registering two resources to an RD using this interface. The 403 resulting location /rd/4521 is just an example of an RD generated 404 location. 406 End-point RD 407 | | 408 | --- POST /rd?ep=node1 " | 409 | | 410 | | 411 | <-- 2.01 Created Location: /rd/4521 ---------- | 412 | | 414 Req: POST coap://rd.example.com/rd?ep=node1 415 Etag: 0x3f 416 Payload: 417 ;ct=41;rt="TemperatureC";if="sensor", 418 ;ct=41;rt="LightLux";if="sensor" 420 Res: 2.01 Created 421 Location: /rd/4521 423 4.3. Update 425 The update interface is used by an end-point to refresh or update its 426 registration with an RD. To use the interface, the end-point sends a 427 PUT request to the resource returned in the Location option in the 428 response to the first registration. An update MAY contain 429 registration parameters or a payload in CoRE Link Format if there 430 have been changes since the last registration or update. Paremeters 431 that have not changed SHOULD NOT be included in an update. 433 The update interface is specified as follows: 435 Interaction: EP -> RD 437 Method: PUT 439 URI Template: /{+location}{?rt,lt,con} 441 URI Template Variables: 443 location := This is the Location path returned by the RD as a 444 result of a successful registration. 446 rt := End-point Type (optional). The semantic type of the end- 447 point. The maximum length of this parameter is 63 octets. 448 Optional. 450 lt := Lifetime (optional). Lifetime of the registration in 451 seconds. Range of 60-4294967295. If no lifetime is included, 452 a default value of 86400 (24 hours) SHOULD be assumed. 454 con := Context (optional). This parameter sets the scheme, 455 address and port at which this server is available in the form 456 scheme://host:port. Optional. In the absence of this 457 parameter the scheme of the protocol, source IP address and 458 source port used to register are assumed. 460 Content-Type: application/link-format (if any) 462 Etag: The Etag option MAY be included to allow an RD to compare the 463 existing entry and perform validation in the future. 465 Success: 2.04 "Changed" in case the resource and/or lifetime was 466 successfully updated 468 Failure: 4.00 "Bad Request". Malformed request. 470 Failure: 5.03 "Service Unavailable". Service could not perform the 471 operation. 473 The following example shows an end-point updating a new set of 474 resources to an RD using this interface. 476 End-point RD 477 | | 478 | --- PUT /rd/4521 " | 479 | | 480 | | 481 | <-- 2.04 Changed ---------------------------- | 482 | | 484 Req: PUT /rd/4521 485 Etag: 0x40 486 Payload: 487 ;ct=41;ins="Indoor";rt="TemperatureC";if="sensor", 488 ;ct=41;ins="Outdoor";rt="TemperatureC";if="sensor", 489 ;ct=41;rt="LightLux";if="sensor" 491 Res: 2.04 Changed 493 4.4. Validation 495 In some cases, an RD may want to validate that it has the latest 496 version of an end-point's resources. This can be performed with a 497 GET on the well-known interface of the CoRE Link Format including the 498 latest Etag stored for that end-point. For the purpose of 499 validation, an end-point implementing this specification SHOULD 500 support Etag validation on /.well-known/core. 502 The validation interface is specified as follows: 504 Interaction: RD -> EP 506 Method: GET 508 Path: /.well-known/core 510 Parameters: None 512 Content-Type: application/link-format (if any) 514 Etag: The Etag option MUST be included 516 Success: 2.03 "Valid" in case the Etag matches 518 Success: 2.05 "Content" in case the Etag does not match, the 519 response MUST include the most recent resource representation and 520 its corresponding Etag. 522 Failure: 4.00 "Bad Request". Malformed request. 524 The following examples shows a successful validation. 526 End-point RD 527 | | 528 | <--- GET /.well-known/core Etag: 0x40 -------- | 529 | | 530 | | 531 | --- 2.03 Valid -----------------------------> | 532 | | 534 Req: GET /.well-known/core 535 Etag: 0x40 537 Res: 2.03 Valid 539 4.5. Removal 541 Although RD entries have soft state and will eventually timeout after 542 their lifetime, an end-point SHOULD explicitly remove its entry from 543 the RD if it knows it will no longer be available (for example on 544 shut-down). This is accomplished using a removal interface on the RD 545 by performing a DELETE on the end-point resource. 547 The removal interface is specified as follows: 549 Interaction: EP -> RD 551 Method: DELETE 553 URI Template: /{+location} 555 URI Template Variables: 557 location := This is the Location path returned by the RD as a 558 result of a successful registration. 560 Content-Type: None 562 Success: 2.02 "Deleted" upon successful deletion 564 Failure: 4.00 "Bad Request". Malformed request. 566 Failure: 5.03 "Service Unavailable". Service could not perform the 567 operation. 569 The following examples shows successful removal of the end-point from 570 the RD. 572 End-point RD 573 | | 574 | --- DELETE /rd/4521 ------------------------> | 575 | | 576 | | 577 | <-- 2.02 Deleted ---------------------------- | 578 | | 580 Req: DELETE /rd/4521 582 Res: 2.02 Deleted 584 5. RD Lookup Function Set 586 In order for an RD to be used for discovering resources registered 587 with it, a lookup interface can be provided using this function set. 588 This lookup interface is defined as a default, and it is assumed that 589 RDs may also support lookups to return resource descriptions in 590 alternative formats (e.g. Atom or HTML Link) or using more advanced 591 interfaces (e.g. supporting context or semantic based lookup). 593 This function set allows lookups for domains, end-points and 594 resources using attributes defined in the RD Function Set and for use 595 with the CoRE Link Format. The result of a lookup request is the 596 list of links (if any) in CoRE Link Format corresponding to the type 597 of lookup. The target of these links SHOULD be the actual location 598 of the domain, end-point or resource, but MAY be an intermediate 599 proxy e.g. in the case of an HTTP lookup interface for CoAP end- 600 points. 602 The lookup interface is specified as follows: 604 Interaction: Client -> RD 606 Method: GET 608 URI Template: /{+rd-lookup-base}/{lookup-type}{?d,ep,resource-param} 610 Parameters: 612 rd-lookup-base := RD Lookup Function Set path (mandatory). This 613 is the path of the RD Lookup Function Set. An RD SHOULD use the 614 value "rd-lookup" for this variable whenever possible. 616 lookup-type := ("d", "ep", "res") (mandatory) This variable is 617 used to select the kind of lookup to perform (domain, end-point 618 or resource). 620 ep := End-point (optional). Used for end-point and resource 621 lookups. 623 d := Domain (optional). Used for domain, end-point and resource 624 lookups. 626 rt := End-point type (optional). Used for end-point lookups. 628 resource-param := Link attribute parameters (optional). Any 629 link attribute as defined in Section 4.1 of 630 [I-D.ietf-core-link-format], used for resource lookups. 632 Content-Type: application/link-format (if any) 634 Success: 2.05 "Content" with an application/link-format payload 635 containing a matching entries for the lookup. 637 Failure: 4.04 "Not Found" in case no matching entry is found for a 638 unicast request. 640 Failure: No error response to a multicast request. 642 Failure: 4.00 "Bad Request". Malformed request. 644 Failure: 5.03 "Service Unavailable". Service could not perform the 645 operation. 647 The following example shows a client performing a resource lookup: 649 Client RD 650 | | 651 | ----- GET /rd-lookup/res?rt=Temperature -----------------> | 652 | | 653 | | 654 | <-- 2.05 Content ";rt="Temperature" ---- | 655 | | 657 Req: GET /rd-lookup/res?rt=Temperature 659 Res: 2.05 Content 660 ;rt="Temperature" 662 The following example shows a client performing an end-point lookup: 664 Client RD 665 | | 666 | ----- GET /rd-lookup/ep?rt=PowerNode --------------------> | 667 | | 668 | | 669 | <-- 2.05 Content ";ep="node5" ----------- | 670 | | 672 Req: GET /rd-lookup/ep?rt=PowerNode 674 Res: 2.05 Content 675 ;ep="node5" 676 ;ep="node7" 678 The following example shows a client performing a domain lookup: 680 Client RD 681 | | 682 | ----- GET /rd-lookup/domain -----------------------------> | 683 | | 684 | | 685 | <-- 2.05 Content ";d=domain1,;d=domain2 --------- | 686 | | 688 Req: GET /rd-lookup/domain 690 Res: 2.05 Content 691 ;d=domain1, 692 ;d=domain2 694 6. New Link-Format Attributes 696 When using the CoRE Link Format to describe resources being 697 discovered by or posted to a resource directory service, additional 698 information about those resources is useful. This specification 699 defines the following new attributes for use in the CoRE Link Format 700 [I-D.ietf-core-link-format]: 702 link-extension = ( "exp" ) 704 6.1. Export 'exp' attribute 706 The Export "exp" attribute is used as a flag to indicate that a link 707 description MAY be exported by a resource directory to external 708 directories. 710 The CoRE Link Format is used for many purposes between CoAP end- 711 points. Some are useful mainly locally, for example checking the 712 observability of a resource before accessing it, determining the size 713 of a resource, or traversing dynamic resource structures. However, 714 other links are very useful to be exported to other directories, for 715 example the entry point resource to a functional service. 717 7. Security Considerations 719 This document needs the same security considerations as described in 720 Section 7 of [RFC5988] and Section 6 of [I-D.ietf-core-link-format]. 721 The /.well-known/core resource may be protected e.g. using DTLS when 722 hosted on a CoAP server as described in [I-D.ietf-core-coap]. 724 Access control SHOULD be performed separately for the RD Function Set 725 and the RD Lookup Function Set independently, as different end-points 726 may be authorized to register with an RD from those authorized to 727 lookup end-points from the RD. Such access control SHOULD be 728 performed in as fine-grained a level as possible. For example access 729 control for lookups could be performed either at the domain, end- 730 point or resource level. 732 8. IANA Considerations 734 "core.rd" and "core.rd-lookup" resource type needs to be registered 735 when the appropriate registry is created by 736 [I-D.ietf-core-link-format]. 738 The "exp" attribute needs to be registered when a future Web Linking 739 attribute is created. 741 9. Acknowledgments 743 Szymon Sasin, Carsten Bormann, Kerry Lynn, Peter van der Stok, Anders 744 Brandt, Matthieu Vial, Sampo Ukkola and Linyi Tian have provided 745 helpful comments, discussions and ideas to improve and shape this 746 document. The authors would also like to thank their collagues from 747 the EU FP7 SENSEI project, where many of the resource directory 748 concepts were originally developed. 750 10. Changelog 752 Changes from -02 to -03: 754 o Changed the end-point name back to a single registration 755 parameter ep= and removed the h= and ins= parameters. 757 o Updated REST interface descriptions to use RFC6570 URI Template 758 format. 760 o Introduced an improved RD Lookup design as its own function set. 762 o Improved the security considerations section. 764 o Made the POST registration interface idempotent by requiring the 765 ep= paramter to be present. 767 Changes from -01 to -02: 769 o Added a terminology section. 771 o Changed the inclusing of an Etag in registration or update to a 772 MAY. 774 o Added the concept of an RD domain and a registration parameter 775 for it. 777 o Recommended the Location returned from a registration to be 778 stable, allowing for end-point and domain information to be 779 changed during updates. 781 o Changed the lookup interface to accept end-point and domain as 782 query string parameters to control the scope of a lookup. 784 11. References 786 11.1. Normative References 788 [I-D.ietf-core-link-format] 789 Shelby, Z., "CoRE Link Format", 790 draft-ietf-core-link-format-06 (work in progress), 791 June 2011. 793 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 794 Requirement Levels", BCP 14, RFC 2119, March 1997. 796 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 798 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 799 and D. Orchard, "URI Template", RFC 6570, March 2012. 801 11.2. Informative References 803 [I-D.brandt-coap-subnet-discovery] 804 Brandt, A., "Discovery of CoAP servers across subnets", 805 draft-brandt-coap-subnet-discovery-00 (work in progress), 806 March 2011. 808 [I-D.ietf-core-coap] 809 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 810 "Constrained Application Protocol (CoAP)", 811 draft-ietf-core-coap-06 (work in progress), May 2011. 813 [I-D.vanderstok-core-bc] 814 Stok, P. and K. Lynn, "CoAP Utilization for Building 815 Control", draft-vanderstok-core-bc-03 (work in progress), 816 March 2011. 818 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 819 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 820 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 822 Authors' Addresses 824 Zach Shelby 825 Sensinode 826 Kidekuja 2 827 Vuokatti 88600 828 FINLAND 830 Phone: +358407796297 831 Email: zach@sensinode.com 833 Srdjan Krco 834 Ericsson 836 Phone: 837 Email: srdjan.krco@ericsson.com