idnits 2.17.1 draft-vial-core-mirror-server-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 (April 10, 2013) is 4033 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 (-18) exists of draft-ietf-core-coap-14 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-08 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-04) exists of draft-shelby-core-coap-req-02 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE M. Vial 3 Internet-Draft Schneider-Electric 4 Intended status: Standards Track April 10, 2013 5 Expires: October 12, 2013 7 CoRE Mirror Server 8 draft-vial-core-mirror-server-01 10 Abstract 12 The Constrained RESTful Environments (CoRE) working group aims at 13 realizing the REpresentational State Transfer (REST) architecture in 14 a suitable form for the most constrained nodes. Thanks to the 15 Constrained Application Protocol (CoAP), REST is now applicable to 16 constrained networks. However the most energy-constrained devices 17 may enter sleep mode and disconnect their network link during several 18 minutes to save energy, hence preventing them from acting as 19 traditional web servers. This document describes how a sleeping 20 device can store resource representations in an entity called Mirror 21 Server and participate in a constrained RESTful environment. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on October 12, 2013. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.2. Uses cases . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.3. Assumptions and objectives . . . . . . . . . . . . . . . 3 61 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4 62 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 5 63 4. Mirror Server Function Set . . . . . . . . . . . . . . . . . 6 64 4.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. Registration . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.4. Validation . . . . . . . . . . . . . . . . . . . . . . . 11 68 4.5. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 4.6. SEP Operation . . . . . . . . . . . . . . . . . . . . . . 12 70 4.7. Client Operation . . . . . . . . . . . . . . . . . . . . 15 71 4.8. Modification check . . . . . . . . . . . . . . . . . . . 17 72 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 73 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 75 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 77 9.1. Normative References . . . . . . . . . . . . . . . . . . 19 78 9.2. Informative References . . . . . . . . . . . . . . . . . 20 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 81 1. Introduction 83 1.1. Motivation 85 The Constrained RESTful Environments (CoRE) working group aims at 86 realizing the REST architecture in a suitable form for the most 87 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 88 ROM, energy harvesting) and networks (e.g. 6LoWPAN). The CoRE 89 charter says that the CoAP protocol [I-D.ietf-core-coap] will support 90 various form of "caching" to support sleeping devices. And the CoAP 91 requirement REQ3 in [I-D.shelby-core-coap-req] clearly states that 92 support of sleeping devices is required: 94 The ability to deal with sleeping nodes. Devices may be powered 95 off at any point in time but periodically "wake up" for brief 96 periods of time. 98 As pointed out by [I-D.arkko-core-sleepy-sensors], the server model 99 is not appropriate for the most energy-constrained devices. CoAP 100 also supports the Publish/Subscribe pattern through CoAP observe 101 [I-D.ietf-core-observe]. Notifications with CoAP observe prove to be 102 efficient however as it is currently specified, it still requires the 103 server model to create and maintain the observation relationship. 104 Although CoAP observe may be enhanced to support subscriptions 105 initiated by the observed server, this method is not currently 106 specified. Also in general, a SEP would support only a limited 107 number of observers at a time. The client model is a viable approach 108 but the interactions and interfaces between endpoints are currently 109 undefined. In conclusion, the current working group documents do not 110 propose a complete solution for sleeping devices that are not always 111 reachable. 113 1.2. Uses cases 115 With the emergence of the Internet of Things we expect a major 116 breaktrough in the number of smart objects in our environment. Yet 117 providing these objects with sufficient energy for continued 118 operation and long battery lifetime is still a big challenge. That 119 is the reason why this specification strives to provide a solution to 120 dramatically reduce the power consumption of constrained RESTful 121 sensors. For battery-operated devices the need to improve battery 122 lifetime is persistent either to reduce the size of smart objects and 123 fit new applications, to increase the product lifetime when it is 124 directly coupled to its battery lifetime or to reduce the annoyance, 125 costs and wastes incurred by changing batteries too frequently. 126 There is also a new trend to avoid batteries and create sensors that 127 can harvest energy from their environment. For those devices it is 128 of prime importance to maintain a high ratio between harvested energy 129 and power consumption. This ratio has a direct impact on service 130 availability and the user experience especially because the 131 harvesting efficiency is typically not constant in time (e.g day/ 132 night for a photovoltaic cell). 134 1.3. Assumptions and objectives 136 In this specification we assume that the energy-constrained devices 137 can store a sufficient amount of energy to enable bi-directional 138 communication and to perform periodic tasks like maintaining soft 139 state. However the most constrained devices may not be able to store 140 energy and may have unpredictable availability due to sporadic energy 141 production (e.g. self-powered push button). This specification may 142 be applicable to these devices as long as they have enough energy to 143 perform the initial registration. This may require an additional 144 source of power during the commissioning phase. 146 Throughout this document we will only consider sleeping devices that 147 are totally unreachable during long periods of time. In other word, 148 network connectivity is turned off at least several seconds hence 149 generating unacceptable interruptions if the device runs as a server. 150 Some link-layer technologies offer advanced low power modes such as 151 duty-cycle link activity or receiver initiated transmissions hence 152 allowing the devices to sleep while still offering network 153 connectivity with an always-on illusion. Devices for which the 154 available energy is sufficient to afford always-on illusion are out 155 of scope of this specification since the server model is applicable 156 to these endpoints. 158 Efficient support of sleeping devices has implications on many 159 aspects of the IP stack: Media Access Control (MAC), neighbor 160 discovery, routing, REST intermediaries... This specification does 161 not aim to find a solution for all of those. The objective is to 162 provide an interaction model at the application level where data 163 exchanges are always initiated by the sleeping endpoint. This way 164 the application can finely control when the network link needs to be 165 on. In no way the mechanisms defined here precludes usage of a low 166 power mode at link-layer. 168 This specification does not pretend to provide full REST support to 169 sleeping devices. These devices will be provided with the minimum 170 set of REST features to publish resources. Particular attention is 171 paid to facilitate configuration and to associate meta-data to 172 resources from sleeping devices. 174 2. Requirements Language 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 178 document are to be interpreted as described in RFC 2119 [RFC2119]. 180 This specification requires readers to be familiar with all the terms 181 and concepts that are discussed in [RFC5988], 182 [I-D.shelby-core-resource-directory] and 183 [I-D.shelby-core-interfaces]. Readers should also be familiar with 184 the terms and concepts discussed in [I-D.ietf-core-coap] and 185 [I-D.ietf-core-link-format]. This specification makes use of the 186 following additional terminology: 188 Sleeping device: A smart object that can enter a long period of time 189 with its network link in disconnected state in order to save 190 energy. 192 Sleeping endpoint (SEP): A sleeping endpoint is an IP sleeping 193 device which can participate in a constrained RESTful environment 194 as a client-only endpoint. 196 Mirror Server (MS): A server endpoint that implements the Mirror 197 Server Function Set. 199 3. Architecture 201 The Mirror Server architecture is shown in Figure 1. A Mirror Server 202 (MS) is a web server implementing a special Function Set that allows 203 a sleeping endpoint (SEP) to create resources in the MS resource 204 tree. For energy efficiency a SEP is a client-only CoAP endpoint and 205 hence is not able to serve content by itself. The MS implements REST 206 interfaces allowing a SEP to maintain a set of mirrored resources 207 that will be served in turn by the MS. So a Mirror Server acts as a 208 mailbox between the sleeping endpoint and the client. A CoAP client 209 discovers resources owned by the SEP but hosted on the MS using 210 typical mechanisms such as "/.well-known/core" 211 [I-D.ietf-core-link-format] or Resource Directory 212 [I-D.shelby-core-resource-directory]. 214 A SEP must register and maintain a mirror entry on the MS, which is 215 soft state and need to be periodically refreshed. A MS provides 216 interfaces to register, update and remove a mirror entry and an 217 associated set of mirrored resources. Furthermore, a MS provides 218 interfaces to read and update the mirrored resources from both the 219 SEP and client sides. Finally, a mechanism to discover a MS using 220 the CoRE Link Format is defined. 222 Registration Discovery 223 | | 224 | | 225 +-----+ | +------+ | +--------+ 226 | | --- push --> | | --- pull --> | | 227 | SEP | | | MS | | | Client | 228 | | <-- pull --- | | <-- push --- | | 229 +-----+ | +------+ | +--------+ 230 | | 231 | | 233 Figure 1: Mirror Server architecture 235 The Mirror Server functionality can be distributed over multiple 236 server endpoints in the network or centralized on a single server 237 endpoint. A shorter round-trip time gives better energy efficiency 238 for request/response exchanges, so it is important to choose a path 239 between the Mirror Server and the sleeping endpoint with minimum 240 latency. Moreover a sleeping endpoint with a Mirror Server in its 241 direct neighborhood may even avoid having to configure global IP 242 connectivity. However in a wireless network relying on local 243 connectivity may result in fragility due to device mobility or radio 244 fluctuations. This could lead a sleeping endpoint to frequently try 245 to move from one Mirror Server to another. Consequently, clients 246 would need to restart resource discovery frequenlty. In that regard, 247 a centralized Mirror Server gives more stability. A centralized 248 Mirror Server also concentrates network traffic on a central point 249 and may cause network congestion in a mesh network. However data 250 flow of a sleeping endpoint is expected to be low hence mitigating 251 the risk of network congestion. 253 A sleeping endpoint MAY register with more than one Mirror Server but 254 in that case the resources of a sleeping endpoint appear duplicated 255 during resource discovery. Section 4.1 describes how to detect 256 duplicate resources. 258 4. Mirror Server Function Set 260 The interface is mostly identical to that of the Resource Directory 261 Function Set defined in [I-D.shelby-core-resource-directory] so this 262 specification only points out the differences. Contrary to the 263 Resource Directory there is no lookup Function Set in a Mirror 264 Server. Indeed, from a client point of view, the mirrored resources 265 look like any other resources hosted the MS endpoint. So resource 266 discovery of mirrored resources is directly available through 267 "/.well-known/core" instead of a separate Function Set. 269 The examples presented in this section make use of a smart 270 temperature sensor the resources of which are defined below using 271 Link Format. Three resources are dedicated to the Device Description 272 (manufacturer, model, name) and one contains the current temperature 273 in degree Celsius. 275 ;rt="ipso.dev.mfg";if="core.rp", 276 ;rt="ipso.dev.mdl";if="core.rp", 277 ;rt="ipso.dev.n";if="core.p", 278 ;rt="ucum.Cel";if="core.s";obs 280 4.1. Discovery 282 The interaction between a SEP and a MS is based on the same discovery 283 interface as the Resource Directory except that the Resource Type in 284 the URI template is replaced with "core.ms". 286 The following example shows a sleeping endpoint discovering a MS 287 using this interface, thus learning that the base MS resource is at / 288 ms. 290 SEP MS 291 | | 292 | ----- GET /.well-known/core?rt=core.ms ------> | 293 | | 294 | | 295 | <---- 2.05 Content "; rt="core.ms" ------ | 296 | | 298 Req: GET coap://[ff02::1]/.well-known/core?rt=core.ms 299 Res: 2.05 Content 300 ;rt="core.ms" 302 Resource discovery between a client and a MS or a client and a RD 303 needs special care to take into account the fact that resources from 304 a sleeping endpoint might appear duplicated. Clients SHOULD employ 305 2-step resource discovery by looking up sleeping endpoints AND 306 resource types to detect duplicate resources. Clients MAY use 307 single-step resource discovery only if the SEP can register with no 308 more than one Mirror Server. A client can use the "ep" link 309 attribute as a filter on the "/.well-known/core" resource to retrieve 310 a list of endpoints and detect duplicate sleeping endpoints 311 registered on multiple MSs. A client can use the "ep" type of lookup 312 to do the same on a RD. The result of endpoint discovery is then 313 used to filter out duplicate resources returned from simple resource 314 discovery. 316 The following example shows a client discovering the sleeping 317 endpoints and learning that the SEP 0224e8fffe925dcf is registered on 318 two Mirror Servers. 320 Client MS1 MS2 321 | | | 322 | ----- GET /.well-known/core?ep=* ------->|----->| 323 | | | 324 | | | 325 | <---- 2.05 Content "..." --------| | 326 | | | 327 | <---- 2.05 Content "..." --------|------| 329 Req: GET coap://[ff02::1]/.well-known/core?ep=* 330 Res: 2.05 Content 331 ;ep="0224e8fffe925dcf" 332 Res: 2.05 Content 333 ;ep="02004cfffe4f4f50" 334 ;ep="0224e8fffe925dcf" 336 From the previous exchange and the next resource discovery request, 337 the client can infer that the resources coap://ms1/ms/0/sen/temp and 338 coap://ms2/ms/1/sen/temp actually come from the same sleeping 339 endpoint. 341 Client MS1 MS2 342 | | | 343 | - GET /.well-known/core?rt=ipso:ucum.Cel ->|----->| 344 | | | 345 | | | 346 | <---- 2.05 Content "..." ----------| | 347 | | | 348 | <---- 2.05 Content "..." ----------|------| 350 Req: GET coap://[ff02::1]/.well-known/core?rt=ucum.Cel 351 Res: 2.05 Content 352 ;rt="ucum.Cel" 356 4.2. Registration 358 The registration interface is identical to the registration interface 359 of the Resource Directory Function Set except that the preferred path 360 for the Mirror Server Function Set is "/ms". 362 After discovering the location of a MS Function Set, a sleeping 363 endpoint MAY register its resources that need to be mirrored using 364 the registration interface. This interface accepts a POST from an 365 endpoint containing a description of the resources to be created on 366 the Mirror Server as the message payload in the CoRE Link Format 367 along with query string parameters indicating the endpoint 368 identifier, its domain and the lifetime of the registration. The 369 Link Format description is identical to the "/.well-known/core" 370 resource found on a typical server endpoint meaning that the 371 Interface Description attributes are actually intended for the Mirror 372 Server. A Mirror Server MUST reject a registration if at least one 373 of the Interface Descriptions is not supported. Upon successful 374 registration a MS creates a new resource or updates an existing 375 resource for the mirror entry and returns its location. The 376 resources specified by the SEP during registration are created as 377 sub-resources of the mirror entry on the MS endpoint. The 378 registration interface MUST be implemented to be idempotent, so that 379 registering twice with the same endpoint parameter does not create 380 multiple MS entries. The resource associated to a mirror entry 381 SHOULD implement the Interface Type CoRE Link List defined in 382 [I-D.shelby-core-interfaces]. A GET request on this resource MUST 383 return the list of mirrored resources for the corresponding SEP. 385 After successul registration, a MS SHOULD enable resource discovery 386 for the new mirrored resources by updating its "/.well-known/core" 387 resource. A MS MUST wait for the initial representation of a 388 mirrored resource before it can be visible in resource discovery. 389 The top level resource corresponding to a mirror entry MUST be 390 published in "/.well-known/core" to enable 2-step resource discovery 391 described in Section 4.1. Sub-resources of a mirror entry SHOULD be 392 discoverable either directly in "/.well-known/core" or indirectly 393 through gradual reveal from the mirror entry resource. The Web Link 394 of a mirror entry MUST contain an "ep" attribute with the value of 395 the End-Point parameter received at registration. If present, the 396 End-Point Type parameter SHOULD also be mapped as a "rt" attribute. 398 A Mirror Server MAY be configured to register the SEP's resources in 399 a Resource Directory (RD). A SEP MUST NOT register the mirrored 400 resources in a RD by itself. It is always the responsibility of the 401 Mirror Server. Since each SEP may register resources with different 402 lifetimes, a MS MUST register the resources of a SEP in a separate 403 resource directory entry. A SEP may register with multiple MS hence 404 the RD entries from the different MS for the same SEP would overlap 405 if special care is not taken. Therefore if a SEP is likely to 406 register with more than one MS, a Mirror Server MUST create its own 407 domain to register the resources of a SEP. This precaution ensures 408 that the ep identifier of a SEP is unique for each domain in the RD. 409 The new domain is typically formed by concatenating the MS's endpoint 410 identifier with the domain in use. 412 SEP resources in the MS are kept active for the period indicated by 413 the lifetime parameter. The SEP is responsible for refreshing the 414 entry within this period using either the registration or update 415 interface. Once a mirror entry has expired, the MS deletes all 416 resources associated to that entry and updates its "/.well-known/ 417 core" resource. When the mirrored resources are also registered in a 418 RD, the RD and MS entries are supposed to have the same lifetime. 419 Consequently, when the mirror entry expires, a MS MAY let the RD 420 entry expire too instead of explicitly deleting it. Nevertheless if 421 the MS entry is deleted using the Removal interface then the RD entry 422 MUST be explicitly removed. 424 A Mirror Server could lose or delete the mirror entry associated to a 425 SEP without sending an explicit notification (e.g. after reboot). A 426 SEP SHOULD be able to detect this situation by processing the 427 response code while using the SEP Operation or Update interface. 428 Especially an error code "4.04 Not Found" SHOULD cause the SEP to 429 register again. A SEP MAY also register with multiple MSs to 430 alleviate the risk of interruption of service. 432 Implementation note: It is not recommended to reuse the value of the 433 ep parameter in the URI of the Mirror Server entry. This parameter 434 may be a relatively long identifier to guarantee global uniqueness 435 (e.g. EUI64) and would generate inefficient URIs on the Mirror 436 Server where only a local handler is necessary. 438 The following example shows a sleeping endpoint registering with a 439 MS. 441 SEP MS 442 | | 443 | --- POST /ms " | 444 | | 445 | | 446 | <-- 2.01 Created Location: /ms/0 ------------- | 447 | | 449 Req: POST coap://ms.example.org/ms?ep=0224e8fffe925dcf&rt=sensor 450 Etag: 0x3f 451 Payload: 452 ;rt="ipso.dev.mfg";if="core.rp", 453 ;rt="ipso.dev.mdl";if="core.rp", 454 ;rt="ipso.dev.n";if="core.p", 455 ;rt="ucum.Cel";if="core.s";obs 457 Res: 2.01 Created 458 Location: /ms/0 460 The mirror entry resource below has been created on the MS. 462 Req: GET coap://ms.example.org/.well-known/core 463 Res: 2.05 Content 464 ;rt="core.ms", 465 ;ep="0224e8fffe925dcf";rt="sensor";if="core.ll" 467 The SEP sets the initial value for its mirrored resources and the 468 following resources are now created. 470 Req: GET coap://ms.example.org/ms/0 471 Res: 2.05 Content 472 Payload: 474 ;rt="ipso.dev.mfg";if="core.rp", 475 ;rt="ipso.dev.mdl";if="core.rp", 476 ;rt="ipso.dev.n";if="core.p", 477 ;rt="ucum.Cel";if="core.s";obs 479 Then the MS registers the mirrored resources in the RD. 481 MS RD 482 | | 483 | --- POST /rd " | 484 | | 485 | | 486 | <-- 2.01 Created Location: /rd/6534 ---------- | 487 | | 489 Req: POST coap://rd.example.org/rd?ep=0224e8fffe925dcf& 490 rt=sensor&d=ms1.example.org 491 Etag: 0x6a 492 Payload: 493 ;rt="ipso.dev.mfg";if="core.rp", 494 ;rt="ipso.dev.mdl";if="core.rp", 495 ;rt="ipso.dev.n";if="core.p", 496 ;rt="ucum.Cel";if="core.s";obs 498 Res: 2.01 Created 499 Location: /rd/6534 501 4.3. Update 503 The update interface is not necessary on a Mirror Server. A SEP can 504 use the registration interface to modify a mirror entry. The 505 Lifetime query parameter of the SEP operation interface defined in 506 Section 4.6 allows a SEP to extend the lifetime of its mirror entry. 508 4.4. Validation 510 The validation interface is not supported on a Mirror Server since 511 the sleeping endpoint is unreachable. 513 4.5. Removal 515 The removal interface is identical. 517 Upon successful removal, "/.well-known/core" and the Resource 518 Directory (if applicable) MUST be updated accordingly. All resources 519 associated to the mirror entry are deleted. 521 4.6. SEP Operation 523 The SEP Operation interface is not defined for a Resource Directory 524 and is specific to the Mirror Server Function Set. 526 Once the resources have been created on the MS, the SEP can access 527 its mirrored resources at its own pace. The SEP MAY update its 528 mirrored resources on the MS using PUT requests. The SEP MAY 529 retrieve the current representation of any of its mirrored resources 530 using GET requests. The SEP can reactivate its mirror entry by 531 including a Lifetime (lt) parameter in the query string. While 532 updating dynamic resources, a SEP SHOULD include a Lifetime parameter 533 with the smallest value that matches its technical constraints. It 534 allows a client to fastly detect a stale mirror entry. A SEP MAY 535 omit processing some responses for non confirmable requests in order 536 to avoid spending energy waiting for a response when it is frequently 537 accessing a mirrored resource. Nevertheless a SEP SHOULD 538 periodically check the responses to ensure that its mirror entry is 539 still active on the MS. 541 Other specifications may override or extend this interface to provide 542 more advanced features, support other REST methods and queuing 543 patterns. This is however out of scope of this specification, which 544 provides only a basic behavior. 546 In addition to the Modification check interface defined in 547 Section 4.8, the SEP Operation interface support a lightweight 548 mechanism to detect if a mirrored resource has been changed by a 549 client. When a SEP sends a PUT request to update its resources, the 550 response may contain a link-format payload. The payload does not 551 directly relate to the target resource of the PUT request. Instead, 552 it is a list of web links to resources that have been modified by 553 clients since either the last PUT request or the last call to the 554 modification check interface. 556 The basic SEP operation interface is specified as follows: 558 Interaction: SEP -> MS 560 Method: GET, PUT 562 URI Template: /{+location}{+resource}{?lt} 564 URI Template Variables: 566 location := This is the Location path returned by the MS as a 567 result of a successful registration. 569 resource := This is the relative path to a mirrored resource 570 managed by the registered SEP. 572 lt := Lifetime (optional). The number of seconds by which the 573 lifetime of the whole mirror entry is extended. Range of 574 1-4294967295. If no lifetime is included, the current 575 remaining lifetime stays unchanged. 577 Request Content-Type: Defined at registration 579 Response Content-Type: Defined at registration for GET method. 580 application/link-format for PUT method if at least one of the 581 mutable resources has been updated since the last PUT request. 583 Etag: The Etag option MAY be included to allow clients to validate a 584 resource on multiple Mirror Servers. 586 Success: 2.01 "Created", the request MUST include the initial 587 representation of the mirrored resource. 589 Success: 2.04 "Changed", the request MUST include the new 590 representation of the mirrored resource. 592 Success: 2.05 "Content", the response MUST include the current 593 representation of the mirrored resource. 595 Failure: 4.00 "Bad Request". Malformed request. 597 Failure: 5.03 "Service Unavailable". Service could not perform the 598 operation. 600 The following example describes how a sleeping endpoint can 601 initialize the resource containing its manufacturer name just after 602 registration. 604 SEP MS 605 | | 606 | --- PUT /ms/0/dev/mfg "acme" ---------------> | 607 | | 608 | | 609 | <-- 2.01 Created ----------------------------- | 610 | | 612 Req: PUT /ms/0/dev/mfg 613 Payload: acme 614 Res: 2.01 Created 615 The example below shows how a SEP can indicate that it is supposed to 616 send a temperature value at least every hour to keep its mirror entry 617 active. 619 SEP MS 620 | | 621 | --- PUT /ms/0/sen/temp?lt=3600 "22" --------> | 622 | | 623 | | 624 | <-- 2.04 Changed ----------------------------- | 625 | | 627 Req: PUT /ms/0/sen/temp?lt=3600 628 Payload: 22 629 Res: 2.04 Changed 631 The following example shows a commissioning tool changing the name of 632 a sleeping device through a Mirror Server. The SEP detects this 633 change right after mirroring its current temperature. 635 SEP MS Client 636 | | | 637 | | <-- PUT /ms/0/dev/n --- | 638 | | | 639 | | -- 2.04 Changed ------> | 640 | | | 641 | - PUT /ms/0/sen/temp ---> | | 642 | | | 643 | <- 2.04 Changed --------- | | 644 | | | 645 | - GET /ms/0/dev/n ------> | | 646 | | | 647 | <- 2.05 Content --------- | | 648 | | | 650 Req: PUT /ms/0/dev/n 651 Payload: "sensor-1" 652 Res: 2.04 Changed 654 Req: PUT /ms/0/sen/temp 655 Payload: "24" 656 Res: 2.04 Changed, Content-Type: application/link-format 657 Payload: "" 659 Req: GET /ms/0/dev/n 660 Res: 2.05 Content 661 Payload: "sensor-1" 663 4.7. Client Operation 665 The Client Operation interface is not defined for a Resource 666 Directory and is specific to the Mirror Server Function Set. 668 While the SEP operation interface describes only the interaction 669 between the SEP and the MS on mirrored resources, the interface 670 between a client and the MS for mirrored resources is actually 671 defined by the Link Format payload at registration. This 672 specification does not define the list of Interface Description 673 attribute values that a Mirror Server must support. This is left to 674 a companion specification such as a CoRE profile specification. A 675 Mirror Server MAY support complex interfaces that require special 676 logic and interactions between multiple mirrored resources. The CoRE 677 Batch interface defined in [I-D.shelby-core-interfaces] is an example 678 of complex interface that defines relations between a parent resource 679 and sub-resources using SenML [I-D.jennings-senml]. 681 A SEP may register resources with the "obs" attribute. In that case 682 a MS using the CoAP protocol [I-D.ietf-core-coap] SHOULD accept to 683 establish a CoAP observation relationship between the observable 684 mirrored resource and a client as defined in [I-D.ietf-core-observe]. 686 A SEP may stop updating its mirrored resources without explictly 687 removing its mirror entry (e.g. transition to another MS after 688 network unreachability detection). A client can detect this 689 situation when the corresponding mirror entry has expired. Upon 690 receipt of a response with error code 4.04 "Not Found", a client 691 SHOULD restart resource discovery to determine if the resources are 692 now mirrored on another MS. 694 The Client operation interface is specified as follows: 696 Interaction: Client -> MS 698 Method: Defined at registration 700 URI Template: /{+location}{+resource} 702 URI Template Variables: 704 location := This is the Location path returned by the MS as a 705 result of a successful registration. 707 resource := This is the relative path to a mirrored resource 708 managed by a SEP. 710 Content-Type: Defined at registration 712 In the example below a client observes the changes of temperature 713 through the Mirror Server. 715 SEP MS Client 716 | | | 717 | | <- GET /ms/0/sen/temp - | 718 | | (observe) | 719 | | | 720 | | -- 2.05 Content "22" -> | 721 | | | 722 | - PUT /ms/0/sen/temp "23" -> | | 723 | | | 724 | <- 2.04 Changed ------------ | | 725 | | | 726 | | -- 2.05 Content "23" -> | 728 4.8. Modification check 730 This interface is not defined for a Resource Directory and is 731 specific to the Mirror Server Function Set. 733 A sleeping endpoint may register resources supporting POST or PUT 734 methods and therefore that could be modified by clients. In that 735 case the SEP needs to poll these resources to detect updates. 736 Polling each modifiable resource is inefficient when they are 737 numerous. The modification check interface allows a SEP to retrieve 738 a list of resources that have been modified. The SEP can then send 739 GET requests on each resource of the list to get the updated 740 representation. A POST request on the check interface automatically 741 clears the list of modified resources. 743 The check interface is specified as follows: 745 Interaction: SEP -> MS 747 Method: POST 749 URI Template: /{+location}?chk 751 URI Template Variables: 753 location := This is the Location path returned by the MS as a 754 result of a successful registration. 756 Request Content-Type: None 758 Response Content-Type: application/link-format 760 Success: 2.04 "Changed", the response MUST include a list of web 761 links to resources that have been modified by clients. 763 Failure: 4.00 "Bad Request". Malformed request. 765 Failure: 5.03 "Service Unavailable". Service could not perform the 766 operation. 768 The following example shows a commissioning tool changing the name of 769 a sleeping device through a Mirror Server. A commissioning button on 770 the SEP triggers the reading of the new configuration. 772 SEP MS Client 773 | | | 774 | | <-- PUT /ms/0/dev/n --- | 775 | | | 776 | | -- 2.04 Changed ------> | 777 | | | 778 | [press button on SEP] | | 779 | | | 780 | - POST /ms/0?chk -------> | | 781 | | | 782 | <- 2.04 Changed --------- | | 783 | | | 784 | - GET /ms/0/dev/n ------> | | 785 | | | 786 | <- 2.05 Content --------- | | 787 | | | 789 Req: PUT /ms/0/dev/n 790 Payload: "sensor-1" 791 Res: 2.04 Changed 793 Req: POST /ms/0?chk 794 Res: 2.04 Changed 795 Payload: "" 797 Req: GET /ms/0/dev/n 798 Res: 2.05 Content 799 Payload: "sensor-1" 801 5. Acknowledgements 803 Thanks to Zach Shelby who is the author of the Resource Directory 804 interface. Thanks to Nicolas Riou, Jari Arkko, Esko Dijk and Carsten 805 Bormann who have provided useful comments. 807 6. IANA Considerations 809 "core.ms" resource type needs to be registered. 811 The "ep" attribute needs to be registered. 813 7. Security Considerations 815 This document needs the same security considerations as described in 816 Section 7 of [RFC5988] and Section 6 of [I-D.ietf-core-link-format]. 818 The Mirror Server architecture defines the SEP and Client roles in 819 the Mirror Function Set interfaces. Since the roles are based on the 820 requester identity, a MS SHOULD perform appropriate authentication in 821 order to prevent a malicious client endpoint from impersonating the 822 SEP or an authorized client. Otherwise the malicious client could 823 gain access to interfaces allowing corruption or deletion of a 824 mirrored resource. 826 A malicious client could start a denial of service attack by trying 827 to mirror a large resource on a MS. Memory exhaustion would prevent 828 other sleeping endpoints from mirroring their resources. A MS SHOULD 829 use quotas to limit the size and the number of mirrored resources per 830 SEP. 832 A Mirror Server is actually an intermediary running at application 833 level. As a consequence the Mirror Server architecture can only 834 provide implicit end-to-end security that relies on a trusted network 835 if security is not available at application layer. When explicit 836 end-to-end security is required between a SEP and a Client, data 837 object security SHOULD be employed. 839 8. Changelog 841 Changes from -00 to -01 843 o Lightweight modification check mechanism. 845 9. References 847 9.1. Normative References 849 [I-D.ietf-core-coap] 850 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 851 Application Protocol (CoAP)", draft-ietf-core-coap-14 852 (work in progress), March 2013. 854 [I-D.ietf-core-link-format] 855 Shelby, Z., "CoRE Link Format", draft-ietf-core-link- 856 format-14 (work in progress), June 2012. 858 [I-D.ietf-core-observe] 859 Hartke, K., "Observing Resources in CoAP", draft-ietf- 860 core-observe-08 (work in progress), February 2013. 862 [I-D.shelby-core-interfaces] 863 Shelby, Z. and M. Vial, "CoRE Interfaces", draft-shelby- 864 core-interfaces-05 (work in progress), March 2013. 866 [I-D.shelby-core-resource-directory] 867 Shelby, Z., Krco, S., and C. Bormann, "CoRE Resource 868 Directory", draft-shelby-core-resource-directory-05 (work 869 in progress), February 2013. 871 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 872 Requirement Levels", BCP 14, RFC 2119, March 1997. 874 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 876 9.2. Informative References 878 [I-D.arkko-core-sleepy-sensors] 879 Arkko, J., Rissanen, H., Loreto, S., Turanyi, Z., and O. 880 Novo, "Implementing Tiny COAP Sensors", draft-arkko-core- 881 sleepy-sensors-01 (work in progress), July 2011. 883 [I-D.jennings-senml] 884 Jennings, C., Shelby, Z., and J. Arkko, "Media Types for 885 Sensor Markup Language (SENML)", draft-jennings-senml-10 886 (work in progress), October 2012. 888 [I-D.shelby-core-coap-req] 889 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 890 Kelsey, "CoAP Requirements and Features", draft-shelby- 891 core-coap-req-02 (work in progress), October 2010. 893 Author's Address 895 Matthieu Vial 896 Schneider-Electric 897 Grenoble 898 FRANCE 900 Phone: +33 (0)47657 6522 901 Email: matthieu.vial@schneider-electric.com