idnits 2.17.1 draft-koster-core-coap-pubsub-05.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 7, 2016) is 2843 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 (-28) exists of draft-ietf-core-resource-directory-07 == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-05 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Koster 3 Internet-Draft SmartThings 4 Intended status: Standards Track A. Keranen 5 Expires: January 8, 2017 J. Jimenez 6 Ericsson 7 July 7, 2016 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-koster-core-coap-pubsub-05 12 Abstract 14 The Constrained Application Protocol (CoAP), and related extensions 15 are intended to support machine-to-machine communication in systems 16 where one or more nodes are resource constrained, in particular for 17 low power wireless sensor networks. This document defines a publish- 18 subscribe broker for CoAP that extends the capabilities of CoAP for 19 supporting nodes with long breaks in connectivity and/or up-time. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 8, 2017. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.1. CoAP pubsub Architecture . . . . . . . . . . . . . . . . 4 59 3.2. CoAP pubsub Broker . . . . . . . . . . . . . . . . . . . 4 60 3.3. CoAP pubsub Client . . . . . . . . . . . . . . . . . . . 5 61 3.4. CoAP pubsub Topic . . . . . . . . . . . . . . . . . . . . 5 62 3.5. Brokerless pubsub . . . . . . . . . . . . . . . . . . . . 5 63 4. CoAP pubsub Function Set . . . . . . . . . . . . . . . . . . 6 64 4.1. DISCOVER . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 14 69 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 15 70 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 16 71 5. CoAP pubsub Operation with Resource Directory . . . . . . . . 17 72 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 18 73 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 18 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 75 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 76 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 20 77 9.2. Response Code value '2.04' . . . . . . . . . . . . . . . 20 78 9.3. Response Code value '4.29' . . . . . . . . . . . . . . . 20 79 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 80 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 81 11.1. Normative References . . . . . . . . . . . . . . . . . . 21 82 11.2. Informative References . . . . . . . . . . . . . . . . . 22 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 85 1. Introduction 87 The Constrained Application Protocol (CoAP) [RFC7252] supports 88 machine-to-machine communication across networks of constrained 89 devices. CoAP uses a request/response model where clients make 90 requests to servers in order to request actions on resources. 91 Depending on the situation the same device may act either as a server 92 or a client. 94 One important class of constrained devices includes devices that are 95 intended to run for years from a small battery, or by scavenging 96 energy from their environment. These devices have limited 97 reachability because they spend most of their time in a sleeping 98 state with no network connectivity. Devices may also have limited 99 reachability due to certain middle-boxes, such as Network Address 100 Translators (NATs) or firewalls. Such middle-boxes often prevent 101 connecting to a device from the Internet unless the connection was 102 initiated by the device. 104 This document specifies the means for nodes with limited reachability 105 to communicate using simple extensions to CoAP. The extensions 106 enable publish-subscribe communication using a broker node that 107 enables store-and-forward messaging between two or more nodes. 108 Furthermore the extensions facilitate many-to-many communication 109 using CoAP. 111 2. Terminology 113 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 114 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 115 specification are to be interpreted as described in [RFC2119]. 117 This specification requires readers to be familiar with all the terms 118 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 119 should also be familiar with the terms and concepts discussed in 120 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 121 format [RFC6570] is used to describe the REST interfaces defined in 122 this specification. 124 This specification makes use of the following additional terminology: 126 Publish-Subscribe (pubsub): A messaging paradigm where messages are 127 published to a broker and potential receivers can subscribe to the 128 broker to receive messages. The publishers do not (need to) know 129 where the message will be eventually sent: the publications and 130 subscriptions are matched by a broker and publications are 131 delivered by the broker to subscribed receivers. 133 CoAP pubsub function set: A group of well-known REST resources that 134 together provide the CoAP pubsub service. 136 CoAP pubsub Broker: A server node capable of receiving messages 137 (publications) from and sending messages to other nodes, and able 138 to match subscriptions and publications in order to route messages 139 to the right destinations. The broker can also temporarily store 140 publications to satisfy future subscriptions. 142 CoAP pubsub Client: A CoAP client that implements the CoAP pubsub 143 function set. 145 Topic: A unique identifier for a particular item being published 146 and/or subscribed to. A broker uses the topics to match 147 subscriptions to publications. 149 3. Architecture 151 3.1. CoAP pubsub Architecture 153 Figure 1 shows the architecture of a CoAP pubsub service. CoAP 154 pubsub Clients interact with a CoAP pubsub Broker through the CoAP 155 pubsub interface which is hosted by the Broker. State information is 156 updated between the Clients and the Broker. The CoAP pubsub Broker 157 performs a store-and-forward function of state updates between 158 certain CoAP pubsub Clients. Clients Subscribe to state updates 159 which are Published by other Clients, and which are forwarded by the 160 Broker to the subscribing clients. The CoAP pubsub Broker also acts 161 as a REST proxy, retaining the last state update provided by clients 162 to supply in response to Read requests from Clients. 164 Clients pubsub Broker 165 +-------+ | 166 | CoAP | | 167 |pubsub |---------|------+ 168 |Client | | | +-------+ 169 +-------+ | +----| CoAP | 170 | |pubsub | 171 +-------+ | +----|Broker | 172 | CoAP | | | +-------+ 173 |pubsub |---------|------+ 174 |Client | | 175 +-------+ | 177 Figure 1: CoAP pubsub Architecture 179 3.2. CoAP pubsub Broker 181 A CoAP pubsub Broker is a CoAP Server that exposes an interface for 182 clients to use to initiate publish-subscribe interactions. Unlike 183 clients, the broker needs to be reachable by all clients. The broker 184 also needs to have sufficient resources (storage, bandwidth, etc.) to 185 host CoAP resources, and potentially buffer messages, on behalf of 186 the clients. 188 3.3. CoAP pubsub Client 190 A CoAP pubsub Client interacts with a CoAP pubsub Broker using the 191 CoAP pubsub interface. Clients initiate all interactions with the 192 CoAP pubsub broker. A data source (e.g., sensor clients) can publish 193 state updates to the broker and data sinks (e.g., actuator clients) 194 can read from or subscribe to state updates from the broker. 195 Application clients can make use of both publish and subscribe in 196 order to exchange state updates with data sources and sinks. 198 3.4. CoAP pubsub Topic 200 The clients and broker use topics to identify a particular resource 201 or object in a publish-subscribe system. Topics are conventionally 202 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 203 "EP-33543/sen/3303/0/5700". The topics are hosted at the broker and 204 all the clients using the broker share the same namespace for topics. 205 A CoAP pubsub topic has a reference path using URI path [RFC3986] 206 construction, link attributes [RFC6690], and a representation of a 207 value with specified content-formats. A CoAP pubsub topic value may 208 alternatively be a collection of one or more sub-topics, consisting 209 of links to the sub-topic URIs and indicated by a link-format 210 content-format. 212 3.5. Brokerless pubsub 214 Figure 2 shows an arrangement for using CoAP pubsub in a "brokerless" 215 configuration between peer nodes. Nodes in a brokerless system act 216 as both broker and client. The Broker interface in a brokerless node 217 may be pre-configured with topics that expose services and resources. 218 Brokerless peer nodes can be mixed with client and broker nodes in a 219 system with full interoperability. 221 Peer pubsub Peer 222 +-------+ | +-------+ 223 | CoAP | | | CoAP | 224 |pubsub |---------|---------|pubsub | 225 |Client | | |Broker | 226 +-------+ | +-------+ 227 | CoAP | | | CoAP | 228 |pubsub |---------|---------|pubsub | 229 |Broker | | |Client | 230 +-------+ | +-------+ 232 Figure 2: Brokerless pubsub 234 4. CoAP pubsub Function Set 236 This section defines the interfaces between a CoAP pubsub Broker and 237 pubsub Clients, which is called the CoAP pubsub Function Set. The 238 examples throughout this section assume the use of CoAP [RFC7252]. A 239 CoAP pubsub Broker implementing this specification MUST support the 240 DISCOVER, CREATE, PUBLISH, SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE 241 operations defined in this section. 243 4.1. DISCOVER 245 CoAP pubsub Clients discover CoAP pubsub Brokers by using CoAP Simple 246 Discovery or through a Resource Directory (RD) 247 [I-D.ietf-core-resource-directory]. A CoAP pubsub Broker SHOULD 248 indicate its presence and availability on a network by exposing a 249 link to its pubsub function set at its .well-known/core location 250 [RFC6690]. A CoAP pubsub broker MAY register its pubsub function set 251 location with a Resource Directory. Figure 3 shows an example of a 252 client discovering a local pubsub Function Set using CoAP Simple 253 Discovery. A broker wishing to advertise the CoAP pubsub Function 254 Set for Simple Discovery or through a Resource Directory MUST use the 255 link relation rt="core.ps". A broker MAY advertise it's supported 256 content formats and other attributes in the link to it's pubsub 257 function set. 259 A CoAP pubsub Broker MAY offer the Discover interface to enable 260 Clients to find topics of interest, either by topic name or by link 261 attributes which may be registered when the topic is created. 262 Figure 4 shows an example of a client looking for a topic with a 263 resource type (rt) of "temperature" in the pubsub function set /ps 264 using the Discover interface. The client then receives the URI of 265 the resource and its content-format. 267 A CoAP pubsub Broker MAY expose the Discover interface through the 268 .well-known/core resource. Links to topics may be exposed at .well- 269 known/core in addition to links to the pubsub function set. Figure 5 270 shows an example of topic discovery through .well-known/core. 272 The DISCOVER interface is specified as follows: 274 Interaction: Client -> Broker 276 Method: GET 278 URI Template: /.well-known/core 280 URI Template: /{+ps/}{topic}{/topic*}{?q*} 281 URI Template Variables: 283 /.well-known/core := for discovering the pubsub function set 284 (optional) 286 ps := pubsub Function Set path (optional). The path of the 287 pubsub Function Set, as obtained from discovery, used to 288 discover topics. 290 topic := The desired topic to return links for (optional). 292 q := Query Filter (optional). MAY contain a query filter list 293 as per [RFC6690] Section 4.1. 295 Content-Format: application/link-format 297 The following response codes are defined for this interface: 299 Success: 2.05 "Content" with an application/link-format payload 300 containing one or more matching entries for the broker resource. 301 A pubsub broker SHOULD use the value "/ps/" for the function set 302 URI wherever possible. 304 Failure: 4.04 "Not Found" is returned in case no matching entry is 305 found for a unicast request. 307 Failure: 4.00 "Bad Request" is returned in case of a malformed 308 request for a unicast request. 310 Failure: No error response to a multicast request. 312 Client Broker 313 | | 314 | ------ GET /.well-known/core?rt=core.ps ----->| 315 | ---Content-Format: application/link-format----| 316 | | 317 | <--2.05 Content ";rt="core.ps";ct=40----| 318 | | 320 Figure 3: Example of DISCOVER pubsub function 322 Client Broker 323 | | 324 | ---------- GET /ps/?rt="temperature" -------->| 325 | Content-Format: application/link-format | 326 | | 327 | <---2.05 Content | 328 | ;rt="temperature";ct=50 ---| 329 | | 331 Figure 4: Example of DISCOVER topic 333 Client Broker 334 | | 335 | -------- GET /.well-known/core?ct=50 -------->| 336 | Content-Format: application/link-format | 337 | | 338 | <---2.05 Content | 339 | ;rt="temperature";ct=50 ---| 340 | | 342 Figure 5: Example of DISCOVER topic 344 4.2. CREATE 346 Clients create topics on the broker using the CREATE interface. A 347 client wishing to create a topic MUST use CoAP POST to the pubsub 348 function set location with a payload indicating the desired topic. 349 The topic specification sent in the payload MUST use a supported 350 serialization of the CoRE link format [RFC6690]. The target of the 351 link MUST be a URI formatted string. The client MUST indicate the 352 desired content format for publishes to the topic by using the ct 353 (Content Format) link attribute in the link-format payload. The 354 client MAY indicate the lifetime of the topic by including the Max- 355 Age option in the CREATE request. Broker MUST return a response code 356 of "2.01 Created" if the topic is created and return the created 357 relative URI path via Location-Path options. The broker MUST return 358 the appropriate 4.xx response code indicating the reason for failure 359 if a new topic can not be created. Broker SHOULD remove topics if 360 the Max-Age of the topic is exceeded without any publishes to the 361 topic. Broker SHOULD retain a topic indefinitely if the Max-Age 362 option is elided or is set to zero upon topic creation. The lifetime 363 of a topic MUST be refreshed upon create operations with a target of 364 an existing topic. 366 Topics may be created as sub-topics of other topics. A client MAY 367 create a topic with a ct (Content Format) link attribute value which 368 describes a supported serialization of the CoRE link format [RFC6690] 369 such as application/link-format (ct=40) or its JSON or CBOR 370 serializations. If a topic is created which describes a link 371 serialization, that topic may then have sub-topics created under it 372 as shown in Figure 7. 374 The CREATE interface is specified as follows: 376 Interaction: Client -> Broker 378 Method: POST 380 URI Template: /{+ps/}{topic}{/topic*} 382 URI Template Variables: 384 ps := pubsub Function Set path (mandatory). The path of the 385 pubsub Function Set, as obtained from discovery. A pubsub 386 broker SHOULD use the value "ps" for this variable whenever 387 possible. 389 Content-Format: application/link-format 391 Payload: The desired topic to CREATE 393 The following response codes are defined for this interface: 395 Success: 2.01 "Created". Successful Creation of the topic 397 Failure: 4.00 "Bad Request". Malformed request. 399 Failure: 4.01 "Unauthorized". Authorization failure. 401 Failure: 4.03 "Forbidden". Topic already exists. 403 Failure: 4.06 "Not Acceptable". Unsupported content format for 404 topic. 406 Figure 6 shows an example of a topic called "topic1" being 407 successfully created. 409 Client Broker 410 | | 411 | ---------- POST /ps ";ct=50" -------->| 412 | | 413 | <---------------- 2.01 Created ---------------| 414 | Location: /ps/topic1 | 415 | | 417 Figure 6: Example of CREATE topic 419 Client Broker 420 | | 421 | ------- POST /ps/ ";ct=40" ------->| 422 | | 423 | <---------------- 2.01 Created ---------------| 424 | Location: /ps/mainTopic/ | 425 | | 426 | --- POST /ps/mainTopic/ ";ct=50" -->| 427 | | 428 | <---------------- 2.01 Created ---------------| 429 | Location: /ps/mainTopic/subTopic | 430 | | 431 | | 433 Figure 7: Example of CREATE sub-topic 435 4.3. PUBLISH 437 A CoAP pubsub Client uses the PUBLISH interface for updating topics 438 on the broker. The client MUST use the PUT method to publish state 439 updates to the CoAP pubsub Broker. A client MUST use the content 440 format specified upon creation of a given topic to publish updates to 441 that topic. The broker MUST reject publish operations which do not 442 use the specified content format. A CoAP client publishing on a 443 topic MAY indicate the maximum lifetime of the value by including the 444 Max-Age option in the publish request. The broker MUST return a 445 response code of "2.04 Changed" if the publish is accepted or "4.04 446 Not Found" if the topic does not exist. A broker MAY return "4.29 447 Too Many Requests" if simple flow control as described in Section 7 448 is implemented. 450 The Broker MUST notify all clients subscribed on a particular topic 451 each time it receives a publish on that topic. An example is shown 452 in Figure 9. If a client publishes to a broker with the Max-Age 453 option, the broker MUST include the same value for the Max-Age option 454 in all notifications. A broker MUST use CoAP Notification as 455 described in [RFC7641] to notify subscribed clients. 457 The PUBLISH interface is specified as follows: 459 Interaction: Client -> Broker 461 Method: PUT 463 URI Template: /{+ps/}{topic}{/topic*} 465 URI Template Variables: 467 ps := pubsub Function Set path (mandatory). The path of the 468 pubsub Function Set, as obtained from discovery. 470 topic := The desired topic to publish on. 472 Content-Format: Any valid CoAP content format 474 Payload: Representation of the topic value (CoAP resource state 475 representation) in the indicated content format 477 The following response codes are defined for this interface: 479 Success: 2.04 "Changed". Successful publish, topic is updated 481 Failure: 4.00 "Bad Request". Malformed request. 483 Failure: 4.01 "Unauthorized". Authorization failure. 485 Failure: 4.04 "Not Found". Topic does not exist. 487 Failure: 4.29 "Too Many Requests". The client should slow down the 488 rate of publish messages for this topic (see Section 7). 490 Figure 8 shows an example of a new value being successfully published 491 to the topic "topic1". See Figure 9 for an example of a broker 492 forwarding a message from a publishing client to a subscribed client. 494 Client Broker 495 | | 496 | ---------- PUT /ps/topic1 "1033.3" --------> | 497 | | 498 | | 499 | <--------------- 2.04 Changed---------------- | 500 | | 502 Figure 8: Example of PUBLISH 504 4.4. SUBSCRIBE 506 CoAP pubsub Clients subscribe to topics on the Broker using CoAP 507 Observe as described in [RFC7641]. A CoAP pubsub Client wishing to 508 Subscribe to a topic on a broker MUST use a CoAP GET with Observe 509 registration. The Broker MAY add the client to a list of observers. 510 The Broker MUST return a response code of "2.05 Content" along with 511 the most recently published value if the topic contains a valid value 512 and the broker can supply the requested content format. The broker 513 MUST accept Subscribe requests on a topic if the content format of 514 the request matches the content format the topic was created with. 515 The broker MAY accept Subscribe requests which specify content 516 formats that the broker can supply as alternate content formats to 517 the content format the topic was registered with. If the topic was 518 published with the Max-Age option, the broker MUST set the Max-Age 519 option in the valid response to the amount of time remaining for the 520 value to be valid since the last publish operation on that topic. 521 The Broker MUST return a response code of "2.04 No Content" if the 522 Max-Age of the previously stored value has expired. The Broker MUST 523 return a response code "4.04 Not Found" if the topic does not exist 524 or has been removed. The Broker MUST return a response code "4.15 525 Unsupported Content Format" if it can not return the requested 526 content format. If a Broker is unable to accept a new Subscription 527 on a topic, it SHOULD return the appropriate response code without 528 the Observe option as per as per [RFC7641] Section 4.1. There is no 529 explicit maximum lifetime of a Subscription, thus a Broker may remove 530 subscribers at any time. The Broker, upon removing a Subscriber, 531 will transmit the appropriate response code without the Observe 532 option, as per [RFC7641] Section 4.2, to the removed Subscriber. 534 The SUBSCRIBE interface is specified as follows: 536 Interaction: Client -> Broker 538 Method: GET 540 Options: Observe:0 541 URI Template: /{+ps/}{topic}{/topic*} 543 URI Template Variables: 545 ps := pubsub Function Set path (mandatory). The path of the 546 pubsub Function Set, as obtained from discovery. 548 topic := The desired topic to subscribe to. 550 The following response codes are defined for this interface: 552 Success: 2.05 "Content". Successful subscribe, current value 553 included 555 Success: 2.04 "No Content". Successful subscribe, value not 556 included 558 Failure: 4.00 "Bad Request". Malformed request. 560 Failure: 4.01 "Unauthorized". Authorization failure. 562 Failure: 4.04 "Not Found". Topic does not exist. 564 Failure: 4.15 "Unsupported Content Format". Unsupported content 565 format. 567 Figure 9 shows an example of Client2 subscribing to "topic1" and 568 receiving a response from the broker, with a subsequent notification. 569 The subscribe response from the broker uses the last stored value 570 associated with the topic1. The notification from the broker is sent 571 in response to the publish received from Client1. 573 Client1 Client2 Broker 574 | | Subscribe | 575 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 576 | | | 577 | | <---------- 2.05 Content Observe:10---------- | 578 | | | 579 | | | 580 | | Publish | 581 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 582 | | Notify | 583 | | <---------- 2.05 Content Observe:11---------- | 584 | | | 586 Figure 9: Example of SUBSCRIBE 588 4.5. UNSUBSCRIBE 590 CoAP pubsub Clients unsubscribe from topics on the Broker using the 591 CoAP Cancel Observation operation. A CoAP pubsub Client wishing to 592 unsubscribe to a topic on a Broker MUST either use CoAP GET with 593 Observe using an Observe parameter of 1 or send a CoAP Reset message 594 in response to a publish, as per [RFC7641]. 596 The UNSUBSCRIBE interface is specified as follows: 598 Interaction: Client -> Broker 600 Method: GET 602 Options: Observe:1 604 URI Template: /{+ps/}{topic}{/topic*} 606 URI Template Variables: 608 ps := pubsub Function Set path (mandatory). The path of the 609 pubsub Function Set, as obtained from discovery. 611 topic := The desired topic to unsubscribe from. 613 The following response codes are defined for this interface: 615 Success: 2.05 "Content". Successful unsubscribe, current value 616 included 618 Success: 2.04 "No Content". Successful unsubscribe, value not 619 included 621 Failure: 4.00 "Bad Request". Malformed request. 623 Failure: 4.01 "Unauthorized". Authorization failure. 625 Failure: 4.04 "Not Found". Topic does not exist. 627 Figure 10 shows an example of a client unsubscribe using the 628 Observe=1 cancellation method. 630 Client Broker 631 | | 632 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 633 | | 634 | <------------- 2.05 Content ----------------- | 635 | | 637 Figure 10: Example of UNSUBSCRIBE 639 4.6. READ 641 A CoAP pubsub client wishing to obtain only the most recent published 642 value on a topic MAY use the READ interface. For reading, the client 643 uses the CoAP GET method. The broker MUST accept Read requests on a 644 topic if the content format of the request matches the content format 645 the topic was created with. The broker MAY accept Read requests 646 which specify content formats that the broker can supply as alternate 647 content formats to the content format the topic was registered with. 648 The Broker MUST return a response code of "2.05 Content" along with 649 the most recently published value if the topic contains a valid value 650 and the broker can supply the requested content format. If the topic 651 was published with the Max-Age option, the broker MUST set the Max- 652 Age option in the valid response to the amount of time remaining for 653 the topic to be valid since the last publish. The Broker MUST return 654 a response code of "2.04 No Content" if the Max-Age of the previously 655 stored value has expired. The Broker MUST return a response code 656 "4.04 Not Found" if the topic does not exist or has been removed. 657 The Broker MUST return a response code "4.15 Unsupported Content 658 Format" if the broker can not return the requested content format. 660 The READ interface is specified as follows: 662 Interaction: Client -> Broker 664 Method: GET 666 URI Template: /{+ps/}{topic}{/topic*} 668 URI Template Variables: 670 ps := pubsub Function Set path (mandatory). The path of the 671 pubsub Function Set, as obtained from discovery. 673 topic := The desired topic to READ. 675 The following response codes are defined for this interface: 677 Success: 2.05 "Content". Successful READ, current value included 679 Success: 2.04 "No Content". Topic exists, value not included 681 Failure: 4.00 "Bad Request". Malformed request. 683 Failure: 4.01 "Unauthorized". Authorization failure. 685 Failure: 4.04 "Not Found". Topic does not exist. 687 Failure: 4.15 "Unsupported Content Format". Unsupported content- 688 format. 690 Figure 11 shows an example of a successful READ from topic1, followed 691 by a Publish on the topic, followed at some time later by a read of 692 the updated value from the recent Publish. 694 Client1 Client2 Broker 695 | | Read | 696 | | --------------- GET /ps/topic1 -------------> | 697 | | | 698 | | <---------- 2.05 Content "1007.1"------------ | 699 | | | 700 | | | 701 | | Publish | 702 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 703 | | | 704 | | | 705 | | Read | 706 | | --------------- GET /ps/topic1 -------------> | 707 | | | 708 | | <----------- 2.05 Content "1033.3"----------- | 709 | | | 711 Figure 11: Example of READ 713 4.7. REMOVE 715 A CoAP pubsub Client wishing to remove a topic MAY use the CoAP 716 Delete operation on the URI of the topic. The CoAP pubsub Broker 717 MUST return "2.02 Deleted" if the remove operation is successful. 718 The broker MUST return the appropriate 4.xx response code indicating 719 the reason for failure if the topic can not be removed. When a topic 720 is removed for any reason, the Broker SHOULD return the response code 721 4.04 Not Found and remove all of the observers from the list of 722 observers as per as per [RFC7641] Section 3.2. 724 The REMOVE interface is specified as follows: 726 Interaction: Client -> Broker 728 Method: DELETE 730 URI Template: /{+ps/}{topic}{/topic*} 732 URI Template Variables: 734 ps := pubsub Function Set path (mandatory). The path of the 735 pubsub Function Set, as obtained from discovery. 737 topic := The desired topic to REMOVE. 739 Content-Format: None 741 Response Payload: None 743 The following response codes are defined for this interface: 745 Success: 2.02 "Deleted". Successful remove 747 Failure: 4.00 "Bad Request". Malformed request. 749 Failure: 4.01 "Unauthorized". Authorization failure. 751 Failure: 4.04 "Not Found". Topic does not exist. 753 Figure 12 shows a successful remove of topic1. 755 Client Broker 756 | | 757 | ------------- DELETE /ps/topic1 ------------> | 758 | | 759 | | 760 | <-------------- 2.02 Deleted ---------------- | 761 | | 763 Figure 12: Example of REMOVE 765 5. CoAP pubsub Operation with Resource Directory 767 A CoAP pubsub Broker may register a pubsub Function Set with a 768 Resource Directory. A pubsub Client may use an RD to discover a 769 pubsub Broker. 771 A CoAP pubsub Client may register links [RFC6690] with a Resource 772 Directory to enable discovery of created pubsub topics. A pubsub 773 Client may use an RD to discover pubsub Topics. A client which 774 registers pubsub Topics with an RD MUST use the context relation 775 (con) [I-D.ietf-core-resource-directory] to indicate that the context 776 of the registered links is the pubsub Broker. 778 A CoAP pubsub Broker may alternatively register links to its topics 779 to a Resource Directory by triggering the RD to retrieve it's links 780 from .well-known/core. In order to use this method, the links must 781 first be exposed in the .well-known/core of the pubsub broker. See 782 Section 4.1 in this document. 784 The pubsub broker triggers the RD to retrieve its links by sending a 785 POST with an empty payload to the .well-known/core of the Resource 786 Directory. The RD server will then retrieve the links from the 787 .well-known/core of the pubsub broker and incorporate them into the 788 Resource Directory. See [I-D.ietf-core-resource-directory] for 789 further details. 791 6. Sleep-Wake Operation 793 CoAP pubsub provides a way for client nodes to sleep between 794 operations, conserving energy during idle periods. This is made 795 possible by shifting the server role to the broker, allowing the 796 broker to be always-on and respond to requests from other clients 797 while a particular client is sleeping. 799 For example, the broker will retain the last state update received 800 from a sleeping client, in order to supply the most recent state 801 update to other clients in response to read and subscribe operations. 803 Likewise, the broker will retain the last state update received on 804 the topic such that a sleeping client, upon waking, can perform a 805 read operation to the broker to update its own state from the most 806 recent system state update. 808 7. Simple Flow Control 810 Since the broker node has to potentially send a large amount of 811 notification messages for each publish message and it may be serving 812 a large amount of subscribers and publishers simultaneously, the 813 broker may become overwhelmed if it receives many publish messages to 814 popular topics in a short period of time. 816 If the broker is unable to serve a certain client that is sending 817 publish messages too fast, the broker MUST respond with Response Code 818 4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too 819 Many Requests" but uses the Max-Age Option in place of the "Retry- 820 After" header field to indicate the number of seconds after which to 821 retry. The broker MAY stop creating notifications from the publish 822 messages from this client and to this topic for the indicated time. 824 If a client receives the 4.29 Response Code from the broker for a 825 publish message to a topic, it MUST NOT send new publish messages to 826 the broker on the same topic before the time indicated in Max-Age has 827 passed. 829 8. Security Considerations 831 CoAP pubsub re-uses CoAP [RFC7252], CoRE Resource Directory 832 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 833 therefore the security considerations of those documents also apply 834 to this specification. Additionally, a CoAP pubsub broker and the 835 clients SHOULD authenticate each other and enforce access control 836 policies. A malicious client could subscribe to data it is not 837 authorized to or mount a denial of service attack against the broker 838 by publishing a large number of resources. The authentication can be 839 performed using the already standardized DTLS offered mechanisms, 840 such as certificates. DTLS also allows communication security to be 841 established to ensure integrity and confidentiality protection of the 842 data exchanged between these relevant parties. Provisioning the 843 necessary credentials, trust anchors and authorization policies is 844 non-trivial and subject of ongoing work. 846 The use of a CoAP pubsub broker introduces challenges for the use of 847 end-to-end security between for example a client device on a sensor 848 network and a client application running in a cloud-based server 849 infrastructure since brokers terminate the exchange. While running 850 separate DTLS sessions from the client device to the broker and from 851 broker to client application protects confidentially on those paths, 852 the client device does not know whether the commands coming from the 853 broker are actually coming from the client application. Similarly, a 854 client application requesting data does not know whether the data 855 originated on the client device. For scenarios where end-to-end 856 security is desirable the use of application layer security is 857 unavoidable. Application layer security would then provide a 858 guarantee to the client device that any request originated at the 859 client application. Similarly, integrity protected sensor data from 860 a client device will also provide guarantee to the client application 861 that the data originated on the client device itself. The protected 862 data can also be verified by the intermediate broker ensuring that it 863 stores/caches correct request/response and no malicious messages/ 864 requests are accepted. The broker would still be able to perform 865 aggregation of data/requests collected. 867 Depending on the level of trust users and system designers place in 868 the CoAP pubsub broker, the use of end-to-end object security is 869 RECOMMENDED [I-D.selander-ace-object-security]. 871 When only end-to-end encryption is necessary and the CoAP Broker is 872 trusted, Payload Only Protection (Mode:PAYL) could be used. The 873 Publisher would wrap only the payload before sending it to the broker 874 and set the option Content-Format to application/smpayl. Upon 875 receival, the Broker can read the unencrypted CoAP header to forward 876 it to the subscribers. 878 9. IANA Considerations 880 This document registers one attribute value in the Resource Type 881 (rt=) registry established with [RFC6690] and appends to the 882 definition of one CoAP Response Code in the CoRE Parameters Registry. 884 9.1. Resource Type value 'core.ps' 886 o Attribute Value: core.ps 888 o Description: Section 4 of [[This document]] 890 o Reference: [[This document]] 892 o Notes: None 894 9.2. Response Code value '2.04' 896 o Response Code: 2.04 898 o Description: Add No Content response to GET to the existing 899 definition of the 2.04 response code. 901 o Reference: [[This document]] 903 o Notes: None 905 9.3. Response Code value '4.29' 907 o Response Code: 4.29 909 o Description: This error code is used by a server to indicate that 910 a client is making too many requests on a resource. 912 o Reference: [[This document]] 914 o Notes: None 916 10. Acknowledgements 918 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 919 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 920 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 921 and reviews. 923 11. References 925 11.1. Normative References 927 [I-D.ietf-core-resource-directory] 928 Shelby, Z., Koster, M., Bormann, D., and P. Stok, "CoRE 929 Resource Directory", draft-ietf-core-resource-directory-07 930 (work in progress), March 2016. 932 [I-D.selander-ace-object-security] 933 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 934 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 935 object-security-05 (work in progress), July 2016. 937 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 938 Requirement Levels", BCP 14, RFC 2119, 939 DOI 10.17487/RFC2119, March 1997, 940 . 942 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 943 Resource Identifier (URI): Generic Syntax", STD 66, 944 RFC 3986, DOI 10.17487/RFC3986, January 2005, 945 . 947 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 948 and D. Orchard, "URI Template", RFC 6570, 949 DOI 10.17487/RFC6570, March 2012, 950 . 952 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 953 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 954 . 956 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 957 Application Protocol (CoAP)", RFC 7252, 958 DOI 10.17487/RFC7252, June 2014, 959 . 961 [RFC7641] Hartke, K., "Observing Resources in the Constrained 962 Application Protocol (CoAP)", RFC 7641, 963 DOI 10.17487/RFC7641, September 2015, 964 . 966 11.2. Informative References 968 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 969 DOI 10.17487/RFC5988, October 2010, 970 . 972 Authors' Addresses 974 Michael Koster 975 SmartThings 977 Email: Michael.Koster@smartthings.com 979 Ari Keranen 980 Ericsson 982 Email: ari.keranen@ericsson.com 984 Jaime Jimenez 985 Ericsson 987 Email: jaime.jimenez@ericsson.com