idnits 2.17.1 draft-vial-core-mirror-proxy-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 (July 13, 2012) is 4302 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-10 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-05 == Outdated reference: A later version (-05) exists of draft-shelby-core-interfaces-03 == Outdated reference: A later version (-05) exists of draft-shelby-core-resource-directory-03 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-10) exists of draft-jennings-senml-08 == Outdated reference: A later version (-04) exists of draft-shelby-core-coap-req-02 Summary: 1 error (**), 0 flaws (~~), 7 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 July 13, 2012 5 Expires: January 14, 2013 7 CoRE Mirror Server 8 draft-vial-core-mirror-proxy-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 January 14, 2013. 40 Copyright Notice 42 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.2. Uses cases . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.3. Assumptions and objectives . . . . . . . . . . . . . . . . 4 61 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 5 62 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 4. Mirror Server Function Set . . . . . . . . . . . . . . . . . . 6 64 4.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.4. Validation . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4.5. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 4.6. SEP Operation . . . . . . . . . . . . . . . . . . . . . . 12 70 4.7. Client Operation . . . . . . . . . . . . . . . . . . . . . 14 71 4.8. Modification check . . . . . . . . . . . . . . . . . . . . 15 72 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 73 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 76 8.1. Normative References . . . . . . . . . . . . . . . . . . . 18 77 8.2. Informative References . . . . . . . . . . . . . . . . . . 19 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 1. Introduction 82 1.1. Motivation 84 The Constrained RESTful Environments (CoRE) working group aims at 85 realizing the REST architecture in a suitable form for the most 86 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 87 ROM, energy harvesting) and networks (e.g. 6LoWPAN). The CoRE 88 charter says that the CoAP protocol [I-D.ietf-core-coap] will support 89 various form of "caching" to support sleeping devices. And the CoAP 90 requirement REQ3 in [I-D.shelby-core-coap-req] clearly states that 91 support of sleeping devices is required: 93 The ability to deal with sleeping nodes. Devices may be powered 94 off at any point in time but periodically "wake up" for brief 95 periods of time. 97 As pointed out by [I-D.arkko-core-sleepy-sensors], the server model 98 is not appropriate for the most energy-constrained devices. CoAP 99 also supports the Publish/Subscribe pattern through CoAP observe 100 [I-D.ietf-core-observe]. Notifications with CoAP observe prove to be 101 efficient however as it is currently specified, it still requires the 102 server model to create and maintain the observation relationship. 103 Although CoAP observe may be enhanced to support subscriptions 104 initiated by the observed server, this method is not currently 105 specified. Also in general, a SEP would support only a limited 106 number of observers at a time. The client model is a viable approach 107 but the interactions and interfaces between endpoints are currently 108 undefined. In conclusion, the current working group documents do not 109 propose a complete solution for sleeping devices that are not always 110 reachable. 112 1.2. Uses cases 114 With the emergence of the Internet of Things we expect a major 115 breaktrough in the number of smart objects in our environment. Yet 116 providing these objects with sufficient energy for continued 117 operation and long battery lifetime is still a big challenge. That 118 is the reason why this specification strives to provide a solution to 119 dramatically reduce the power consumption of constrained RESTful 120 sensors. For battery-operated devices the need to improve battery 121 lifetime is persistent either to reduce the size of smart objects and 122 fit new applications, to increase the product lifetime when it is 123 directly coupled to its battery lifetime or to reduce the annoyance, 124 costs and wastes incurred by changing batteries too frequently. 125 There is also a new trend to avoid batteries and create sensors that 126 can harvest energy from their environment. For those devices it is 127 of prime importance to maintain a high ratio between harvested energy 128 and power consumption. This ratio has a direct impact on service 129 availability and the user experience especially because the 130 harvesting efficiency is typically not constant in time (e.g day/ 131 night for a photovoltaic cell). 133 1.3. Assumptions and objectives 135 In this specification we assume that the energy-constrained devices 136 can store a sufficient amount of energy to enable bi-directional 137 communication and to perform periodic tasks like maintaining soft 138 state. However the most constrained devices may not be able to store 139 energy and may have unpredictable availability due to sporadic energy 140 production (e.g. self-powered push button). This specification may 141 be applicable to these devices as long as they have enough energy to 142 perform the initial registration. This may require an additional 143 source of power during the commissioning phase. 145 Throughout this document we will only consider sleeping devices that 146 are totally unreachable during long periods of time. In other word, 147 network connectivity is turned off at least several seconds hence 148 generating unacceptable interruptions if the device runs as a server. 149 Some link-layer technologies offer advanced low power modes such as 150 duty-cycle link activity or receiver initiated transmissions hence 151 allowing the devices to sleep while still offering network 152 connectivity with an always-on illusion. Devices for which the 153 available energy is sufficient to afford always-on illusion are out 154 of scope of this specification since the server model is applicable 155 to these endpoints. 157 Efficient support of sleeping devices has implications on many 158 aspects of the IP stack: Media Access Control (MAC), neighbor 159 discovery, routing, REST intermediaries... This specification does 160 not aim to find a solution for all of those. The objective is to 161 provide an interaction model at the application level where data 162 exchanges are always initiated by the sleeping endpoint. This way 163 the application can finely control when the network link needs to be 164 on. In no way the mechanisms defined here precludes usage of a low 165 power mode at link-layer. 167 This specification does not pretend to provide full REST support to 168 sleeping devices. These devices will be provided with the minimum 169 set of REST features to publish resources. Particular attention is 170 paid to facilitate configuration and to associate meta-data to 171 resources from sleeping devices. 173 2. Requirements Language 175 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 176 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 177 document are to be interpreted as described in RFC 2119 [RFC2119]. 179 This specification requires readers to be familiar with all the terms 180 and concepts that are discussed in [RFC5988], 181 [I-D.shelby-core-resource-directory] and 182 [I-D.shelby-core-interfaces]. Readers should also be familiar with 183 the terms and concepts discussed in [I-D.ietf-core-coap] and 184 [I-D.ietf-core-link-format]. This specification makes use of the 185 following additional terminology: 187 Sleeping device: A smart object that can enter a long period of time 188 with its network link in disconnected state in order to save 189 energy. 191 Sleeping endpoint (SEP): A sleeping endpoint is an IP sleeping 192 device which can participate in a constrained RESTful environment 193 as a client-only endpoint. 195 Mirror Server (MS): A server endpoint that implements the Mirror 196 Server Function Set. 198 3. Architecture 200 The Mirror Server architecture is shown in Figure 1. A Mirror Server 201 (MS) is a web server implementing a special Function Set that allows 202 a sleeping endpoint (SEP) to create resources in the MS resource 203 tree. For energy efficiency a SEP is a client-only CoAP endpoint and 204 hence is not able to serve content by itself. The MS implements REST 205 interfaces allowing a SEP to maintain a set of mirrored resources 206 that will be served in turn by the MS. So a Mirror Server acts as a 207 mailbox between the sleeping endpoint and the client. A CoAP client 208 discovers resources owned by the SEP but hosted on the MS using 209 typical mechanisms such as "/.well-known/core" 210 [I-D.ietf-core-link-format] or Resource Directory 211 [I-D.shelby-core-resource-directory]. 213 A SEP must register and maintain a mirror entry on the MS, which is 214 soft state and need to be periodically refreshed. A MS provides 215 interfaces to register, update and remove a mirror entry and an 216 associated set of mirrored resources. Furthermore, a MS provides 217 interfaces to read and update the mirrored resources from both the 218 SEP and client sides. Finally, a mechanism to discover a MS using 219 the CoRE Link Format is defined. 221 Registration Discovery 222 | | 223 | | 224 +-----+ | +------+ | +--------+ 225 | | --- push --> | | --- pull --> | | 226 | SEP | | | MS | | | Client | 227 | | <-- pull --- | | <-- push --- | | 228 +-----+ | +------+ | +--------+ 229 | | 230 | | 232 Figure 1: Mirror Server architecture 234 The Mirror Server functionality can be distributed over multiple 235 server endpoints in the network or centralized on a single server 236 endpoint. A shorter round-trip time gives better energy efficiency 237 for request/response exchanges, so it is important to choose a path 238 between the Mirror Server and the sleeping endpoint with minimum 239 latency. Moreover a sleeping endpoint with a Mirror Server in its 240 direct neighborhood may even avoid having to configure global IP 241 connectivity. However in a wireless network relying on local 242 connectivity may result in fragility due to device mobility or radio 243 fluctuations. This could lead a sleeping endpoint to frequently try 244 to move from one Mirror Server to another. Consequently, clients 245 would need to restart resource discovery frequenlty. In that regard, 246 a centralized Mirror Server gives more stability. A centralized 247 Mirror Server also concentrates network traffic on a central point 248 and may cause network congestion in a mesh network. However data 249 flow of a sleeping endpoint is expected to be low hence mitigating 250 the risk of network congestion. 252 A sleeping endpoint MAY register with more than one Mirror Server but 253 in that case the resources of a sleeping endpoint appear duplicated 254 during resource discovery. Section 4.1 describes how to detect 255 duplicate resources. 257 4. Mirror Server Function Set 259 The interface is mostly identical to that of the Resource Directory 260 Function Set defined in [I-D.shelby-core-resource-directory] so this 261 specification only points out the differences. Contrary to the 262 Resource Directory there is no lookup Function Set in a Mirror 263 Server. Indeed, from a client point of view, the mirrored resources 264 look like any other resources hosted the MS endpoint. So resource 265 discovery of mirrored resources is directly available through 266 "/.well-known/core" instead of a separate Function Set. 268 The examples presented in this section make use of a smart 269 temperature sensor the resources of which are defined below using 270 Link Format. Three resources are dedicated to the Device Description 271 (manufacturer, model, name) and one contains the current temperature 272 in degree Celsius. 274 ;rt="ipso.dev.mfg";if="core.rp", 275 ;rt="ipso.dev.mdl";if="core.rp", 276 ;rt="ipso.dev.n";if="core.p", 277 ;rt="ucum.Cel";if="core.s";obs 279 4.1. Discovery 281 The interaction between a SEP and a MS is based on the same discovery 282 interface as the Resource Directory except that the Resource Type in 283 the URI template is replaced with "core.ms". 285 The following example shows a sleeping endpoint discovering a MS 286 using this interface, thus learning that the base MS resource is at 287 /ms. 289 SEP MS 290 | | 291 | ----- GET /.well-known/core?rt=core.ms ------> | 292 | | 293 | | 294 | <---- 2.05 Content "; rt="core.ms" ------ | 295 | | 297 Req: GET coap://[ff02::1]/.well-known/core?rt=core.ms 298 Res: 2.05 Content 299 ;rt="core.ms" 301 Resource discovery between a client and a MS or a client and a RD 302 needs special care to take into account the fact that resources from 303 a sleeping endpoint might appear duplicated. Clients SHOULD employ 304 2-step resource discovery by looking up sleeping endpoints AND 305 resource types to detect duplicate resources. Clients MAY use 306 single-step resource discovery only if the SEP can register with no 307 more than one Mirror Server. A client can use the "ep" link 308 attribute as a filter on the "/.well-known/core" resource to retrieve 309 a list of endpoints and detect duplicate sleeping endpoints 310 registered on multiple MSs. A client can use the "ep" type of lookup 311 to do the same on a RD. The result of endpoint discovery is then 312 used to filter out duplicate resources returned from simple resource 313 discovery. 315 The following example shows a client discovering the sleeping 316 endpoints and learning that the SEP 0224e8fffe925dcf is registered on 317 two Mirror Servers. 319 Client MS1 MS2 320 | | | 321 | ----- GET /.well-known/core?ep=* ------->|----->| 322 | | | 323 | | | 324 | <---- 2.05 Content "..." --------| | 325 | | | 326 | <---- 2.05 Content "..." --------|------| 328 Req: GET coap://[ff02::1]/.well-known/core?ep=* 329 Res: 2.05 Content 330 ;ep="0224e8fffe925dcf" 331 Res: 2.05 Content 332 ;ep="02004cfffe4f4f50" 333 ;ep="0224e8fffe925dcf" 335 From the previous exchange and the next resource discovery request, 336 the client can infer that the resources coap://ms1/ms/0/sen/temp and 337 coap://ms2/ms/1/sen/temp actually come from the same sleeping 338 endpoint. 340 Client MS1 MS2 341 | | | 342 | - GET /.well-known/core?rt=ipso:ucum.Cel ->|----->| 343 | | | 344 | | | 345 | <---- 2.05 Content "..." ----------| | 346 | | | 347 | <---- 2.05 Content "..." ----------|------| 349 Req: GET coap://[ff02::1]/.well-known/core?rt=ucum.Cel 350 Res: 2.05 Content 351 ;rt="ucum.Cel" 355 4.2. Registration 357 The registration interface is identical to the registration interface 358 of the Resource Directory Function Set except that the preferred path 359 for the Mirror Server Function Set is "/ms". 361 After discovering the location of a MS Function Set, a sleeping 362 endpoint MAY register its resources that need to be mirrored using 363 the registration interface. This interface accepts a POST from an 364 endpoint containing a description of the resources to be created on 365 the Mirror Server as the message payload in the CoRE Link Format 366 along with query string parameters indicating the endpoint 367 identifier, its domain and the lifetime of the registration. The 368 Link Format description is identical to the "/.well-known/core" 369 resource found on a typical server endpoint meaning that the 370 Interface Description attributes are actually intended for the Mirror 371 Server. A Mirror Server MUST reject a registration if at least one 372 of the Interface Descriptions is not supported. Upon successful 373 registration a MS creates a new resource or updates an existing 374 resource for the mirror entry and returns its location. The 375 resources specified by the SEP during registration are created as 376 sub-resources of the mirror entry on the MS endpoint. The 377 registration interface MUST be implemented to be idempotent, so that 378 registering twice with the same endpoint parameter does not create 379 multiple MS entries. The resource associated to a mirror entry 380 SHOULD implement the Interface Type CoRE Link List defined in 381 [I-D.shelby-core-interfaces]. A GET request on this resource MUST 382 return the list of mirrored resources for the corresponding SEP. 384 After successul registration, a MS SHOULD enable resource discovery 385 for the new mirrored resources by updating its "/.well-known/core" 386 resource. A MS MUST wait for the initial representation of a 387 mirrored resource before it can be visible in resource discovery. 388 The top level resource corresponding to a mirror entry MUST be 389 published in "/.well-known/core" to enable 2-step resource discovery 390 described in Section 4.1. Sub-resources of a mirror entry SHOULD be 391 discoverable either directly in "/.well-known/core" or indirectly 392 through gradual reveal from the mirror entry resource. The Web Link 393 of a mirror entry MUST contain an "ep" attribute with the value of 394 the End-Point parameter received at registration. If present, the 395 End-Point Type parameter SHOULD also be mapped as a "rt" attribute. 397 A Mirror Server MAY be configured to register the SEP's resources in 398 a Resource Directory (RD). A SEP MUST NOT register the mirrored 399 resources in a RD by itself. It is always the responsibility of the 400 Mirror Server. Since each SEP may register resources with different 401 lifetimes, a MS MUST register the resources of a SEP in a separate 402 resource directory entry. A SEP may register with multiple MS hence 403 the RD entries from the different MS for the same SEP would overlap 404 if special care is not taken. Therefore if a SEP is likely to 405 register with more than one MS, a Mirror Server MUST create its own 406 domain to register the resources of a SEP. This precaution ensures 407 that the ep identifier of a SEP is unique for each domain in the RD. 408 The new domain is typically formed by concatenating the MS's endpoint 409 identifier with the domain in use. 411 SEP resources in the MS are kept active for the period indicated by 412 the lifetime parameter. The SEP is responsible for refreshing the 413 entry within this period using either the registration or update 414 interface. Once a mirror entry has expired, the MS deletes all 415 resources associated to that entry and updates its "/.well-known/ 416 core" resource. When the mirrored resources are also registered in a 417 RD, the RD and MS entries are supposed to have the same lifetime. 418 Consequently, when the mirror entry expires, a MS MAY let the RD 419 entry expire too instead of explicitly deleting it. Nevertheless if 420 the MS entry is deleted using the Removal interface then the RD entry 421 MUST be explicitly removed. 423 A Mirror Server could lose or delete the mirror entry associated to a 424 SEP without sending an explicit notification (e.g. after reboot). A 425 SEP SHOULD be able to detect this situation by processing the 426 response code while using the SEP Operation or Update interface. 427 Especially an error code "4.04 Not Found" SHOULD cause the SEP to 428 register again. A SEP MAY also register with multiple MSs to 429 alleviate the risk of interruption of service. 431 Implementation note: It is not recommended to reuse the value of the 432 ep parameter in the URI of the Mirror Server entry. This parameter 433 may be a relatively long identifier to guarantee global uniqueness 434 (e.g. EUI64) and would generate inefficient URIs on the Mirror 435 Server where only a local handler is necessary. 437 The following example shows a sleeping endpoint registering with a 438 MS. 440 SEP MS 441 | | 442 | --- POST /ms " | 443 | | 444 | | 445 | <-- 2.01 Created Location: /ms/0 ------------- | 446 | | 448 Req: POST coap://ms.example.org/ms?ep=0224e8fffe925dcf&rt=sensor 449 Etag: 0x3f 450 Payload: 451 ;rt="ipso.dev.mfg";if="core.rp", 452 ;rt="ipso.dev.mdl";if="core.rp", 453 ;rt="ipso.dev.n";if="core.p", 454 ;rt="ucum.Cel";if="core.s";obs 456 Res: 2.01 Created 457 Location: /ms/0 459 The mirror entry resource below has been created on the MS. 461 Req: GET coap://ms.example.org/.well-known/core 462 Res: 2.05 Content 463 ;rt="core.ms", 464 ;ep="0224e8fffe925dcf";rt="sensor";if="core.ll" 466 The SEP sets the initial value for its mirrored resources and the 467 following resources are now created. 469 Req: GET coap://ms.example.org/ms/0 470 Res: 2.05 Content 471 Payload: 472 ;rt="ipso.dev.mfg";if="core.rp", 473 ;rt="ipso.dev.mdl";if="core.rp", 474 ;rt="ipso.dev.n";if="core.p", 475 ;rt="ucum.Cel";if="core.s";obs 477 Then the MS registers the mirrored resources in the RD. 479 MS RD 480 | | 481 | --- POST /rd " | 482 | | 483 | | 484 | <-- 2.01 Created Location: /rd/6534 ---------- | 485 | | 487 Req: POST coap://rd.example.org/rd?ep=0224e8fffe925dcf& 488 rt=sensor&d=ms1.example.org 489 Etag: 0x6a 490 Payload: 491 ;rt="ipso.dev.mfg";if="core.rp", 492 ;rt="ipso.dev.mdl";if="core.rp", 493 ;rt="ipso.dev.n";if="core.p", 494 ;rt="ucum.Cel";if="core.s";obs 496 Res: 2.01 Created 497 Location: /rd/6534 499 4.3. Update 501 The update interface is not necessary on a Mirror Server. A SEP can 502 use the registration interface to modify a mirror entry. The 503 Lifetime query parameter of the SEP operation interface defined in 504 Section 4.6 allows a SEP to extend the lifetime of its mirror entry. 506 4.4. Validation 508 The validation interface is not supported on a Mirror Server since 509 the sleeping endpoint is unreachable. 511 4.5. Removal 513 The removal interface is identical. 515 Upon successful removal, "/.well-known/core" and the Resource 516 Directory (if applicable) MUST be updated accordingly. All resources 517 associated to the mirror entry are deleted. 519 4.6. SEP Operation 521 The SEP Operation interface is not defined for a Resource Directory 522 and is specific to the Mirror Server Function Set. 524 Once the resources have been created on the MS, the SEP can access 525 its mirrored resources at its own pace. The SEP MAY update its 526 mirrored resources on the MS using PUT requests. The SEP MAY 527 retrieve the current representation of any of its mirrored resources 528 using GET requests. The SEP can reactivate its mirror entry by 529 including a Lifetime (lt) parameter in the query string. While 530 updating dynamic resources, a SEP SHOULD include a Lifetime parameter 531 with the smallest value that matches its technical constraints. It 532 allows a client to fastly detect a stale mirror entry. A SEP MAY 533 omit processing some responses for non confirmable requests in order 534 to avoid spending energy waiting for a response when it is frequently 535 accessing a mirrored resource. Nevertheless a SEP SHOULD 536 periodically check the responses to ensure that its mirror entry is 537 still active on the MS. 539 Other specifications may override or extend this interface to provide 540 more advanced features, support other REST methods and queuing 541 patterns. This is however out of scope of this specification which 542 provides only a basic behavior. 544 The basic SEP operation interface is specified as follows: 546 Interaction: SEP -> MS 548 Method: GET, PUT 550 URI Template: /{+location}{+resource}{?lt} 551 URI Template Variables: 553 location := This is the Location path returned by the MS as a 554 result of a successful registration. 556 resource := This is the relative path to a mirrored resource 557 managed by the registered SEP. 559 lt := Lifetime (optional). The number of seconds by which the 560 lifetime of the whole mirror entry is extended. Range of 561 1-4294967295. If no lifetime is included, the current 562 remaining lifetime stays unchanged. 564 Content-Type: Defined at registration 566 Etag: The Etag option MAY be included to allow clients to validate a 567 resource on multiple Mirror Servers. 569 Success: 2.01 "Created", the request MUST include the initial 570 representation of the mirrored resource. 572 Success: 2.04 "Changed", the request MUST include the new 573 representation of the mirrored resource. 575 Success: 2.05 "Content", the response MUST include the current 576 representation of the mirrored resource. 578 Failure: 4.00 "Bad Request". Malformed request. 580 Failure: 5.03 "Service Unavailable". Service could not perform the 581 operation. 583 The following example describes how a sleeping endpoint can 584 initialize the resource containing its manufacturer name just after 585 registration. 587 SEP MS 588 | | 589 | --- PUT /ms/0/dev/mfg "acme" ---------------> | 590 | | 591 | | 592 | <-- 2.01 Created ----------------------------- | 593 | | 595 Req: PUT /ms/0/dev/mfg 596 Payload: acme 597 Res: 2.01 Created 598 The example below shows how a SEP can indicate that it is supposed to 599 send a temperature value at least every hour to keep its mirror entry 600 active. 602 SEP MS 603 | | 604 | --- PUT /ms/0/sen/temp?lt=3600 "22" --------> | 605 | | 606 | | 607 | <-- 2.04 Changed ----------------------------- | 608 | | 610 Req: PUT /ms/0/sen/temp?lt=3600 611 Payload: 22 612 Res: 2.04 Changed 614 4.7. Client Operation 616 The Client Operation interface is not defined for a Resource 617 Directory and is specific to the Mirror Server Function Set. 619 While the SEP operation interface describes only the interaction 620 between the SEP and the MS on mirrored resources, the interface 621 between a client and the MS for mirrored resources is actually 622 defined by the Link Format payload at registration. This 623 specification does not define the list of Interface Description 624 attribute values that a Mirror Server must support. This is left to 625 a companion specification such as a CoRE profile specification. A 626 Mirror Server MAY support complex interfaces that require special 627 logic and interactions between multiple mirrored resources. The CoRE 628 Batch interface defined in [I-D.shelby-core-interfaces] is an example 629 of complex interface that defines relations between a parent resource 630 and sub-resources using SenML [I-D.jennings-senml]. 632 A SEP may register resources with the "obs" attribute. In that case 633 a MS using the CoAP protocol [I-D.ietf-core-coap] SHOULD accept to 634 establish a CoAP observation relationship between the observable 635 mirrored resource and a client as defined in [I-D.ietf-core-observe]. 637 A SEP may stop updating its mirrored resources without explictly 638 removing its mirror entry (e.g. transition to another MS after 639 network unreachability detection). A client can detect this 640 situation when the corresponding mirror entry has expired. Upon 641 receipt of a response with error code 4.04 "Not Found", a client 642 SHOULD restart resource discovery to determine if the resources are 643 now mirrored on another MS. 645 The Client operation interface is specified as follows: 647 Interaction: Client -> MS 649 Method: Defined at registration 651 URI Template: /{+location}{+resource} 653 URI Template Variables: 655 location := This is the Location path returned by the MS as a 656 result of a successful registration. 658 resource := This is the relative path to a mirrored resource 659 managed by a SEP. 661 Content-Type: Defined at registration 663 In the example below a client observes the changes of temperature 664 through the Mirror Server. 666 SEP MS Client 667 | | | 668 | | <- GET /ms/0/sen/temp - | 669 | | (observe) | 670 | | | 671 | | -- 2.05 Content "22" -> | 672 | | | 673 | - PUT /ms/0/sen/temp "23" -> | | 674 | | | 675 | <- 2.04 Changed ------------ | | 676 | | | 677 | | -- 2.05 Content "23" -> | 679 4.8. Modification check 681 This interface is not defined for a Resource Directory and is 682 specific to the Mirror Server Function Set. 684 A sleeping endpoint may register resources supporting POST or PUT 685 methods and therefore that could be modified by clients. In that 686 case the SEP needs to poll these resources to detect updates. 687 Polling each modifiable resource is inefficient when they are 688 numerous. The modification check interface allows a SEP to retrieve 689 a list of resources that have been modified. The SEP can then send 690 GET requests on each resource of the list to get the updated 691 representation. A POST request on the check interface automatically 692 clears the list of modified resources. 694 The check interface is specified as follows: 696 Interaction: SEP -> MS 698 Method: POST 700 URI Template: /{+location}?chk 702 URI Template Variables: 704 location := This is the Location path returned by the MS as a 705 result of a successful registration. 707 Request Content-Type: None 709 Response Content-Type: application/link-format 711 Success: 2.04 "Changed", the response MUST include a list of web 712 links to resources that have been modified by clients. 714 Failure: 4.00 "Bad Request". Malformed request. 716 Failure: 5.03 "Service Unavailable". Service could not perform the 717 operation. 719 The following example shows a commissioning tool changing the name of 720 a sleeping device through a Mirror Server. A commissioning button on 721 the SEP triggers the reading of the new configuration. 723 SEP MS Client 724 | | | 725 | | <-- PUT /ms/0/dev/n --- | 726 | | | 727 | | -- 2.04 Changed ------> | 728 | | | 729 | [press button on SEP] | | 730 | | | 731 | - POST /ms/0?chk -------> | | 732 | | | 733 | <- 2.04 Changed --------- | | 734 | | | 735 | - GET /ms/0/dev/n ------> | | 736 | | | 737 | <- 2.05 Content --------- | | 738 | | | 740 Req: PUT /ms/0/dev/n 741 Payload: "sensor-1" 742 Res: 2.04 Changed 744 Req: POST /ms/0?chk 745 Res: 2.04 Changed 746 Payload: "" 748 Req: GET /ms/0/dev/n 749 Res: 2.05 Content 750 Payload: "sensor-1" 752 5. Acknowledgements 754 Thanks to Zach Shelby who is the author of the Resource Directory 755 interface. Thanks to Nicolas Riou, Jari Arkko, Esko Dijk who have 756 provided fruitful comments. 758 6. IANA Considerations 760 "core.ms" resource type needs to be registered. 762 The "ep" attribute needs to be registered. 764 7. Security Considerations 766 This document needs the same security considerations as described in 767 Section 7 of [RFC5988] and Section 6 of [I-D.ietf-core-link-format]. 769 The Mirror Server architecture defines the SEP and Client roles in 770 the Mirror Function Set interfaces. Since the roles are based on the 771 requester identity, a MS SHOULD perform appropriate authentication in 772 order to prevent a malicious client endpoint from impersonating the 773 SEP or an authorized client. Otherwise the malicious client could 774 gain access to interfaces allowing corruption or deletion of a 775 mirrored resource. 777 A malicious client could start a denial of service attack by trying 778 to mirror a large resource on a MS. Memory exhaustion would prevent 779 other sleeping endpoints from mirroring their resources. A MS SHOULD 780 use quotas to limit the size and the number of mirrored resources per 781 SEP. 783 A Mirror Server is actually an intermediary running at application 784 level. As a consequence the Mirror Server architecture can only 785 provide implicit end-to-end security that relies on a trusted network 786 if security is not available at application layer. When explicit 787 end-to-end security is required between a SEP and a Client, data 788 object security SHOULD be employed. 790 8. References 792 8.1. Normative References 794 [I-D.ietf-core-coap] 795 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 796 "Constrained Application Protocol (CoAP)", 797 draft-ietf-core-coap-10 (work in progress), June 2012. 799 [I-D.ietf-core-link-format] 800 Shelby, Z., "CoRE Link Format", 801 draft-ietf-core-link-format-14 (work in progress), 802 June 2012. 804 [I-D.ietf-core-observe] 805 Hartke, K., "Observing Resources in CoAP", 806 draft-ietf-core-observe-05 (work in progress), March 2012. 808 [I-D.shelby-core-interfaces] 809 Shelby, Z. and M. Vial, "CoRE Interfaces", 810 draft-shelby-core-interfaces-03 (work in progress), 811 July 2012. 813 [I-D.shelby-core-resource-directory] 814 Shelby, Z. and S. Krco, "CoRE Resource Directory", 815 draft-shelby-core-resource-directory-03 (work in 816 progress), May 2012. 818 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 819 Requirement Levels", BCP 14, RFC 2119, March 1997. 821 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 823 8.2. Informative References 825 [I-D.arkko-core-sleepy-sensors] 826 Arkko, J., Rissanen, H., Loreto, S., Turanyi, Z., and O. 827 Novo, "Implementing Tiny COAP Sensors", 828 draft-arkko-core-sleepy-sensors-01 (work in progress), 829 July 2011. 831 [I-D.jennings-senml] 832 Jennings, C., Shelby, Z., and J. Arkko, "Media Types for 833 Sensor Markup Language (SENML)", draft-jennings-senml-08 834 (work in progress), January 2012. 836 [I-D.shelby-core-coap-req] 837 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 838 Kelsey, "CoAP Requirements and Features", 839 draft-shelby-core-coap-req-02 (work in progress), 840 October 2010. 842 Author's Address 844 Matthieu Vial 845 Schneider-Electric 846 Grenoble, 847 FRANCE 849 Phone: +33 (0)47657 6522 850 Email: matthieu.vial@schneider-electric.com