idnits 2.17.1 draft-ietf-core-coap-pubsub-02.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. 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 4, 2017) is 2486 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) == Unused Reference: 'I-D.selander-ace-object-security' is defined on line 1039, but no explicit reference was found in the text == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-10 == Outdated reference: A later version (-06) exists of draft-palombini-ace-coap-pubsub-profile-00 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 6 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 5, 2018 J. Jimenez 6 Ericsson 7 July 4, 2017 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-02 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 5, 2018. 38 Copyright Notice 40 Copyright (c) 2017 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 REST API . . . . . . . . . . . . . . . . . . . . 6 64 4.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 14 69 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 17 71 5. CoAP pubsub Operation with Resource Directory . . . . . . . . 18 72 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 19 73 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 19 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 75 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 76 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 21 77 9.2. Resource Type value 'core.ps.discover' . . . . . . . . . 21 78 9.3. Response Code value '2.07' . . . . . . . . . . . . . . . 21 79 9.4. Response Code value '4.29' . . . . . . . . . . . . . . . 21 80 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 81 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 82 11.1. Normative References . . . . . . . . . . . . . . . . . . 22 83 11.2. Informative References . . . . . . . . . . . . . . . . . 23 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 86 1. Introduction 88 The Constrained Application Protocol (CoAP) [RFC7252] supports 89 machine-to-machine communication across networks of constrained 90 devices. CoAP uses a request/response model where clients make 91 requests to servers in order to request actions on resources. 92 Depending on the situation the same device may act either as a server 93 or a client. 95 One important class of constrained devices includes devices that are 96 intended to run for years from a small battery, or by scavenging 97 energy from their environment. These devices have limited 98 reachability because they spend most of their time in a sleeping 99 state with no network connectivity. Devices may also have limited 100 reachability due to certain middle-boxes, such as Network Address 101 Translators (NATs) or firewalls. Such middle-boxes often prevent 102 connecting to a device from the Internet unless the connection was 103 initiated by the device. 105 This document specifies the means for nodes with limited reachability 106 to communicate using simple extensions to CoAP. The extensions 107 enable publish-subscribe communication using a broker node that 108 enables store-and-forward messaging between two or more nodes. 109 Furthermore the extensions facilitate many-to-many communication 110 using CoAP. 112 2. Terminology 114 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 115 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 116 specification are to be interpreted as described in [RFC2119]. 118 This specification requires readers to be familiar with all the terms 119 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 120 should also be familiar with the terms and concepts discussed in 121 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 122 format [RFC6570] is used to describe the REST interfaces defined in 123 this specification. 125 This specification makes use of the following additional terminology: 127 Publish-Subscribe (pubsub): A messaging paradigm where messages are 128 published to a broker and potential receivers can subscribe to the 129 broker to receive messages. The publishers do not (need to) know 130 where the message will be eventually sent: the publications and 131 subscriptions are matched by a broker and publications are 132 delivered by the broker to subscribed receivers. 134 CoAP pubsub service: A group of REST resources, as defined in this 135 document, which together implement the required features of this 136 specification. 138 CoAP pubsub Broker: A server node capable of receiving messages 139 (publications) from and sending messages to other nodes, and able 140 to match subscriptions and publications in order to route messages 141 to the right destinations. The broker can also temporarily store 142 publications to satisfy future subscriptions and pending 143 notifications. 145 CoAP pubsub Client: A CoAP client which is capable of publish or 146 subscribe operations as defined in this specification. 148 Topic: A unique identifier for a particular item being published 149 and/or subscribed to. A broker uses the topics to match 150 subscriptions to publications. A topic is a valid CoAP URI as 151 defined in [RFC7252] 153 3. Architecture 155 3.1. CoAP pubsub Architecture 157 Figure 1 shows the architecture of a CoAP pubsub service. CoAP 158 pubsub Clients interact with a CoAP pubsub Broker through the CoAP 159 pubsub REST API which is hosted by the Broker. State information is 160 updated between the Clients and the Broker. The CoAP pubsub Broker 161 performs a store-and-forward of state update representations between 162 certain CoAP pubsub Clients. Clients Subscribe to topics upon which 163 representations are Published by other Clients, which are forwarded 164 by the Broker to the subscribing clients. A CoAP pubsub Broker may 165 be used as a REST resource proxy, retaining the last published 166 representation to supply in response to Read requests from Clients. 168 Clients pubsub Broker 169 +-------+ | 170 | CoAP | | 171 |pubsub |---------|------+ 172 |Client | | | +-------+ 173 +-------+ | +----| CoAP | 174 | |pubsub | 175 +-------+ | +----|Broker | 176 | CoAP | | | +-------+ 177 |pubsub |---------|------+ 178 |Client | | 179 +-------+ | 181 Figure 1: CoAP pubsub Architecture 183 3.2. CoAP pubsub Broker 185 A CoAP pubsub Broker is a CoAP Server that exposes a REST API for 186 clients to use to initiate publish-subscribe interactions. Avoiding 187 the need for direct reachability between clients, the broker only 188 needs to be reachable from all clients. The broker also needs to 189 have sufficient resources (storage, bandwidth, etc.) to host CoAP 190 resource services, and potentially buffer messages, on behalf of the 191 clients. 193 3.3. CoAP pubsub Client 195 A CoAP pubsub Client interacts with a CoAP pubsub Broker using the 196 CoAP pubsub REST API defined in this document. Clients initiate 197 interactions with a CoAP pubsub broker. A data source (e.g., sensor 198 clients) can publish state updates to the broker and data sinks 199 (e.g., actuator clients) can read from or subscribe to state updates 200 from the broker. Application clients can make use of both publish 201 and subscribe in order to exchange state updates with data sources 202 and data sinks. 204 3.4. CoAP pubsub Topic 206 The clients and broker use topics to identify a particular resource 207 or object in a publish-subscribe system. Topics are conventionally 208 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 209 "EP-33543/sen/3303/0/5700". The topics are hosted at the broker and 210 all the clients using the broker share the same namespace for topics. 211 Every CoAP pubsub topic has a link, consisting of a reference path on 212 the broker using URI path [RFC3986] construction and link attributes 213 [RFC6690]. Every topic is associated with zero or more stored 214 representations with a content-format specified in the link. A CoAP 215 pubsub topic value may alternatively be a collection of one or more 216 sub-topics, consisting of links to the sub-topic URIs and indicated 217 by a link-format content-format. 219 3.5. Brokerless pubsub 221 Figure 2 shows an arrangement for using CoAP pubsub in a "brokerless" 222 configuration between peer nodes. Nodes in a brokerless system may 223 act as both broker and client. The Broker interface in a brokerless 224 node may be pre-configured with topics that expose services and 225 resources. Brokerless peer nodes can be mixed with client and broker 226 nodes in a system with full interoperability. 228 Peer pubsub Peer 229 +-------+ | +-------+ 230 | CoAP | | | CoAP | 231 |pubsub |---------|---------|pubsub | 232 |Client | | |Broker | 233 +-------+ | +-------+ 234 | CoAP | | | CoAP | 235 |pubsub |---------|---------|pubsub | 236 |Broker | | |Client | 237 +-------+ | +-------+ 239 Figure 2: Brokerless pubsub 241 4. CoAP pubsub REST API 243 This section defines the REST API exposed by a CoAP pubsub Broker to 244 pubsub Clients. The examples throughout this section assume the use 245 of CoAP [RFC7252]. A CoAP pubsub Broker implementing this 246 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 247 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 248 section. Optimized implementations MAY support a subset of the 249 operations as required by particular constrained use cases. 251 4.1. DISCOVERY 253 CoAP pubsub Clients discover CoAP pubsub Brokers by using CoAP Simple 254 Discovery or through a Resource Directory (RD) 255 [I-D.ietf-core-resource-directory]. A CoAP pubsub Broker SHOULD 256 indicate its presence and availability on a network by exposing a 257 link to the entry point of its pubsub API at its .well-known/core 258 location [RFC6690]. A CoAP pubsub broker MAY register its pubsub 259 REST API entry point with a Resource Directory. Figure 3 shows an 260 example of a client discovering a local pubsub API using CoAP Simple 261 Discovery. A broker wishing to advertise the CoAP pubsub API for 262 Simple Discovery or through a Resource Directory MUST use the link 263 relation rt=core.ps. A broker MAY advertise its supported content 264 formats and other attributes in the link to its pubsub API. 266 A CoAP pubsub Broker MAY offer a topic discovery entry point to 267 enable Clients to find topics of interest, either by topic name or by 268 link attributes which may be registered when the topic is created. 269 Figure 4 shows an example of a client looking for a topic with a 270 resource type (rt) of "temperature" using Discover. The client then 271 receives the URI of the resource and its content-format. A pubsub 272 broker wishing to advertize topic discovery MUST use the relation 273 rt=core.ps.discover in the link. 275 A CoAP pubsub Broker MAY expose the Discover interface through the 276 .well-known/core resource. Links to topics may be exposed at .well- 277 known/core in addition to links to the pubsub API. Figure 5 shows an 278 example of topic discovery through .well-known/core. 280 The DISCOVER interface is specified as follows: 282 Interaction: Client -> Broker 284 Method: GET 286 URI Template: {+ps}/{+topic}{?q*} 287 URI Template Variables: ps := pubsub REST API entry point 288 (optional). The entry point of the pubsub REST API, as obtained 289 from discovery, used to discover topics. 291 topic := The desired topic to return links for (optional). 293 q := Query Filter (optional). MAY contain a query filter list as 294 per [RFC6690] Section 4.1. 296 Content-Format: application/link-format 298 The following response codes are defined for this interface: 300 Success: 2.05 "Content" with an application/link-format payload 301 containing one or more matching entries for the broker resource. 302 A pubsub broker SHOULD use the value "/ps/" for the base URI of 303 the pubsub API wherever possible. 305 Failure: 4.04 "Not Found" is returned in case no matching entry is 306 found for a unicast request. 308 Failure: 4.00 "Bad Request" is returned in case of a malformed 309 request for a unicast request. 311 Failure: No error response to a multicast request. 313 Client Broker 314 | | 315 | ------ GET /.well-known/core?rt=core.ps ---->>| 316 | -- Content-Format: application/link-format ---| 317 | | 318 | <<--- 2.05 Content | 319 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 320 | | 322 Figure 3: Example of DISCOVER pubsub function 324 Client Broker 325 | | 326 | ---------- GET /ps/?rt="temperature" ------->>| 327 | Content-Format: application/link-format | 328 | | 329 | <<-- 2.05 Content | 330 | ;rt="temperature";ct=50 ---| 331 | | 333 Figure 4: Example of DISCOVER topic 335 Client Broker 336 | | 337 | -------- GET /.well-known/core?ct=50 ------->>| 338 | Content-Format: application/link-format | 339 | | 340 | <<-- 2.05 Content | 341 | ;rt="temperature";ct=50 ---| 342 | | 344 Figure 5: Example of DISCOVER topic 346 4.2. CREATE 348 A CoAP pubsub broker MAY allow Clients to create new topics on the 349 broker using CREATE. A client wishing to create a topic MUST use 350 CoAP POST to the pubsub API with a payload indicating the desired 351 topic. The topic specification sent in the payload MUST use a 352 supported serialization of the CoRE link format [RFC6690]. The 353 target of the link MUST be a URI formatted string. The client MUST 354 indicate the desired content format for publishes to the topic by 355 using the ct (Content Format) link attribute in the link-format 356 payload. The client MAY indicate the lifetime of the topic by 357 including the Max-Age option in the CREATE request. 359 A Broker MUST return a response code of "2.01 Created" if the topic 360 is created and return the URI path of the created topic via Location- 361 Path options. The broker MUST return the appropriate 4.xx response 362 code indicating the reason for failure if a new topic can not be 363 created. Broker SHOULD remove topics if the Max-Age of the topic is 364 exceeded without any publishes to the topic. Broker SHOULD retain a 365 topic indefinitely if the Max-Age option is elided or is set to zero 366 upon topic creation. The lifetime of a topic MUST be refreshed upon 367 create operations with a target of an existing topic. 369 Topics may be created as sub-topics of other topics. A client MAY 370 create a topic with a ct (Content Format) link attribute value which 371 describes a supported serialization of the CoRE link format [RFC6690] 372 such as application/link-format (ct=40) or its JSON or CBOR 373 serializations. If a topic is created which describes a link 374 serialization, that topic may then have sub-topics created under it 375 as shown in Figure 7. 377 The CREATE interface is specified as follows: 379 Interaction: Client -> Broker 381 Method: POST 383 URI Template: {+ps}/{+topic}{?q*} 385 URI Template Variables: ps := pubsub REST API entry point 386 (optional). The entry point of the pubsub REST API, as obtained 387 from discovery, used to discover topics. 389 topic := The desired topic to return links for (optional). 391 q := Query Filter (optional). MAY contain a query filter list as 392 per [RFC6690] Section 4.1. 394 Content-Format: application/link-format 396 Payload: The desired topic to CREATE 398 The following response codes are defined for this interface: 400 Success: 2.01 "Created". Successful Creation of the topic 402 Failure: 4.00 "Bad Request". Malformed request. 404 Failure: 4.01 "Unauthorized". Authorization failure. 406 Failure: 4.03 "Forbidden". Topic already exists. 408 Failure: 4.06 "Not Acceptable". Unsupported content format for 409 topic. 411 Figure 6 shows an example of a topic called "topic1" being 412 successfully created. 414 Client Broker 415 | | 416 | ---------- POST /ps/ ";ct=50" -------->| 417 | | 418 | <---------------- 2.01 Created ---------------| 419 | Location: /ps/topic1 | 420 | | 422 Figure 6: Example of CREATE topic 424 Client Broker 425 | | 426 | ------- POST /ps/ ";ct=40" ------->| 427 | | 428 | <---------------- 2.01 Created ---------------| 429 | Location: /ps/mainTopic/ | 430 | | 431 | --- POST /ps/mainTopic/ ";ct=50" -->| 432 | | 433 | <---------------- 2.01 Created ---------------| 434 | Location: /ps/mainTopic/subTopic | 435 | | 436 | | 438 Figure 7: Example of CREATE sub-topic 440 4.3. PUBLISH 442 A CoAP pubsub broker MAY allow clients to PUBLISH to topics on the 443 broker. A client MAY use the PUT or the POST method to publish state 444 updates to the CoAP pubsub Broker. A client MUST use the content 445 format specified upon creation of a given topic to publish updates to 446 that topic. The broker MUST reject publish operations which do not 447 use the specified content format. A CoAP client publishing on a 448 topic MAY indicate the maximum lifetime of the value by including the 449 Max-Age option in the publish request. The broker MUST return a 450 response code of "2.04 Changed" if the publish is accepted. A Broker 451 MAY return a "4.04 Not Found" if the topic does not exist. A broker 452 MAY return "4.29 Too Many Requests" if simple flow control as 453 described in Section 7 is implemented. 455 A Broker MUST accept PUBLISH operations using the PUT method. 456 PUBLISH operations using the PUT method replace any stored 457 representation associated with the topic, with the supplied 458 representation. A Broker MAY reject, or delay responses to, PUT 459 requests to a topic while pending resolution of notifications to 460 subscribers from previous PUT requests. 462 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 463 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 464 to a topic that does not exist, the Broker MUST create the topic 465 using the information in the PUT operation. The Broker MUST create a 466 topic with the URI-Path of the request, including all of the sub- 467 topics necessary, and create a topic link with the ct attribute set 468 to the content-format of the payload of the PUT request. If topic is 469 created, the Broker MUST return the response "2.01 Created" with the 470 URI of the created topic, including all of the created path segments, 471 returned via the Location-Path option. 473 A Broker MAY accept PUBLISH operations using the POST method. If a 474 broker accepts PUBLISH using POST it shall respond with the 2.04 475 Changed status code. 477 A Broker MAY perform garbage collection of stored representations 478 which have been delivered to all subscribers or which have timed out. 479 A Broker MAY retain at least one most recently published 480 representation to return in response to SUBSRCIBE and READ requests. 482 A Broker MUST make a best-effort attempt to notify all clients 483 subscribed on a particular topic each time it receives a publish on 484 that topic. An example is shown in Figure 10. If a client publishes 485 to a broker with the Max-Age option, the broker MUST include the same 486 value for the Max-Age option in all notifications. A broker MUST use 487 CoAP Notification as described in [RFC7641] to notify subscribed 488 clients. 490 The PUBLISH interface is specified as follows: 492 Interaction: Client -> Broker 494 Method: PUT, POST 496 URI Template: {+ps}/{+topic}{?q*} 498 URI Template Variables: ps := pubsub REST API entry point 499 (optional). The entry point of the pubsub REST API, as obtained 500 from discovery, used to discover topics. 502 topic := The desired topic to return links for (optional). 504 q := Query Filter (optional). MAY contain a query filter list as 505 per [RFC6690] Section 4.1. 507 Content-Format: Any valid CoAP content format 509 Payload: Representation of the topic value (CoAP resource state 510 representation) in the indicated content format 512 The following response codes are defined for this interface: 514 Success: 2.01 "Created". Successful publish, topic is created 516 Success: 2.04 "Changed". Successful publish, topic is updated 518 Failure: 4.00 "Bad Request". Malformed request. 520 Failure: 4.01 "Unauthorized". Authorization failure. 522 Failure: 4.04 "Not Found". Topic does not exist. 524 Failure: 4.29 "Too Many Requests". The client should slow down the 525 rate of publish messages for this topic (see Section 7). 527 Figure 8 shows an example of a new value being successfully published 528 to the topic "topic1". See Figure 10 for an example of a broker 529 forwarding a message from a publishing client to a subscribed client. 531 Client Broker 532 | | 533 | ---------- PUT /ps/topic1 "1033.3" --------> | 534 | | 535 | | 536 | <--------------- 2.04 Changed---------------- | 537 | | 539 Figure 8: Example of PUBLISH 541 Client Broker 542 | | 543 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 544 | | 545 | | 546 | <--------------- 2.01 Created---------------- | 547 | Location: /ps/exa/mpl/e | 548 | | 550 Figure 9: Example of CREATE on PUBLISH 552 4.4. SUBSCRIBE 554 A CoAP pubsub broker MAY allow Clients to subscribe to topics on the 555 Broker using CoAP Observe as described in [RFC7641]. A CoAP pubsub 556 Client wishing to Subscribe to a topic on a broker MUST use a CoAP 557 GET with the Observe option set to 0 (zero). The Broker MAY add the 558 client to a list of observers. The Broker MUST return a response 559 code of "2.05 Content" along with the most recently published value 560 if the topic contains a valid value and the broker can supply the 561 requested content format. The broker MUST reject Subscribe requests 562 on a topic if the content format of the request is not supported by 563 the content format the topic was created with. The broker MAY accept 564 Subscribe requests which specify content formats that the broker can 565 supply as alternate content formats to the content format the topic 566 was registered with. If the topic was published with the Max-Age 567 option, the broker MUST set the Max-Age option in the valid response 568 to the amount of time remaining for the value to be valid since the 569 last publish operation on that topic. The Broker MUST return a 570 response code of "2.07 No Content" if the Max-Age of the previously 571 stored value has expired. The Broker MUST return a response code 572 "4.04 Not Found" if the topic does not exist or has been removed. 573 The Broker MUST return a response code "4.15 Unsupported Content 574 Format" if it can not return the requested content format. If a 575 Broker is unable to accept a new Subscription on a topic, it SHOULD 576 return the appropriate response code without the Observe option as 577 per as per [RFC7641] Section 4.1. There is no explicit maximum 578 lifetime of a Subscription, thus a Broker may remove subscribers at 579 any time. The Broker, upon removing a Subscriber, will transmit the 580 appropriate response code without the Observe option, as per 581 [RFC7641] Section 4.2, to the removed Subscriber. 583 The SUBSCRIBE interface is specified as follows: 585 Interaction: Client -> Broker 587 Method: GET 589 Options: Observe:0 591 URI Template: {+ps}/{+topic}{?q*} 593 URI Template Variables: ps := pubsub REST API entry point 594 (optional). The entry point of the pubsub REST API, as obtained 595 from discovery, used to discover topics. 597 topic := The desired topic to return links for (optional). 599 q := Query Filter (optional). MAY contain a query filter list as 600 per [RFC6690] Section 4.1. 602 The following response codes are defined for this interface: 604 Success: 2.05 "Content". Successful subscribe, current value 605 included 607 Success: 2.07 "No Content". Successful subscribe, value not 608 included 610 Failure: 4.00 "Bad Request". Malformed request. 612 Failure: 4.01 "Unauthorized". Authorization failure. 614 Failure: 4.04 "Not Found". Topic does not exist. 616 Failure: 4.15 "Unsupported Content Format". Unsupported content 617 format. 619 Figure 10 shows an example of Client2 subscribing to "topic1" and 620 receiving a response from the broker, with a subsequent notification. 621 The subscribe response from the broker uses the last stored value 622 associated with the topic1. The notification from the broker is sent 623 in response to the publish received from Client1. 625 Client1 Client2 Broker 626 | | Subscribe | 627 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 628 | | | 629 | | <---------- 2.05 Content Observe:10---------- | 630 | | | 631 | | | 632 | | Publish | 633 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 634 | | Notify | 635 | | <---------- 2.05 Content Observe:11 --------- | 636 | | | 638 Figure 10: Example of SUBSCRIBE 640 4.5. UNSUBSCRIBE 642 If a CoAP pubsub broker allows clients to SUBSCRIBE to topics on the 643 broker, it MUST allow Clients to unsubscribe from topics on the 644 Broker using the CoAP Cancel Observation operation. A CoAP pubsub 645 Client wishing to unsubscribe to a topic on a Broker MUST either use 646 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 647 Reset message in response to a publish, as per [RFC7641]. 649 The UNSUBSCRIBE interface is specified as follows: 651 Interaction: Client -> Broker 653 Method: GET 655 Options: Observe:1 657 URI Template: {+ps}/{+topic}{?q*} 659 URI Template Variables: ps := pubsub REST API entry point 660 (optional). The entry point of the pubsub REST API, as obtained 661 from discovery, used to discover topics. 663 topic := The desired topic to return links for (optional). 665 q := Query Filter (optional). MAY contain a query filter list as 666 per [RFC6690] Section 4.1. 668 The following response codes are defined for this interface: 670 Success: 2.05 "Content". Successful unsubscribe, current value 671 included 673 Success: 2.07 "No Content". Successful unsubscribe, value not 674 included 676 Failure: 4.00 "Bad Request". Malformed request. 678 Failure: 4.01 "Unauthorized". Authorization failure. 680 Failure: 4.04 "Not Found". Topic does not exist. 682 Figure 11 shows an example of a client unsubscribe using the 683 Observe=1 cancellation method. 685 Client Broker 686 | | 687 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 688 | | 689 | <------------- 2.05 Content ----------------- | 690 | | 692 Figure 11: Example of UNSUBSCRIBE 694 4.6. READ 696 A CoAP pubsub broker MAY accept Read requests on a topic using the 697 the CoAP GET method if the content format of the request matches the 698 content format the topic was created with. The broker MAY accept 699 Read requests which specify content formats that the broker can 700 supply as alternate content formats to the content format the topic 701 was registered with. The Broker MUST return a response code of "2.05 702 Content" along with the most recently published value if the topic 703 contains a valid value and the broker can supply the requested 704 content format. If the topic was published with the Max-Age option, 705 the broker MUST set the Max-Age option in the valid response to the 706 amount of time remaining for the topic to be valid since the last 707 publish. The Broker MUST return a response code of "2.07 No Content" 708 if the Max-Age of the previously stored value has expired. The 709 Broker MUST return a response code "4.04 Not Found" if the topic does 710 not exist or has been removed. The Broker MUST return a response 711 code "4.15 Unsupported Content Format" if the broker can not return 712 the requested content format. 714 The READ interface is specified as follows: 716 Interaction: Client -> Broker 718 Method: GET 720 URI Template: {+ps}/{+topic}{?q*} 722 URI Template Variables: ps := pubsub REST API entry point 723 (optional). The entry point of the pubsub REST API, as obtained 724 from discovery, used to discover topics. 726 topic := The desired topic to return links for (optional). 728 q := Query Filter (optional). MAY contain a query filter list as 729 per [RFC6690] Section 4.1. 731 The following response codes are defined for this interface: 733 Success: 2.05 "Content". Successful READ, current value included 735 Success: 2.07 "No Content". Topic exists, value not included 737 Failure: 4.00 "Bad Request". Malformed request. 739 Failure: 4.01 "Unauthorized". Authorization failure. 741 Failure: 4.04 "Not Found". Topic does not exist. 743 Failure: 4.15 "Unsupported Content Format". Unsupported content- 744 format. 746 Figure 12 shows an example of a successful READ from topic1, followed 747 by a Publish on the topic, followed at some time later by a read of 748 the updated value from the recent Publish. 750 Client1 Client2 Broker 751 | | Read | 752 | | --------------- GET /ps/topic1 -------------> | 753 | | | 754 | | <---------- 2.05 Content "1007.1"------------ | 755 | | | 756 | | | 757 | | Publish | 758 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 759 | | | 760 | | | 761 | | Read | 762 | | --------------- GET /ps/topic1 -------------> | 763 | | | 764 | | <----------- 2.05 Content "1033.3" ---------- | 765 | | | 767 Figure 12: Example of READ 769 4.7. REMOVE 771 A CoAP pubsub broker MAY allow clientsremove a topics from the broker 772 using the CoAP Delete method on the URI of the topic. The CoAP 773 pubsub Broker MUST return "2.02 Deleted" if the removal is 774 successful. The broker MUST return the appropriate 4.xx response 775 code indicating the reason for failure if the topic can not be 776 removed. When a topic is removed for any reason, the Broker SHOULD 777 return the response code 4.04 Not Found and remove all of the 778 observers from the list of observers as per as per [RFC7641] 779 Section 3.2. If a topic which has sub-topics is removed, then all of 780 its sub-topics MUST be recursively removed. 782 The REMOVE interface is specified as follows: 784 Interaction: Client -> Broker 786 Method: DELETE 788 URI Template: {+ps}/{+topic}{?q*} 789 URI Template Variables: ps := pubsub REST API entry point 790 (optional). The entry point of the pubsub REST API, as obtained 791 from discovery, used to discover topics. 793 topic := The desired topic to return links for (optional). 795 q := Query Filter (optional). MAY contain a query filter list as 796 per [RFC6690] Section 4.1. 798 Content-Format: None 800 Response Payload: None 802 The following response codes are defined for this interface: 804 Success: 2.02 "Deleted". Successful remove 806 Failure: 4.00 "Bad Request". Malformed request. 808 Failure: 4.01 "Unauthorized". Authorization failure. 810 Failure: 4.04 "Not Found". Topic does not exist. 812 Figure 13 shows a successful remove of topic1. 814 Client Broker 815 | | 816 | ------------- DELETE /ps/topic1 ------------> | 817 | | 818 | | 819 | <-------------- 2.02 Deleted ---------------- | 820 | | 822 Figure 13: Example of REMOVE 824 5. CoAP pubsub Operation with Resource Directory 826 A CoAP pubsub Broker may register the base URI, which is the REST API 827 entry point for a pubsub service, with a Resource Directory. A 828 pubsub Client may use an RD to discover a pubsub Broker. 830 A CoAP pubsub Client may register links [RFC6690] with a Resource 831 Directory to enable discovery of created pubsub topics. A pubsub 832 Client may use an RD to discover pubsub Topics. A client which 833 registers pubsub Topics with an RD MUST use the context relation 834 (con) [I-D.ietf-core-resource-directory] to indicate that the context 835 of the registered links is the pubsub Broker. 837 A CoAP pubsub Broker may alternatively register links to its topics 838 to a Resource Directory by triggering the RD to retrieve it's links 839 from .well-known/core. In order to use this method, the links must 840 first be exposed in the .well-known/core of the pubsub broker. See 841 Section 4.1 in this document. 843 The pubsub broker triggers the RD to retrieve its links by sending a 844 POST with an empty payload to the .well-known/core of the Resource 845 Directory. The RD server will then retrieve the links from the 846 .well-known/core of the pubsub broker and incorporate them into the 847 Resource Directory. See [I-D.ietf-core-resource-directory] for 848 further details. 850 6. Sleep-Wake Operation 852 CoAP pubsub provides a way for client nodes to sleep between 853 operations, conserving energy during idle periods. This is made 854 possible by shifting the server role to the broker, allowing the 855 broker to be always-on and respond to requests from other clients 856 while a particular client is sleeping. 858 For example, the broker will retain the last state update received 859 from a sleeping client, in order to supply the most recent state 860 update to other clients in response to read and subscribe operations. 862 Likewise, the broker will retain the last state update received on 863 the topic such that a sleeping client, upon waking, can perform a 864 read operation to the broker to update its own state from the most 865 recent system state update. 867 7. Simple Flow Control 869 Since the broker node has to potentially send a large amount of 870 notification messages for each publish message and it may be serving 871 a large amount of subscribers and publishers simultaneously, the 872 broker may become overwhelmed if it receives many publish messages to 873 popular topics in a short period of time. 875 If the broker is unable to serve a certain client that is sending 876 publish messages too fast, the broker MUST respond with Response Code 877 4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too 878 Many Requests" but uses the Max-Age Option in place of the "Retry- 879 After" header field to indicate the number of seconds after which to 880 retry. The broker MAY stop creating notifications from the publish 881 messages from this client and to this topic for the indicated time. 883 If a client receives the 4.29 Response Code from the broker for a 884 publish message to a topic, it MUST NOT send new publish messages to 885 the broker on the same topic before the time indicated in Max-Age has 886 passed. 888 8. Security Considerations 890 CoAP pubsub re-uses CoAP [RFC7252], CoRE Resource Directory 891 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 892 therefore the security considerations of those documents also apply 893 to this specification. Additionally, a CoAP pubsub broker and the 894 clients SHOULD authenticate each other and enforce access control 895 policies. A malicious client could subscribe to data it is not 896 authorized to or mount a denial of service attack against the broker 897 by publishing a large number of resources. The authentication can be 898 performed using the already standardized DTLS offered mechanisms, 899 such as certificates. DTLS also allows communication security to be 900 established to ensure integrity and confidentiality protection of the 901 data exchanged between these relevant parties. Provisioning the 902 necessary credentials, trust anchors and authorization policies is 903 non-trivial and subject of ongoing work. 905 The use of a CoAP pubsub broker introduces challenges for the use of 906 end-to-end security between for example a client device on a sensor 907 network and a client application running in a cloud-based server 908 infrastructure since brokers terminate the exchange. While running 909 separate DTLS sessions from the client device to the broker and from 910 broker to client application protects confidentially on those paths, 911 the client device does not know whether the commands coming from the 912 broker are actually coming from the client application. Similarly, a 913 client application requesting data does not know whether the data 914 originated on the client device. For scenarios where end-to-end 915 security is desirable the use of application layer security is 916 unavoidable. Application layer security would then provide a 917 guarantee to the client device that any request originated at the 918 client application. Similarly, integrity protected sensor data from 919 a client device will also provide guarantee to the client application 920 that the data originated on the client device itself. The protected 921 data can also be verified by the intermediate broker ensuring that it 922 stores/caches correct request/response and no malicious messages/ 923 requests are accepted. The broker would still be able to perform 924 aggregation of data/requests collected. 926 Depending on the level of trust users and system designers place in 927 the CoAP pubsub broker, the use of end-to-end object security is 928 RECOMMENDED as described in [I-D.palombini-ace-coap-pubsub-profile]. 929 When only end-to-end encryption is necessary and the CoAP Broker is 930 trusted, Payload Only Protection (Mode:PAYL) could be used. The 931 Publisher would wrap only the payload before sending it to the broker 932 and set the option Content-Format to application/smpayl. Upon 933 receival, the Broker can read the unencrypted CoAP header to forward 934 it to the subscribers. 936 9. IANA Considerations 938 This document registers one attribute value in the Resource Type 939 (rt=) registry established with [RFC6690] and appends to the 940 definition of one CoAP Response Code in the CoRE Parameters Registry. 942 9.1. Resource Type value 'core.ps' 944 o Attribute Value: core.ps 946 o Description: Section 4 of [[This document]] 948 o Reference: [[This document]] 950 o Notes: None 952 9.2. Resource Type value 'core.ps.discover' 954 o Attribute Value: core.ps.discover 956 o Description: Section 4 of [[This document]] 958 o Reference: [[This document]] 960 o Notes: None 962 9.3. Response Code value '2.07' 964 o Response Code: 2.07 966 o Description: Add No Content response to GET to the existing 967 definition of the 2.07 response code. 969 o Reference: [[This document]] 971 o Notes: The server sends this code to the client to indicate that 972 the request was valid and accepted, but the responce may contain 973 an empty payload. It is comparable to and may be proxied with the 974 http 204 No Content status code. 976 9.4. Response Code value '4.29' 978 o Response Code: 4.29 979 o Description: This error code is used by a server to indicate that 980 a client is making too many requests on a resource. 982 o Reference: [[This document]] 984 o Notes: None 986 10. Acknowledgements 988 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 989 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 990 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 991 and reviews. 993 11. References 995 11.1. Normative References 997 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 998 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 999 RFC2119, March 1997, 1000 . 1002 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1003 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1004 3986, DOI 10.17487/RFC3986, January 2005, 1005 . 1007 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1008 and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/ 1009 RFC6570, March 2012, 1010 . 1012 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1013 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1014 . 1016 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1017 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1018 RFC7252, June 2014, 1019 . 1021 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1022 Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ 1023 RFC7641, September 2015, 1024 . 1026 11.2. Informative References 1028 [I-D.ietf-core-resource-directory] 1029 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1030 Resource Directory", draft-ietf-core-resource-directory-10 1031 (work in progress), March 2017. 1033 [I-D.palombini-ace-coap-pubsub-profile] 1034 Palombini, F., "CoAP Pub-Sub Profile for Authentication 1035 and Authorization for Constrained Environments (ACE)", 1036 draft-palombini-ace-coap-pubsub-profile-00 (work in 1037 progress), March 2017. 1039 [I-D.selander-ace-object-security] 1040 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1041 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 1042 object-security-06 (work in progress), October 2016. 1044 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 1045 RFC5988, October 2010, 1046 . 1048 Authors' Addresses 1050 Michael Koster 1051 SmartThings 1053 Email: Michael.Koster@smartthings.com 1055 Ari Keranen 1056 Ericsson 1058 Email: ari.keranen@ericsson.com 1060 Jaime Jimenez 1061 Ericsson 1063 Email: jaime.jimenez@ericsson.com