idnits 2.17.1 draft-ietf-core-coap-pubsub-09.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 (September 30, 2019) is 1663 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: 'RFC2119' is defined on line 1036, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-core-object-security' is defined on line 1072, but no explicit reference was found in the text == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-23 == Outdated reference: A later version (-06) exists of draft-palombini-ace-coap-pubsub-profile-05 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 7 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: April 2, 2020 J. Jimenez 6 Ericsson 7 September 30, 2019 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-09 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 There is work in progress to resolve some of the transfer layer 22 issues by using a more RESTful approach. 24 Please see https://github.com/core-wg/pubsub/blob/master/proposal.txt 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on April 2, 2020. 43 Copyright Notice 45 Copyright (c) 2019 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3.1. CoAP Pub/sub Architecture . . . . . . . . . . . . . . . . 4 64 3.2. CoAP Pub/sub Broker . . . . . . . . . . . . . . . . . . . 5 65 3.3. CoAP Pub/sub Client . . . . . . . . . . . . . . . . . . . 5 66 3.4. CoAP Pub/sub Topic . . . . . . . . . . . . . . . . . . . 5 67 3.5. Brokerless Pub/sub . . . . . . . . . . . . . . . . . . . 6 68 4. CoAP Pub/sub REST API . . . . . . . . . . . . . . . . . . . . 7 69 4.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 7 70 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 14 73 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 16 74 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 17 75 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 5. CoAP Pub/sub Operation with Resource Directory . . . . . . . 20 77 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 21 78 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 21 79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 80 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 81 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 23 82 9.2. Resource Type value 'core.ps.discover' . . . . . . . . . 23 83 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 84 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 85 11.1. Normative References . . . . . . . . . . . . . . . . . . 23 86 11.2. Informative References . . . . . . . . . . . . . . . . . 24 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 89 1. Introduction 91 The Constrained Application Protocol (CoAP) [RFC7252] supports 92 machine-to-machine communication across networks of constrained 93 devices. CoAP uses a request/response model where clients make 94 requests to servers in order to request actions on resources. 96 Depending on the situation the same device may act either as a 97 server, a client, or both. 99 One important class of constrained devices includes devices that are 100 intended to run for years from a small battery, or by scavenging 101 energy from their environment. These devices have limited 102 reachability because they spend most of their time in a sleeping 103 state with no network connectivity. Devices may also have limited 104 reachability due to certain middle-boxes, such as Network Address 105 Translators (NATs) or firewalls. Such middle-boxes often prevent 106 connecting to a device from the Internet unless the connection was 107 initiated by the device. 109 For some applications the client/server and request/response 110 communication model is not optimal but publish-subscribe 111 communication with potentially many senders and/or receivers and 112 communication via topics rather than directly with endpoints may fit 113 better. 115 This document specifies simple extensions to CoAP for enabling 116 publish-subscribe communication using a Broker node that enables 117 store-and-forward messaging between two or more nodes. This model 118 facilitates communication of nodes with limited reachability, enables 119 simple many-to-many communication, and eases integration with other 120 publish-subscribe systems. 122 2. Terminology 124 {::boilerplate bcp14} 126 This specification requires readers to be familiar with all the terms 127 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 128 should also be familiar with the terms and concepts discussed in 129 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 130 format [RFC6570] is used to describe the REST API defined in this 131 specification. 133 This specification makes use of the following additional terminology: 135 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 136 published to a Broker and potential receivers can subscribe to the 137 Broker to receive messages. The publishers do not (need to) know 138 where the message will be eventually sent: the publications and 139 subscriptions are matched by a Broker and publications are 140 delivered by the Broker to subscribed receivers. 142 CoAP pub/sub service: A group of REST resources, as defined in this 143 document, which together implement the required features of this 144 specification. 146 CoAP pub/sub Broker: A server node capable of receiving messages 147 (publications) from and sending messages to other nodes, and able 148 to match subscriptions and publications in order to route messages 149 to the right destinations. The Broker can also temporarily store 150 publications to satisfy future subscriptions and pending 151 notifications. 153 CoAP pub/sub Client: A CoAP client which is capable of publish or 154 subscribe operations as defined in this specification. 156 Topic: A unique identifier for a particular item being published 157 and/or subscribed to. A Broker uses the topics to match 158 subscriptions to publications. A reference to a Topic on a Broker 159 is a valid CoAP URI as defined in [RFC7252] 161 3. Architecture 163 3.1. CoAP Pub/sub Architecture 165 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 166 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 167 sub REST API which is hosted by the Broker. State information is 168 updated between the Clients and the Broker. The CoAP pub/sub Broker 169 performs a store-and-forward of state update representations between 170 certain CoAP pub/sub Clients. Clients Subscribe to topics upon which 171 representations are Published by other Clients, which are forwarded 172 by the Broker to the subscribing clients. A CoAP pub/sub Broker may 173 be used as a REST resource proxy, retaining the last published 174 representation to supply in response to Read requests from Clients. 176 Clients pub/sub Broker 177 +-------+ | 178 | CoAP | | 179 |pub/sub|---------|------+ 180 |Client | | | +-------+ 181 +-------+ | +----| CoAP | 182 | |pub/sub| 183 +-------+ | +----|Broker | 184 | CoAP | | | +-------+ 185 |pub/sub|---------|------+ 186 |Client | | 187 +-------+ | 189 Figure 1: CoAP pub/sub Architecture 191 3.2. CoAP Pub/sub Broker 193 A CoAP pub/sub Broker is a CoAP Server that exposes a REST API for 194 clients to use to initiate publish-subscribe interactions. Avoiding 195 the need for direct reachability between clients, the Broker only 196 needs to be reachable from all clients. The Broker also needs to 197 have sufficient resources (storage, bandwidth, etc.) to host CoAP 198 resource services, and potentially buffer messages, on behalf of the 199 clients. 201 3.3. CoAP Pub/sub Client 203 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 204 CoAP pub/sub REST API defined in this document. Clients initiate 205 interactions with a CoAP pub/sub Broker. A data source (e.g., sensor 206 clients) can publish state updates to the Broker and data sinks 207 (e.g., actuator clients) can read from or subscribe to state updates 208 from the Broker. Application clients can make use of both publish 209 and subscribe in order to exchange state updates with data sources 210 and data sinks. 212 3.4. CoAP Pub/sub Topic 214 The clients and Broker use topics to identify a particular resource 215 or object in a publish-subscribe system. Topics are conventionally 216 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 217 "/EP-33543/sen/3303/0/5700". The topics are hosted by a Broker and 218 all the clients using the Broker share the same namespace for topics. 220 Every CoAP pub/sub topic has an associated link, consisting of a 221 reference path on the Broker using URI path [RFC3986] construction 222 and link attributes [RFC6690]. Every topic is associated with zero 223 or more stored representations and a content-format specified in the 224 link. A CoAP pub/sub topic value may alternatively consist of a 225 collection of one or more sub-topics, consisting of links to the sub- 226 topic URIs and indicated by a link-format content-format. Sub-topics 227 are also topics and may have their own sub-topics, forming a tree 228 structure of unique paths that is implemented using URIs. The full 229 URI of a topic includes a scheme and authority for the Broker, for 230 example "coaps://192.0.2.13:5684/EP-33543/sen/3303/0/5700". 232 A Topic may have a lifetime defined by using the CoAP Max-Age option 233 on topic creation, or on publish operations to the topic. The 234 lifetime is refreshed each time a representation is published to the 235 topic. If the lifetime expires, the topic is removed from discovery 236 responses, returns errors on subscription, and any outstanding 237 subscriptions are cancelled. 239 3.5. Brokerless Pub/sub 241 In some use cases, it is desireable to use pub/sub semantics for 242 peer-to-peer communication, but it is not feasible or desireable to 243 include a separate node on the network to serve as a Broker. In 244 other use cases, it is desireable to enable one-way-only 245 communication, such as sensors pushing updates to a service. 247 Figure 2 shows an arrangement for using CoAP pub/sub in a 248 "Brokerless" configuration between peer nodes. Nodes in a Brokerless 249 system may act as both Broker and client. A node that supports 250 Broker functionality may be pre-configured with topics that expose 251 services and resources. Brokerless peer nodes can be mixed with 252 client and Broker nodes in a system with full interoperability. 254 Peer pub/sub Peer 255 +-------+ | +-------+ 256 | CoAP | | | CoAP | 257 |pub/sub|---------|---------|pub/sub| 258 |Client | | |Broker | 259 +-------+ | +-------+ 260 | CoAP | | | CoAP | 261 |pub/sub|---------|---------|pub/sub| 262 |Broker | | |Client | 263 +-------+ | +-------+ 265 Figure 2: Brokerless pub/sub 267 4. CoAP Pub/sub REST API 269 This section defines the REST API exposed by a CoAP pub/sub Broker to 270 pub/sub Clients. The examples throughout this section assume the use 271 of CoAP [RFC7252]. A CoAP pub/sub Broker implementing this 272 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 273 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 274 section. Optimized implementations MAY support a subset of the 275 operations as required by particular constrained use cases. 277 4.1. DISCOVERY 279 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 280 Simple Discovery or through a Resource Directory (RD) 281 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 282 indicate its presence and availability on a network by exposing a 283 link to the entry point of its pub/sub API at its .well-known/core 284 location [RFC6690]. A CoAP pub/sub Broker MAY register its pub/sub 285 REST API entry point with a Resource Directory. Figure 3 shows an 286 example of a client discovering a local pub/sub API using CoAP Simple 287 Discovery. A Broker wishing to advertise the CoAP pub/sub API for 288 Simple Discovery or through a Resource Directory MUST use the link 289 relation rt=core.ps. A Broker MAY advertise its supported content 290 formats and other attributes in the link to its pub/sub API. 292 A CoAP pub/sub Broker MAY offer a topic discovery entry point to 293 enable Clients to find topics of interest, either by topic name or by 294 link attributes which may be registered when the topic is created. 295 Figure 4 shows an example of a client looking for a topic with a 296 resource type (rt) of "temperature" using Discover. The client then 297 receives the URI of the resource and its content-format. A pub/sub 298 Broker wishing to advertise topic discovery MUST use the relation 299 rt=core.ps.discover in the link. 301 A CoAP pub/sub Broker MAY provide topic discovery functionality 302 through the .well-known/core resource. Links to topics may be 303 exposed at .well-known/core in addition to links to the pub/sub API. 304 Figure 5 shows an example of topic discovery through .well-known/ 305 core. 307 Topics in the broker may be created in hierarchies (see Section 4.2) 308 with parent topics having sub-topics. For a discovery the broker may 309 choose to not expose the sub-topics in order to limit amount of topic 310 links sent in a discovery response. The client can then perform 311 discovery for the parent topics it wants to discover the sub-topics. 313 The DISCOVER interface is specified as follows: 315 Interaction: Client -> Broker 317 Method: GET 319 URI Template: {+ps}/{+topic}{?q*} 321 URI Template Variables: ps := Pub/sub REST API entry point 322 (optional). The entry point of the pub/sub REST API, as obtained 323 from discovery, used to discover topics. 325 topic := The desired topic to return links for (optional). 327 q := Query Filter (optional). MAY contain a query filter list as 328 per [RFC6690] Section 4.1. 330 Content-Format: application/link-format 332 The following response codes are defined for the DISCOVER operation: 334 Success: 2.05 "Content" with an application/link-format payload 335 containing one or more matching entries for the Broker resource. 336 A pub/sub Broker SHOULD use the value "/ps/" for the base URI of 337 the pub/sub API wherever possible. 339 Failure: 4.04 "Not Found" is returned in case no matching entry is 340 found for a unicast request. 342 Failure: 4.00 "Bad Request" is returned in case of a malformed 343 request for a unicast request. 345 Failure: No error response to a multicast request. 347 Client Broker 348 | | 349 | ------ GET /.well-known/core?rt=core.ps ---->>| 350 | -- Content-Format: application/link-format ---| 351 | | 352 | <<--- 2.05 Content | 353 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 354 | | 356 Figure 3: Example of DISCOVER pub/sub function 358 Client Broker 359 | | 360 | ---------- GET /ps/?rt="temperature" ------->>| 361 | Content-Format: application/link-format | 362 | | 363 | <<-- 2.05 Content | 364 | ;rt="temperature";ct=50 ---| 365 | | 367 Figure 4: Example of DISCOVER topic 369 Client Broker 370 | | 371 | -------- GET /.well-known/core?ct=50 ------->>| 372 | Content-Format: application/link-format | 373 | | 374 | <<-- 2.05 Content | 375 | ;rt="temperature";ct=50 ---| 376 | | 378 Figure 5: Example of DISCOVER topic 380 4.2. CREATE 382 A CoAP pub/sub broker SHOULD allow Clients to create new topics on 383 the broker using CREATE. Some exceptions are for fixed brokerless 384 devices and pre-configured brokers in dedicated installations. A 385 client wishing to create a topic MUST use a CoAP POST to the pub/sub 386 API with a payload indicating the desired topic. The topic 387 specification sent in the payload MUST use a supported serialization 388 of the CoRE link format [RFC6690]. The target of the link MUST be a 389 URI formatted string. The client MUST indicate the desired content 390 format for publishes to the topic by using the ct (Content Format) 391 link attribute in the link-format payload. Additional link target 392 attributes and relation values MAY be included in the topic 393 specification link when a topic is created. 395 The client MAY indicate the lifetime of the topic by including the 396 Max-Age option in the CREATE request. 398 Topic hierarchies can be created by creating parent topics. A parent 399 topic is created with a POST using ct (Content Format) link attribute 400 value which describes a supported serialization of the CoRE link 401 format [RFC6690], such as application/link-format (ct=40) or its JSON 402 or CBOR serializations. If a topic is created which describes a link 403 serialization, that topic may then have sub-topics created under it 404 as shown in Figure 7. 406 Ony one level in the topic hierarchy may be created as a result of a 407 CREATE operation, unless create on PUBLISH is supported (see 408 Section 4.3). The topic string used in the link target MUST NOT 409 contain the "/" character. 411 A topic creator MUST include exactly one content format link 412 attribute value (ct) in the create payload. If the content format 413 option is not included or if the option is repeated, the Broker MUST 414 reject the operation with an error code of "4.00 Bad Request". 416 Only one topic may be created per request. If there is more than one 417 link included in a CREATE request, the Broker MUST reject the 418 operation with an error code of "4.00 Bad Request". 420 A Broker MUST return a response code of "2.01 Created" if the topic 421 is created and MUST return the URI path of the created topic via 422 Location-Path options. If a new topic can not be created, the Broker 423 MUST return the appropriate 4.xx response code indicating the reason 424 for failure. 426 A Broker SHOULD remove topics if the Max-Age of the topic is exceeded 427 without any publishes to the topic. A Broker SHOULD retain a topic 428 indefinitely if the Max-Age option is elided or is set to zero upon 429 topic creation. The lifetime of a topic MUST be refreshed upon 430 create operations with a target of an existing topic. 432 A topic creator SHOULD PUBLISH an initial value to a newly-created 433 Topic in order to enable responses to READ and SUBSCRIBE requests 434 that may be submitted after the topic is discoverable. 436 The CREATE interface is specified as follows: 438 Interaction: Client -> Broker 440 Method: POST 442 URI Template: {+ps}/{+topic} 444 URI Template Variables: ps := Pub/sub REST API entry point 445 (optional). The entry point of the pub/sub REST API, as obtained 446 from discovery, used to discover topics. 448 topic := The desired topic to return links for (optional). 450 Content-Format: application/link-format 451 Payload: The desired topic to CREATE 453 The following response codes are defined for the CREATE operation: 455 Success: 2.01 "Created". Successful Creation of the topic 457 Failure: 4.00 "Bad Request". Malformed request. 459 Failure: 4.01 "Unauthorized". Authorization failure. 461 Figure 6 shows an example of a topic called "topic1" being 462 successfully created. 464 Client Broker 465 | | 466 | ---------- POST /ps/ ";ct=50" ------->| 467 | | 468 | <---------------- 2.01 Created ---------------| 469 | Location: /ps/topic1 | 470 | | 472 Figure 6: Example of CREATE topic 474 Client Broker 475 | | 476 | ----- POST /ps/ ";ct=40" ------>| 477 | | 478 | <---------------- 2.01 Created ---------------| 479 | Location: /ps/parent-topic/ | 480 | | 481 |-- POST /ps/parent-topic/ ";ct=50" ->| 482 | | 483 | <---------------- 2.01 Created ---------------| 484 | Location: /ps/parent-topic/subtopic | 485 | | 486 | | 488 Figure 7: Example of CREATE of topic hierarchy 490 4.3. PUBLISH 492 A CoAP pub/sub Broker MAY allow clients to PUBLISH to topics on the 493 Broker. A client MAY use the PUT or the POST method to publish state 494 updates to the CoAP pub/sub Broker. A client MUST use the content 495 format specified upon creation of a given topic to publish updates to 496 that topic. The Broker MUST reject publish operations which do not 497 use the specified content format. A CoAP client publishing on a 498 topic MAY indicate the maximum lifetime of the value by including the 499 Max-Age option in the publish request. The Broker MUST return a 500 response code of "2.04 Changed" if the publish is accepted. A Broker 501 MAY return a "4.04 Not Found" if the topic does not exist. A Broker 502 MAY return "4.29 Too Many Requests" if simple flow control as 503 described in Section 7 is implemented. 505 A Broker MUST accept PUBLISH operations using the PUT method. 506 PUBLISH operations using the PUT method replace any stored 507 representation associated with the topic, with the supplied 508 representation. A Broker MAY reject, or delay responses to, PUT 509 requests to a topic while pending resolution of notifications to 510 subscribers from previous PUT requests. 512 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 513 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 514 to a topic that does not exist, the Broker MUST create the topic 515 using the information in the PUT operation. The Broker MUST create a 516 topic with the URI-Path of the request, including all of the sub- 517 topics necessary, and create a topic link with the ct attribute set 518 to the content-format value from the header of the PUT request. If 519 topic is created, the Broker MUST return the response "2.01 Created" 520 with the URI of the created topic, including all of the created path 521 segments, returned via the Location-Path option. 523 Figure 9 shows an example of a topic being created on first PUBLISH. 525 A Broker MAY accept PUBLISH operations using the POST method. If a 526 Broker accepts PUBLISH using POST it shall respond with the 2.04 527 Changed status code. If an attempt is made to PUBLISH using POST to 528 a topic that does not exist, the Broker SHALL return a response 529 status indicating resource not found, such as HTTP 404 or CoAP 4.04. 531 A Broker MAY perform garbage collection of stored representations 532 which have been delivered to all subscribers or which have timed out. 533 A Broker MAY retain at least one most recently published 534 representation to return in response to SUBSCRIBE and READ requests. 536 A Broker MUST make a best-effort attempt to notify all clients 537 subscribed on a particular topic each time it receives a publish on 538 that topic. An example is shown in Figure 10. 540 If a client publishes to a Broker without the Max-Age option, the 541 Broker MUST refresh the topic lifetime with the most recently set 542 Max-Age value, and the Broker MUST include the most recently set Max- 543 Age value in the Max-Age option of all notifications. 545 If a client publishes to a Broker with the Max-Age option, the Broker 546 MUST include the same value for the Max-Age option in all 547 notifications. 549 A Broker MUST use CoAP Notification as described in [RFC7641] to 550 notify subscribed clients. 552 The PUBLISH operation is specified as follows: 554 Interaction: Client -> Broker 556 Method: PUT, POST 558 URI Template: {+ps}/{+topic} 560 URI Template Variables: ps := Pub/sub REST API entry point 561 (optional). The entry point of the pub/sub REST API, as obtained 562 from discovery, used to discover topics. 564 topic := The desired topic to return links for (optional). 566 Content-Format: Any valid CoAP content format 568 Payload: Representation of the topic value (CoAP resource state 569 representation) in the indicated content format 571 The following response codes are defined for the PUBLISH operation: 573 Success: 2.01 "Created". Successful publish, topic is created 575 Success: 2.04 "Changed". Successful publish, topic is updated 577 Failure: 4.00 "Bad Request". Malformed request. 579 Failure: 4.01 "Unauthorized". Authorization failure. 581 Failure: 4.04 "Not Found". Topic does not exist. 583 Failure: 4.29 "Too Many Requests". The client should slow down the 584 rate of publish messages for this topic (see Section 7). 586 Figure 8 shows an example of a new value being successfully published 587 to the topic "topic1". See Figure 10 for an example of a Broker 588 forwarding a message from a publishing client to a subscribed client. 590 Client Broker 591 | | 592 | ---------- PUT /ps/topic1 "1033.3" --------> | 593 | | 594 | | 595 | <--------------- 2.04 Changed---------------- | 596 | | 598 Figure 8: Example of PUBLISH 600 Client Broker 601 | | 602 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 603 | | 604 | | 605 | <--------------- 2.01 Created---------------- | 606 | Location: /ps/exa/mpl/e | 607 | | 609 Figure 9: Example of CREATE on PUBLISH 611 4.4. SUBSCRIBE 613 A CoAP pub/sub Broker MAY allow Clients to subscribe to topics on the 614 Broker using CoAP Observe as described in [RFC7641]. A CoAP pub/sub 615 Client wishing to Subscribe to a topic on a Broker MUST use a CoAP 616 GET with the Observe option set to 0 (zero). The Broker MAY add the 617 client to a list of observers. The Broker MUST return a response 618 code of "2.05 Content" along with the most recently published value 619 if the topic contains a valid value and the Broker can supply the 620 requested content format. The Broker MUST reject Subscribe requests 621 on a topic if the content format of the request is not the content 622 format the topic was created with. 624 If the topic was published with the Max-Age option, the Broker MUST 625 set the Max-Age option in the valid response to the amount of time 626 remaining for the value to be valid since the last publish operation 627 on that topic. 629 The Broker MUST return a response code "4.04 Not Found" if the topic 630 does not exist or has been removed, or if Max-Age of a previously 631 published representation has expired. 633 If a Topic has been created but not yet published to when a SUBSCRIBE 634 to the topic is received, the Broker MAY acknowledge and queue the 635 pending SUBSCRIBE and defer the response until an initial PUBLISH 636 occurs. 638 The Broker MUST return a response code "4.15 Unsupported Content 639 Format" if it can not return the requested content format. If a 640 Broker is unable to accept a new Subscription on a topic, it SHOULD 641 return the appropriate response code without the Observe option as 642 per [RFC7641] Section 4.1. 644 There is no explicit maximum lifetime of a Subscription, thus a 645 Broker may remove subscribers at any time. The Broker, upon removing 646 a Subscriber, will transmit the appropriate response code without the 647 Observe option, as per [RFC7641] Section 4.2, to the removed 648 Subscriber. 650 The SUBSCRIBE operation is specified as follows: 652 Interaction: Client -> Broker 654 Method: GET 656 Options: Observe:0 658 URI Template: {+ps}/{+topic} 660 URI Template Variables: ps := Pub/sub REST API entry point 661 (optional). The entry point of the pub/sub REST API, as obtained 662 from discovery, used to discover topics. 664 topic := The desired topic to return links for (optional). 666 The following response codes are defined for the SUBSCRIBE operation: 668 Success: 2.05 "Content". Successful subscribe, current value 669 included 671 Failure: 4.00 "Bad Request". Malformed request. 673 Failure: 4.01 "Unauthorized". Authorization failure. 675 Failure: 4.04 "Not Found". Topic does not exist. 677 Failure: 4.15 "Unsupported Content Format". Unsupported content 678 format. 680 Figure 10 shows an example of Client2 subscribing to "topic1" and 681 receiving a response from the Broker, with a subsequent notification. 682 The subscribe response from the Broker uses the last stored value 683 associated with the topic1. The notification from the Broker is sent 684 in response to the publish received from Client1. 686 Client1 Client2 Broker 687 | | Subscribe | 688 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 689 | | | 690 | | <---------- 2.05 Content Observe:10---------- | 691 | | | 692 | | | 693 | | Publish | 694 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 695 | | Notify | 696 | | <---------- 2.05 Content Observe:11 --------- | 697 | | | 699 Figure 10: Example of SUBSCRIBE 701 4.5. UNSUBSCRIBE 703 If a CoAP pub/sub Broker allows clients to SUBSCRIBE to topics on the 704 Broker, it MUST allow Clients to unsubscribe from topics on the 705 Broker using the CoAP Cancel Observation operation. A CoAP pub/sub 706 Client wishing to unsubscribe to a topic on a Broker MUST either use 707 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 708 Reset message in response to a publish, as per [RFC7641]. 710 The UNSUBSCRIBE operation is specified as follows: 712 Interaction: Client -> Broker 714 Method: GET 716 Options: Observe:1 718 URI Template: {+ps}/{+topic}{?q*} 720 URI Template Variables: ps := Pub/sub REST API entry point 721 (optional). The entry point of the pub/sub REST API, as obtained 722 from discovery, used to discover topics. 724 topic := The desired topic to return links for (optional). 726 q := Query Filter (optional). MAY contain a query filter list as 727 per [RFC6690] Section 4.1. 729 The following response codes are defined for the UNSUBSCRIBE 730 operation: 732 Success: 2.05 "Content". Successful unsubscribe, current value 733 included 735 Success: 2.07 "No Content". Successful unsubscribe, value not 736 included 738 Failure: 4.00 "Bad Request". Malformed request. 740 Failure: 4.01 "Unauthorized". Authorization failure. 742 Failure: 4.04 "Not Found". Topic does not exist. 744 Figure 11 shows an example of a client unsubscribe using the 745 Observe=1 cancellation method. 747 Client Broker 748 | | 749 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 750 | | 751 | <------------- 2.05 Content ----------------- | 752 | | 754 Figure 11: Example of UNSUBSCRIBE 756 4.6. READ 758 A CoAP pub/sub Broker MAY accept Read requests on a topic using the 759 the CoAP GET method if the content format of the request matches the 760 content format the topic was created with. The Broker MUST return a 761 response code of "2.05 Content" along with the most recently 762 published value if the topic contains a valid value and the Broker 763 can supply the requested content format. 765 If the topic was published with the Max-Age option, the Broker MUST 766 set the Max-Age option in the valid response to the amount of time 767 remaining for the value to be valid since the last publish operation 768 on that topic. 770 The Broker MUST return a response code "4.04 Not Found" if the topic 771 does not exist or has been removed, or if Max-Age of a previously 772 published representation has expired. 774 If a Topic has been created but not yet published to when a READ to 775 the topic is received, the Broker MAY acknowledge and queue the 776 pending READ, and defer the response until an initial PUBLISH occurs. 778 The Broker MUST return a response code "4.15 Unsupported Content 779 Format" if the Broker can not return the requested content format. 781 The READ operation is specified as follows: 783 Interaction: Client -> Broker 785 Method: GET 787 URI Template: {+ps}/{+topic} 789 URI Template Variables: ps := Pub/sub REST API entry point 790 (optional). The entry point of the pub/sub REST API, as obtained 791 from discovery, used to discover topics. 793 topic := The desired topic to return links for (optional). 795 The following response codes are defined for the READ operation: 797 Success: 2.05 "Content". Successful READ, current value included 799 Failure: 4.00 "Bad Request". Malformed request. 801 Failure: 4.01 "Unauthorized". Authorization failure. 803 Failure: 4.04 "Not Found". Topic does not exist. 805 Failure: 4.15 "Unsupported Content Format". Unsupported content- 806 format. 808 Figure 12 shows an example of a successful READ from topic1, followed 809 by a Publish on the topic, followed at some time later by a read of 810 the updated value from the recent Publish. 812 Client1 Client2 Broker 813 | | Read | 814 | | --------------- GET /ps/topic1 -------------> | 815 | | | 816 | | <---------- 2.05 Content "1007.1"------------ | 817 | | | 818 | | | 819 | | Publish | 820 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 821 | | | 822 | | | 823 | | Read | 824 | | --------------- GET /ps/topic1 -------------> | 825 | | | 826 | | <----------- 2.05 Content "1033.3" ---------- | 827 | | | 829 Figure 12: Example of READ 831 4.7. REMOVE 833 A CoAP pub/sub Broker MAY allow clients to remove topics from the 834 Broker using the CoAP Delete method on the URI of the topic. The 835 CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is 836 successful. The Broker MUST return the appropriate 4.xx response 837 code indicating the reason for failure if the topic can not be 838 removed. 840 When a topic is removed for any reason, the Broker SHOULD remove all 841 of the observers from the list of observers and return a final 4.04 842 "Not Found" response as per [RFC7641] Section 3.2. If a topic which 843 has sub-topics is removed, then all of its sub-topics MUST be 844 recursively removed. 846 The REMOVE operation is specified as follows: 848 Interaction: Client -> Broker 850 Method: DELETE 852 URI Template: {+ps}/{+topic} 854 URI Template Variables: ps := Pub/sub REST API entry point 855 (optional). The entry point of the pub/sub REST API, as obtained 856 from discovery, used to discover topics. 858 topic := The desired topic to return links for (optional). 860 Content-Format: None 862 Response Payload: None 864 The following response codes are defined for the REMOVE operation: 866 Success: 2.02 "Deleted". Successful remove 868 Failure: 4.00 "Bad Request". Malformed request. 870 Failure: 4.01 "Unauthorized". Authorization failure. 872 Failure: 4.04 "Not Found". Topic does not exist. 874 Figure 13 shows a successful remove of topic1. 876 Client Broker 877 | | 878 | ------------- DELETE /ps/topic1 ------------> | 879 | | 880 | | 881 | <-------------- 2.02 Deleted ---------------- | 882 | | 884 Figure 13: Example of REMOVE 886 5. CoAP Pub/sub Operation with Resource Directory 888 A CoAP pub/sub Broker may register the base URI, which is the REST 889 API entry point for a pub/sub service, with a Resource Directory. A 890 pub/sub Client may use an RD to discover a pub/sub Broker. 892 A CoAP pub/sub Client may register links [RFC6690] with a Resource 893 Directory to enable discovery of created pub/sub topics. A pub/sub 894 Client may use an RD to discover pub/sub Topics. A client which 895 registers pub/sub Topics with an RD MUST use the context relation 896 (con) [I-D.ietf-core-resource-directory] to indicate that the context 897 of the registered links is the pub/sub Broker. 899 A CoAP pub/sub Broker may alternatively register links to its topics 900 to a Resource Directory by triggering the RD to retrieve it's links 901 from .well-known/core. In order to use this method, the links must 902 first be exposed in the .well-known/core of the pub/sub Broker. See 903 Section 4.1 in this document. 905 The pub/sub Broker triggers the RD to retrieve its links by sending a 906 POST with an empty payload to the .well-known/core of the Resource 907 Directory. The RD server will then retrieve the links from the 908 .well-known/core of the pub/sub Broker and incorporate them into the 909 Resource Directory. See [I-D.ietf-core-resource-directory] for 910 further details. 912 6. Sleep-Wake Operation 914 CoAP pub/sub provides a way for client nodes to sleep between 915 operations, conserving energy during idle periods. This is made 916 possible by shifting the server role to the Broker, allowing the 917 Broker to be always-on and respond to requests from other clients 918 while a particular client is sleeping. 920 For example, the Broker will retain the last state update received 921 from a sleeping client, in order to supply the most recent state 922 update to other clients in response to read and subscribe operations. 924 Likewise, the Broker will retain the last state update received on 925 the topic such that a sleeping client, upon waking, can perform a 926 read operation to the Broker to update its own state from the most 927 recent system state update. 929 7. Simple Flow Control 931 Since the Broker node has to potentially send a large amount of 932 notification messages for each publish message and it may be serving 933 a large amount of subscribers and publishers simultaneously, the 934 Broker may become overwhelmed if it receives many publish messages to 935 popular topics in a short period of time. 937 If the Broker is unable to serve a certain client that is sending 938 publish messages too fast, the Broker SHOULD respond with Response 939 Code 4.29, "Too Many Requests" [RFC8516] and set the Max-Age Option 940 to indicate the number of seconds after which the client can retry. 941 The Broker MAY stop creating notifications from the publish messages 942 from this client and to this topic for the indicated time. 944 If a client receives the 4.29 Response Code from the Broker for a 945 publish message to a topic, it MUST NOT send new publish messages to 946 the Broker on the same topic before the time indicated in Max-Age has 947 passed. 949 8. Security Considerations 951 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 952 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 953 therefore the security considerations of those documents also apply 954 to this specification. Additionally, a CoAP pub/sub Broker and the 955 clients SHOULD authenticate each other and enforce access control 956 policies. A malicious client could subscribe to data it is not 957 authorized to or mount a denial of service attack against the Broker 958 by publishing a large number of resources. The authentication can be 959 performed using the already standardized DTLS offered mechanisms, 960 such as certificates. DTLS also allows communication security to be 961 established to ensure integrity and confidentiality protection of the 962 data exchanged between these relevant parties. Provisioning the 963 necessary credentials, trust anchors and authorization policies is 964 non-trivial and subject of ongoing work. 966 The use of a CoAP pub/sub Broker introduces challenges for the use of 967 end-to-end security between for example a client device on a sensor 968 network and a client application running in a cloud-based server 969 infrastructure since Brokers terminate the exchange. While running 970 separate DTLS sessions from the client device to the Broker and from 971 Broker to client application protects confidentially on those paths, 972 the client device does not know whether the commands coming from the 973 Broker are actually coming from the client application. Similarly, a 974 client application requesting data does not know whether the data 975 originated on the client device. For scenarios where end-to-end 976 security is desirable the use of application layer security is 977 unavoidable. Application layer security would then provide a 978 guarantee to the client device that any request originated at the 979 client application. Similarly, integrity protected sensor data from 980 a client device will also provide guarantee to the client application 981 that the data originated on the client device itself. The protected 982 data can also be verified by the intermediate Broker ensuring that it 983 stores/caches correct request/response and no malicious messages/ 984 requests are accepted. The Broker would still be able to perform 985 aggregation of data/requests collected. 987 Depending on the level of trust users and system designers place in 988 the CoAP pub/sub Broker, the use of end-to-end object security is 989 RECOMMENDED as described in [I-D.palombini-ace-coap-pubsub-profile]. 990 An example application that uses the CoAP pub/sub Broker and relies 991 on end-to-end object security is described in [RFC8387]. When only 992 end-to-end encryption is necessary and the CoAP Broker is trusted, 993 Payload Only Protection (Mode:PAYL) could be used. The Publisher 994 would wrap only the payload before sending it to the Broker and set 995 the option Content-Format to application/smpayl. Upon receival, the 996 Broker can read the unencrypted CoAP header to forward it to the 997 subscribers. 999 9. IANA Considerations 1001 This document registers one attribute value in the Resource Type 1002 (rt=) registry established with [RFC6690] and appends to the 1003 definition of one CoAP Response Code in the CoRE Parameters Registry. 1005 9.1. Resource Type value 'core.ps' 1007 o Attribute Value: core.ps 1009 o Description: Section 4 of [[This document]] 1011 o Reference: [[This document]] 1013 o Notes: None 1015 9.2. Resource Type value 'core.ps.discover' 1017 o Attribute Value: core.ps.discover 1019 o Description: Section 4 of [[This document]] 1021 o Reference: [[This document]] 1023 o Notes: None 1025 10. Acknowledgements 1027 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 1028 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 1029 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 1030 and reviews. 1032 11. References 1034 11.1. Normative References 1036 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1037 Requirement Levels", BCP 14, RFC 2119, 1038 DOI 10.17487/RFC2119, March 1997, . 1041 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1042 Resource Identifier (URI): Generic Syntax", STD 66, 1043 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1044 . 1046 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1047 and D. Orchard, "URI Template", RFC 6570, 1048 DOI 10.17487/RFC6570, March 2012, . 1051 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1052 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1053 . 1055 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1056 Application Protocol (CoAP)", RFC 7252, 1057 DOI 10.17487/RFC7252, June 2014, . 1060 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1061 Application Protocol (CoAP)", RFC 7641, 1062 DOI 10.17487/RFC7641, September 2015, . 1065 [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the 1066 Constrained Application Protocol", RFC 8516, 1067 DOI 10.17487/RFC8516, January 2019, . 1070 11.2. Informative References 1072 [I-D.ietf-core-object-security] 1073 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1074 "Object Security for Constrained RESTful Environments 1075 (OSCORE)", draft-ietf-core-object-security-16 (work in 1076 progress), March 2019. 1078 [I-D.ietf-core-resource-directory] 1079 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1080 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1081 resource-directory-23 (work in progress), July 2019. 1083 [I-D.palombini-ace-coap-pubsub-profile] 1084 Palombini, F., "CoAP Pub-Sub Profile for Authentication 1085 and Authorization for Constrained Environments (ACE)", 1086 draft-palombini-ace-coap-pubsub-profile-05 (work in 1087 progress), July 2019. 1089 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1090 DOI 10.17487/RFC5988, October 2010, . 1093 [RFC8387] Sethi, M., Arkko, J., Keranen, A., and H. Back, "Practical 1094 Considerations and Implementation Experiences in Securing 1095 Smart Object Networks", RFC 8387, DOI 10.17487/RFC8387, 1096 May 2018, . 1098 Authors' Addresses 1100 Michael Koster 1101 SmartThings 1103 Email: Michael.Koster@smartthings.com 1105 Ari Keranen 1106 Ericsson 1108 Email: ari.keranen@ericsson.com 1110 Jaime Jimenez 1111 Ericsson 1113 Email: jaime.jimenez@ericsson.com