idnits 2.17.1 draft-ietf-core-coap-pubsub-08.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 date (March 11, 2019) is 1873 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.ietf-core-object-security' is defined on line 1073, but no explicit reference was found in the text == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-20 == Outdated reference: A later version (-06) exists of draft-palombini-ace-coap-pubsub-profile-03 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 5 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: September 12, 2019 J. Jimenez 6 Ericsson 7 March 11, 2019 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-08 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 https://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 September 13, 2019. 38 Copyright Notice 40 Copyright (c) 2019 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 (https://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 Pub/sub Architecture . . . . . . . . . . . . . . . . 4 59 3.2. CoAP Pub/sub Broker . . . . . . . . . . . . . . . . . . . 5 60 3.3. CoAP Pub/sub Client . . . . . . . . . . . . . . . . . . . 5 61 3.4. CoAP Pub/sub Topic . . . . . . . . . . . . . . . . . . . 5 62 3.5. Brokerless Pub/sub . . . . . . . . . . . . . . . . . . . 6 63 4. CoAP Pub/sub REST API . . . . . . . . . . . . . . . . . . . . 6 64 4.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 14 68 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 15 69 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 17 70 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 18 71 5. CoAP Pub/sub Operation with Resource Directory . . . . . . . 20 72 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 20 73 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 20 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 75 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 76 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 22 77 9.2. Resource Type value 'core.ps.discover' . . . . . . . . . 22 78 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 79 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 80 11.1. Normative References . . . . . . . . . . . . . . . . . . 23 81 11.2. Informative References . . . . . . . . . . . . . . . . . 24 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 84 1. Introduction 86 The Constrained Application Protocol (CoAP) [RFC7252] supports 87 machine-to-machine communication across networks of constrained 88 devices. CoAP uses a request/response model where clients make 89 requests to servers in order to request actions on resources. 90 Depending on the situation the same device may act either as a 91 server, a client, or both. 93 One important class of constrained devices includes devices that are 94 intended to run for years from a small battery, or by scavenging 95 energy from their environment. These devices have limited 96 reachability because they spend most of their time in a sleeping 97 state with no network connectivity. Devices may also have limited 98 reachability due to certain middle-boxes, such as Network Address 99 Translators (NATs) or firewalls. Such middle-boxes often prevent 100 connecting to a device from the Internet unless the connection was 101 initiated by the device. 103 For some applications the client/server and request/response 104 communication model is not optimal but publish-subscribe 105 communication with potentially many senders and/or receivers and 106 communication via topics rather than directly with endpoints may fit 107 better. 109 This document specifies simple extensions to CoAP for enabling 110 publish-subscribe communication using a Broker node that enables 111 store-and-forward messaging between two or more nodes. This model 112 facilitates communication of nodes with limited reachability, enables 113 simple many-to-many communication, and eases integration with other 114 publish-subscribe systems. 116 2. Terminology 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 120 "OPTIONAL" in this document are to be interpreted as described in 121 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 122 capitals, as shown here. 124 This specification requires readers to be familiar with all the terms 125 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 126 should also be familiar with the terms and concepts discussed in 127 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 128 format [RFC6570] is used to describe the REST API defined in this 129 specification. 131 This specification makes use of the following additional terminology: 133 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 134 published to a Broker and potential receivers can subscribe to the 135 Broker to receive messages. The publishers do not (need to) know 136 where the message will be eventually sent: the publications and 137 subscriptions are matched by a Broker and publications are 138 delivered by the Broker to subscribed receivers. 140 CoAP pub/sub service: A group of REST resources, as defined in this 141 document, which together implement the required features of this 142 specification. 144 CoAP pub/sub Broker: A server node capable of receiving messages 145 (publications) from and sending messages to other nodes, and able 146 to match subscriptions and publications in order to route messages 147 to the right destinations. The Broker can also temporarily store 148 publications to satisfy future subscriptions and pending 149 notifications. 151 CoAP pub/sub Client: A CoAP client which is capable of publish or 152 subscribe operations as defined in this specification. 154 Topic: A unique identifier for a particular item being published 155 and/or subscribed to. A Broker uses the topics to match 156 subscriptions to publications. A reference to a Topic on a Broker 157 is a valid CoAP URI as defined in [RFC7252] 159 3. Architecture 161 3.1. CoAP Pub/sub Architecture 163 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 164 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 165 sub REST API which is hosted by the Broker. State information is 166 updated between the Clients and the Broker. The CoAP pub/sub Broker 167 performs a store-and-forward of state update representations between 168 certain CoAP pub/sub Clients. Clients Subscribe to topics upon which 169 representations are Published by other Clients, which are forwarded 170 by the Broker to the subscribing clients. A CoAP pub/sub Broker may 171 be used as a REST resource proxy, retaining the last published 172 representation to supply in response to Read requests from Clients. 174 Clients pub/sub Broker 175 +-------+ | 176 | CoAP | | 177 |pub/sub|---------|------+ 178 |Client | | | +-------+ 179 +-------+ | +----| CoAP | 180 | |pub/sub| 181 +-------+ | +----|Broker | 182 | CoAP | | | +-------+ 183 |pub/sub|---------|------+ 184 |Client | | 185 +-------+ | 187 Figure 1: CoAP pub/sub Architecture 189 3.2. CoAP Pub/sub Broker 191 A CoAP pub/sub Broker is a CoAP Server that exposes a REST API for 192 clients to use to initiate publish-subscribe interactions. Avoiding 193 the need for direct reachability between clients, the Broker only 194 needs to be reachable from all clients. The Broker also needs to 195 have sufficient resources (storage, bandwidth, etc.) to host CoAP 196 resource services, and potentially buffer messages, on behalf of the 197 clients. 199 3.3. CoAP Pub/sub Client 201 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 202 CoAP pub/sub REST API defined in this document. Clients initiate 203 interactions with a CoAP pub/sub Broker. A data source (e.g., sensor 204 clients) can publish state updates to the Broker and data sinks 205 (e.g., actuator clients) can read from or subscribe to state updates 206 from the Broker. Application clients can make use of both publish 207 and subscribe in order to exchange state updates with data sources 208 and data sinks. 210 3.4. CoAP Pub/sub Topic 212 The clients and Broker use topics to identify a particular resource 213 or object in a publish-subscribe system. Topics are conventionally 214 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 215 "/EP-33543/sen/3303/0/5700". The topics are hosted by a Broker and 216 all the clients using the Broker share the same namespace for topics. 218 Every CoAP pub/sub topic has an associated link, consisting of a 219 reference path on the Broker using URI path [RFC3986] construction 220 and link attributes [RFC6690]. Every topic is associated with zero 221 or more stored representations and a content-format specified in the 222 link. A CoAP pub/sub topic value may alternatively consist of a 223 collection of one or more sub-topics, consisting of links to the sub- 224 topic URIs and indicated by a link-format content-format. Sub-topics 225 are also topics and may have their own sub-topics, forming a tree 226 structure of unique paths that is implemented using URIs. The full 227 URI of a topic includes a scheme and authority for the Broker, for 228 example "coaps://192.0.2.13:5684/EP-33543/sen/3303/0/5700". 230 A Topic may have a lifetime defined by using the CoAP Max-Age option 231 on topic creation, or on publish operations to the topic. The 232 lifetime is refreshed each time a representation is published to the 233 topic. If the lifetime expires, the topic is removed from discovery 234 responses, returns errors on subscription, and any outstanding 235 subscriptions are cancelled. 237 3.5. Brokerless Pub/sub 239 In some use cases, it is desireable to use pub/sub semantics for 240 peer-to-peer communication, but it is not feasible or desireable to 241 include a separate node on the network to serve as a Broker. In 242 other use cases, it is desireable to enable one-way-only 243 communication, such as sensors pushing updates to a service. 245 Figure 2 shows an arrangement for using CoAP pub/sub in a 246 "Brokerless" configuration between peer nodes. Nodes in a Brokerless 247 system may act as both Broker and client. A node that supports 248 Broker functionality may be pre-configured with topics that expose 249 services and resources. Brokerless peer nodes can be mixed with 250 client and Broker nodes in a system with full interoperability. 252 Peer pub/sub Peer 253 +-------+ | +-------+ 254 | CoAP | | | CoAP | 255 |pub/sub|---------|---------|pub/sub| 256 |Client | | |Broker | 257 +-------+ | +-------+ 258 | CoAP | | | CoAP | 259 |pub/sub|---------|---------|pub/sub| 260 |Broker | | |Client | 261 +-------+ | +-------+ 263 Figure 2: Brokerless pub/sub 265 4. CoAP Pub/sub REST API 267 This section defines the REST API exposed by a CoAP pub/sub Broker to 268 pub/sub Clients. The examples throughout this section assume the use 269 of CoAP [RFC7252]. A CoAP pub/sub Broker implementing this 270 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 271 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 272 section. Optimized implementations MAY support a subset of the 273 operations as required by particular constrained use cases. 275 4.1. DISCOVERY 277 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 278 Simple Discovery or through a Resource Directory (RD) 279 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 280 indicate its presence and availability on a network by exposing a 281 link to the entry point of its pub/sub API at its .well-known/core 282 location [RFC6690]. A CoAP pub/sub Broker MAY register its pub/sub 283 REST API entry point with a Resource Directory. Figure 3 shows an 284 example of a client discovering a local pub/sub API using CoAP Simple 285 Discovery. A Broker wishing to advertise the CoAP pub/sub API for 286 Simple Discovery or through a Resource Directory MUST use the link 287 relation rt=core.ps. A Broker MAY advertise its supported content 288 formats and other attributes in the link to its pub/sub API. 290 A CoAP pub/sub Broker MAY offer a topic discovery entry point to 291 enable Clients to find topics of interest, either by topic name or by 292 link attributes which may be registered when the topic is created. 293 Figure 4 shows an example of a client looking for a topic with a 294 resource type (rt) of "temperature" using Discover. The client then 295 receives the URI of the resource and its content-format. A pub/sub 296 Broker wishing to advertise topic discovery MUST use the relation 297 rt=core.ps.discover in the link. 299 A CoAP pub/sub Broker MAY provide topic discovery functionality 300 through the .well-known/core resource. Links to topics may be 301 exposed at .well-known/core in addition to links to the pub/sub API. 302 Figure 5 shows an example of topic discovery through .well-known/ 303 core. 305 Topics in the broker may be created in hierarchies (see Section 4.2) 306 with parent topics having sub-topics. For a discovery the broker may 307 choose to not expose the sub-topics in order to limit amount of topic 308 links sent in a discovery response. The client can then perform 309 discovery for the parent topics it wants to discover the sub-topics. 311 The DISCOVER interface is specified as follows: 313 Interaction: Client -> Broker 315 Method: GET 317 URI Template: {+ps}/{+topic}{?q*} 319 URI Template Variables: ps := Pub/sub REST API entry point 320 (optional). The entry point of the pub/sub REST API, as obtained 321 from discovery, used to discover topics. 323 topic := The desired topic to return links for (optional). 325 q := Query Filter (optional). MAY contain a query filter list as 326 per [RFC6690] Section 4.1. 328 Content-Format: application/link-format 330 The following response codes are defined for the DISCOVER operation: 332 Success: 2.05 "Content" with an application/link-format payload 333 containing one or more matching entries for the Broker resource. 334 A pub/sub Broker SHOULD use the value "/ps/" for the base URI of 335 the pub/sub API wherever possible. 337 Failure: 4.04 "Not Found" is returned in case no matching entry is 338 found for a unicast request. 340 Failure: 4.00 "Bad Request" is returned in case of a malformed 341 request for a unicast request. 343 Failure: No error response to a multicast request. 345 Client Broker 346 | | 347 | ------ GET /.well-known/core?rt=core.ps ---->>| 348 | -- Content-Format: application/link-format ---| 349 | | 350 | <<--- 2.05 Content | 351 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 352 | | 354 Figure 3: Example of DISCOVER pub/sub function 356 Client Broker 357 | | 358 | ---------- GET /ps/?rt="temperature" ------->>| 359 | Content-Format: application/link-format | 360 | | 361 | <<-- 2.05 Content | 362 | ;rt="temperature";ct=50 ---| 363 | | 365 Figure 4: Example of DISCOVER topic 367 Client Broker 368 | | 369 | -------- GET /.well-known/core?ct=50 ------->>| 370 | Content-Format: application/link-format | 371 | | 372 | <<-- 2.05 Content | 373 | ;rt="temperature";ct=50 ---| 374 | | 376 Figure 5: Example of DISCOVER topic 378 4.2. CREATE 380 A CoAP pub/sub broker SHOULD allow Clients to create new topics on 381 the broker using CREATE. Some exceptions are for fixed brokerless 382 devices and pre-configured brokers in dedicated installations. A 383 client wishing to create a topic MUST use a CoAP POST to the pub/sub 384 API with a payload indicating the desired topic. The topic 385 specification sent in the payload MUST use a supported serialization 386 of the CoRE link format [RFC6690]. The target of the link MUST be a 387 URI formatted string. The client MUST indicate the desired content 388 format for publishes to the topic by using the ct (Content Format) 389 link attribute in the link-format payload. Additional link target 390 attributes and relation values MAY be included in the topic 391 specification link when a topic is created. 393 The client MAY indicate the lifetime of the topic by including the 394 Max-Age option in the CREATE request. 396 Topic hierarchies can be created by creating parent topics. A parent 397 topic is created with a POST using ct (Content Format) link attribute 398 value which describes a supported serialization of the CoRE link 399 format [RFC6690], such as application/link-format (ct=40) or its JSON 400 or CBOR serializations. If a topic is created which describes a link 401 serialization, that topic may then have sub-topics created under it 402 as shown in Figure 7. 404 Ony one level in the topic hierarchy may be created as a result of a 405 CREATE operation, unless create on PUBLISH is supported (see 406 Section 4.3). The topic string used in the link target MUST NOT 407 contain the "/" character. 409 A topic creator MUST include exactly one content format link 410 attribute value (ct) in the create payload. If the content format 411 option is not included or if the option is repeated, the Broker MUST 412 reject the operation with an error code of "4.00 Bad Request". 414 Only one topic may be created per request. If there is more than one 415 link included in a CREATE request, the Broker MUST reject the 416 operation with an error code of "4.00 Bad Request". 418 A Broker MUST return a response code of "2.01 Created" if the topic 419 is created and MUST return the URI path of the created topic via 420 Location-Path options. If a new topic can not be created, the Broker 421 MUST return the appropriate 4.xx response code indicating the reason 422 for failure. 424 A Broker SHOULD remove topics if the Max-Age of the topic is exceeded 425 without any publishes to the topic. A Broker SHOULD retain a topic 426 indefinitely if the Max-Age option is elided or is set to zero upon 427 topic creation. The lifetime of a topic MUST be refreshed upon 428 create operations with a target of an existing topic. 430 A topic creator SHOULD PUBLISH an initial value to a newly-created 431 Topic in order to enable responses to READ and SUBSCRIBE requests 432 that may be submitted after the topic is discoverable. 434 The CREATE interface is specified as follows: 436 Interaction: Client -> Broker 438 Method: POST 440 URI Template: {+ps}/{+topic} 442 URI Template Variables: ps := Pub/sub REST API entry point 443 (optional). The entry point of the pub/sub REST API, as obtained 444 from discovery, used to discover topics. 446 topic := The desired topic to return links for (optional). 448 Content-Format: application/link-format 450 Payload: The desired topic to CREATE 452 The following response codes are defined for the CREATE operation: 454 Success: 2.01 "Created". Successful Creation of the topic 456 Failure: 4.00 "Bad Request". Malformed request. 458 Failure: 4.01 "Unauthorized". Authorization failure. 460 Figure 6 shows an example of a topic called "topic1" being 461 successfully created. 463 Client Broker 464 | | 465 | ---------- POST /ps/ ";ct=50" ------->| 466 | | 467 | <---------------- 2.01 Created ---------------| 468 | Location: /ps/topic1 | 469 | | 471 Figure 6: Example of CREATE topic 473 Client Broker 474 | | 475 | ----- POST /ps/ ";ct=40" ------>| 476 | | 477 | <---------------- 2.01 Created ---------------| 478 | Location: /ps/parent-topic/ | 479 | | 480 |-- POST /ps/parent-topic/ ";ct=50" ->| 481 | | 482 | <---------------- 2.01 Created ---------------| 483 | Location: /ps/parent-topic/subtopic | 484 | | 485 | | 487 Figure 7: Example of CREATE of topic hierarchy 489 4.3. PUBLISH 491 A CoAP pub/sub Broker MAY allow clients to PUBLISH to topics on the 492 Broker. A client MAY use the PUT or the POST method to publish state 493 updates to the CoAP pub/sub Broker. A client MUST use the content 494 format specified upon creation of a given topic to publish updates to 495 that topic. The Broker MUST reject publish operations which do not 496 use the specified content format. A CoAP client publishing on a 497 topic MAY indicate the maximum lifetime of the value by including the 498 Max-Age option in the publish request. The Broker MUST return a 499 response code of "2.04 Changed" if the publish is accepted. A Broker 500 MAY return a "4.04 Not Found" if the topic does not exist. A Broker 501 MAY return "4.29 Too Many Requests" if simple flow control as 502 described in Section 7 is implemented. 504 A Broker MUST accept PUBLISH operations using the PUT method. 505 PUBLISH operations using the PUT method replace any stored 506 representation associated with the topic, with the supplied 507 representation. A Broker MAY reject, or delay responses to, PUT 508 requests to a topic while pending resolution of notifications to 509 subscribers from previous PUT requests. 511 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 512 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 513 to a topic that does not exist, the Broker MUST create the topic 514 using the information in the PUT operation. The Broker MUST create a 515 topic with the URI-Path of the request, including all of the sub- 516 topics necessary, and create a topic link with the ct attribute set 517 to the content-format value from the header of the PUT request. If 518 topic is created, the Broker MUST return the response "2.01 Created" 519 with the URI of the created topic, including all of the created path 520 segments, returned via the Location-Path option. 522 Figure 9 shows an example of a topic being created on first PUBLISH. 524 A Broker MAY accept PUBLISH operations using the POST method. If a 525 Broker accepts PUBLISH using POST it shall respond with the 2.04 526 Changed status code. If an attempt is made to PUBLISH using POST to 527 a topic that does not exist, the Broker SHALL return a response 528 status indicating resource not found, such as HTTP 404 or CoAP 4.04. 530 A Broker MAY perform garbage collection of stored representations 531 which have been delivered to all subscribers or which have timed out. 532 A Broker MAY retain at least one most recently published 533 representation to return in response to SUBSCRIBE and READ requests. 535 A Broker MUST make a best-effort attempt to notify all clients 536 subscribed on a particular topic each time it receives a publish on 537 that topic. An example is shown in Figure 10. 539 If a client publishes to a Broker without the Max-Age option, the 540 Broker MUST refresh the topic lifetime with the most recently set 541 Max-Age value, and the Broker MUST include the most recently set Max- 542 Age value in the Max-Age option of all notifications. 544 If a client publishes to a Broker with the Max-Age option, the Broker 545 MUST include the same value for the Max-Age option in all 546 notifications. 548 A Broker MUST use CoAP Notification as described in [RFC7641] to 549 notify subscribed clients. 551 The PUBLISH operation is specified as follows: 553 Interaction: Client -> Broker 555 Method: PUT, POST 557 URI Template: {+ps}/{+topic} 559 URI Template Variables: ps := Pub/sub REST API entry point 560 (optional). The entry point of the pub/sub REST API, as obtained 561 from discovery, used to discover topics. 563 topic := The desired topic to return links for (optional). 565 Content-Format: Any valid CoAP content format 566 Payload: Representation of the topic value (CoAP resource state 567 representation) in the indicated content format 569 The following response codes are defined for the PUBLISH operation: 571 Success: 2.01 "Created". Successful publish, topic is created 573 Success: 2.04 "Changed". Successful publish, topic is updated 575 Failure: 4.00 "Bad Request". Malformed request. 577 Failure: 4.01 "Unauthorized". Authorization failure. 579 Failure: 4.04 "Not Found". Topic does not exist. 581 Failure: 4.29 "Too Many Requests". The client should slow down the 582 rate of publish messages for this topic (see Section 7). 584 Figure 8 shows an example of a new value being successfully published 585 to the topic "topic1". See Figure 10 for an example of a Broker 586 forwarding a message from a publishing client to a subscribed client. 588 Client Broker 589 | | 590 | ---------- PUT /ps/topic1 "1033.3" --------> | 591 | | 592 | | 593 | <--------------- 2.04 Changed---------------- | 594 | | 596 Figure 8: Example of PUBLISH 598 Client Broker 599 | | 600 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 601 | | 602 | | 603 | <--------------- 2.01 Created---------------- | 604 | Location: /ps/exa/mpl/e | 605 | | 607 Figure 9: Example of CREATE on PUBLISH 609 4.4. SUBSCRIBE 611 A CoAP pub/sub Broker MAY allow Clients to subscribe to topics on the 612 Broker using CoAP Observe as described in [RFC7641]. A CoAP pub/sub 613 Client wishing to Subscribe to a topic on a Broker MUST use a CoAP 614 GET with the Observe option set to 0 (zero). The Broker MAY add the 615 client to a list of observers. The Broker MUST return a response 616 code of "2.05 Content" along with the most recently published value 617 if the topic contains a valid value and the Broker can supply the 618 requested content format. The Broker MUST reject Subscribe requests 619 on a topic if the content format of the request is not the content 620 format the topic was created with. 622 If the topic was published with the Max-Age option, the Broker MUST 623 set the Max-Age option in the valid response to the amount of time 624 remaining for the value to be valid since the last publish operation 625 on that topic. 627 The Broker MUST return a response code "4.04 Not Found" if the topic 628 does not exist or has been removed, or if Max-Age of a previously 629 published representation has expired. 631 If a Topic has been created but not yet published to when a SUBSCRIBE 632 to the topic is received, the Broker MAY acknowledge and queue the 633 pending SUBSCRIBE and defer the response until an initial PUBLISH 634 occurs. 636 The Broker MUST return a response code "4.15 Unsupported Content 637 Format" if it can not return the requested content format. If a 638 Broker is unable to accept a new Subscription on a topic, it SHOULD 639 return the appropriate response code without the Observe option as 640 per [RFC7641] Section 4.1. 642 There is no explicit maximum lifetime of a Subscription, thus a 643 Broker may remove subscribers at any time. The Broker, upon removing 644 a Subscriber, will transmit the appropriate response code without the 645 Observe option, as per [RFC7641] Section 4.2, to the removed 646 Subscriber. 648 The SUBSCRIBE operation is specified as follows: 650 Interaction: Client -> Broker 652 Method: GET 654 Options: Observe:0 656 URI Template: {+ps}/{+topic} 657 URI Template Variables: ps := Pub/sub REST API entry point 658 (optional). The entry point of the pub/sub REST API, as obtained 659 from discovery, used to discover topics. 661 topic := The desired topic to return links for (optional). 663 The following response codes are defined for the SUBSCRIBE operation: 665 Success: 2.05 "Content". Successful subscribe, current value 666 included 668 Failure: 4.00 "Bad Request". Malformed request. 670 Failure: 4.01 "Unauthorized". Authorization failure. 672 Failure: 4.04 "Not Found". Topic does not exist. 674 Failure: 4.15 "Unsupported Content Format". Unsupported content 675 format. 677 Figure 10 shows an example of Client2 subscribing to "topic1" and 678 receiving a response from the Broker, with a subsequent notification. 679 The subscribe response from the Broker uses the last stored value 680 associated with the topic1. The notification from the Broker is sent 681 in response to the publish received from Client1. 683 Client1 Client2 Broker 684 | | Subscribe | 685 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 686 | | | 687 | | <---------- 2.05 Content Observe:10---------- | 688 | | | 689 | | | 690 | | Publish | 691 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 692 | | Notify | 693 | | <---------- 2.05 Content Observe:11 --------- | 694 | | | 696 Figure 10: Example of SUBSCRIBE 698 4.5. UNSUBSCRIBE 700 If a CoAP pub/sub Broker allows clients to SUBSCRIBE to topics on the 701 Broker, it MUST allow Clients to unsubscribe from topics on the 702 Broker using the CoAP Cancel Observation operation. A CoAP pub/sub 703 Client wishing to unsubscribe to a topic on a Broker MUST either use 704 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 705 Reset message in response to a publish, as per [RFC7641]. 707 The UNSUBSCRIBE operation is specified as follows: 709 Interaction: Client -> Broker 711 Method: GET 713 Options: Observe:1 715 URI Template: {+ps}/{+topic}{?q*} 717 URI Template Variables: ps := Pub/sub REST API entry point 718 (optional). The entry point of the pub/sub REST API, as obtained 719 from discovery, used to discover topics. 721 topic := The desired topic to return links for (optional). 723 q := Query Filter (optional). MAY contain a query filter list as 724 per [RFC6690] Section 4.1. 726 The following response codes are defined for the UNSUBSCRIBE 727 operation: 729 Success: 2.05 "Content". Successful unsubscribe, current value 730 included 732 Success: 2.07 "No Content". Successful unsubscribe, value not 733 included 735 Failure: 4.00 "Bad Request". Malformed request. 737 Failure: 4.01 "Unauthorized". Authorization failure. 739 Failure: 4.04 "Not Found". Topic does not exist. 741 Figure 11 shows an example of a client unsubscribe using the 742 Observe=1 cancellation method. 744 Client Broker 745 | | 746 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 747 | | 748 | <------------- 2.05 Content ----------------- | 749 | | 751 Figure 11: Example of UNSUBSCRIBE 753 4.6. READ 755 A CoAP pub/sub Broker MAY accept Read requests on a topic using the 756 the CoAP GET method if the content format of the request matches the 757 content format the topic was created with. The Broker MUST return a 758 response code of "2.05 Content" along with the most recently 759 published value if the topic contains a valid value and the Broker 760 can supply the requested content format. 762 If the topic was published with the Max-Age option, the Broker MUST 763 set the Max-Age option in the valid response to the amount of time 764 remaining for the value to be valid since the last publish operation 765 on that topic. 767 The Broker MUST return a response code "4.04 Not Found" if the topic 768 does not exist or has been removed, or if Max-Age of a previously 769 published representation has expired. 771 If a Topic has been created but not yet published to when a READ to 772 the topic is received, the Broker MAY acknowledge and queue the 773 pending READ, and defer the response until an initial PUBLISH occurs. 775 The Broker MUST return a response code "4.15 Unsupported Content 776 Format" if the Broker can not return the requested content format. 778 The READ operation is specified as follows: 780 Interaction: Client -> Broker 782 Method: GET 784 URI Template: {+ps}/{+topic} 786 URI Template Variables: ps := Pub/sub REST API entry point 787 (optional). The entry point of the pub/sub REST API, as obtained 788 from discovery, used to discover topics. 790 topic := The desired topic to return links for (optional). 792 The following response codes are defined for the READ operation: 794 Success: 2.05 "Content". Successful READ, current value included 796 Failure: 4.00 "Bad Request". Malformed request. 798 Failure: 4.01 "Unauthorized". Authorization failure. 800 Failure: 4.04 "Not Found". Topic does not exist. 802 Failure: 4.15 "Unsupported Content Format". Unsupported content- 803 format. 805 Figure 12 shows an example of a successful READ from topic1, followed 806 by a Publish on the topic, followed at some time later by a read of 807 the updated value from the recent Publish. 809 Client1 Client2 Broker 810 | | Read | 811 | | --------------- GET /ps/topic1 -------------> | 812 | | | 813 | | <---------- 2.05 Content "1007.1"------------ | 814 | | | 815 | | | 816 | | Publish | 817 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 818 | | | 819 | | | 820 | | Read | 821 | | --------------- GET /ps/topic1 -------------> | 822 | | | 823 | | <----------- 2.05 Content "1033.3" ---------- | 824 | | | 826 Figure 12: Example of READ 828 4.7. REMOVE 830 A CoAP pub/sub Broker MAY allow clients to remove topics from the 831 Broker using the CoAP Delete method on the URI of the topic. The 832 CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is 833 successful. The Broker MUST return the appropriate 4.xx response 834 code indicating the reason for failure if the topic can not be 835 removed. 837 When a topic is removed for any reason, the Broker SHOULD remove all 838 of the observers from the list of observers and return a final 4.04 839 "Not Found" response as per [RFC7641] Section 3.2. If a topic which 840 has sub-topics is removed, then all of its sub-topics MUST be 841 recursively removed. 843 The REMOVE operation is specified as follows: 845 Interaction: Client -> Broker 847 Method: DELETE 849 URI Template: {+ps}/{+topic} 851 URI Template Variables: ps := Pub/sub REST API entry point 852 (optional). The entry point of the pub/sub REST API, as obtained 853 from discovery, used to discover topics. 855 topic := The desired topic to return links for (optional). 857 Content-Format: None 859 Response Payload: None 861 The following response codes are defined for the REMOVE operation: 863 Success: 2.02 "Deleted". Successful remove 865 Failure: 4.00 "Bad Request". Malformed request. 867 Failure: 4.01 "Unauthorized". Authorization failure. 869 Failure: 4.04 "Not Found". Topic does not exist. 871 Figure 13 shows a successful remove of topic1. 873 Client Broker 874 | | 875 | ------------- DELETE /ps/topic1 ------------> | 876 | | 877 | | 878 | <-------------- 2.02 Deleted ---------------- | 879 | | 881 Figure 13: Example of REMOVE 883 5. CoAP Pub/sub Operation with Resource Directory 885 A CoAP pub/sub Broker may register the base URI, which is the REST 886 API entry point for a pub/sub service, with a Resource Directory. A 887 pub/sub Client may use an RD to discover a pub/sub Broker. 889 A CoAP pub/sub Client may register links [RFC6690] with a Resource 890 Directory to enable discovery of created pub/sub topics. A pub/sub 891 Client may use an RD to discover pub/sub Topics. A client which 892 registers pub/sub Topics with an RD MUST use the context relation 893 (con) [I-D.ietf-core-resource-directory] to indicate that the context 894 of the registered links is the pub/sub Broker. 896 A CoAP pub/sub Broker may alternatively register links to its topics 897 to a Resource Directory by triggering the RD to retrieve it's links 898 from .well-known/core. In order to use this method, the links must 899 first be exposed in the .well-known/core of the pub/sub Broker. See 900 Section 4.1 in this document. 902 The pub/sub Broker triggers the RD to retrieve its links by sending a 903 POST with an empty payload to the .well-known/core of the Resource 904 Directory. The RD server will then retrieve the links from the 905 .well-known/core of the pub/sub Broker and incorporate them into the 906 Resource Directory. See [I-D.ietf-core-resource-directory] for 907 further details. 909 6. Sleep-Wake Operation 911 CoAP pub/sub provides a way for client nodes to sleep between 912 operations, conserving energy during idle periods. This is made 913 possible by shifting the server role to the Broker, allowing the 914 Broker to be always-on and respond to requests from other clients 915 while a particular client is sleeping. 917 For example, the Broker will retain the last state update received 918 from a sleeping client, in order to supply the most recent state 919 update to other clients in response to read and subscribe operations. 921 Likewise, the Broker will retain the last state update received on 922 the topic such that a sleeping client, upon waking, can perform a 923 read operation to the Broker to update its own state from the most 924 recent system state update. 926 7. Simple Flow Control 928 Since the Broker node has to potentially send a large amount of 929 notification messages for each publish message and it may be serving 930 a large amount of subscribers and publishers simultaneously, the 931 Broker may become overwhelmed if it receives many publish messages to 932 popular topics in a short period of time. 934 If the Broker is unable to serve a certain client that is sending 935 publish messages too fast, the Broker SHOULD respond with Response 936 Code 4.29, "Too Many Requests" [RFC8516] and set the Max-Age Option 937 to indicate the number of seconds after which the client can retry. 938 The Broker MAY stop creating notifications from the publish messages 939 from this client and to this topic for the indicated time. 941 If a client receives the 4.29 Response Code from the Broker for a 942 publish message to a topic, it MUST NOT send new publish messages to 943 the Broker on the same topic before the time indicated in Max-Age has 944 passed. 946 8. Security Considerations 948 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 949 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 950 therefore the security considerations of those documents also apply 951 to this specification. Additionally, a CoAP pub/sub Broker and the 952 clients SHOULD authenticate each other and enforce access control 953 policies. A malicious client could subscribe to data it is not 954 authorized to or mount a denial of service attack against the Broker 955 by publishing a large number of resources. The authentication can be 956 performed using the already standardized DTLS offered mechanisms, 957 such as certificates. DTLS also allows communication security to be 958 established to ensure integrity and confidentiality protection of the 959 data exchanged between these relevant parties. Provisioning the 960 necessary credentials, trust anchors and authorization policies is 961 non-trivial and subject of ongoing work. 963 The use of a CoAP pub/sub Broker introduces challenges for the use of 964 end-to-end security between for example a client device on a sensor 965 network and a client application running in a cloud-based server 966 infrastructure since Brokers terminate the exchange. While running 967 separate DTLS sessions from the client device to the Broker and from 968 Broker to client application protects confidentially on those paths, 969 the client device does not know whether the commands coming from the 970 Broker are actually coming from the client application. Similarly, a 971 client application requesting data does not know whether the data 972 originated on the client device. For scenarios where end-to-end 973 security is desirable the use of application layer security is 974 unavoidable. Application layer security would then provide a 975 guarantee to the client device that any request originated at the 976 client application. Similarly, integrity protected sensor data from 977 a client device will also provide guarantee to the client application 978 that the data originated on the client device itself. The protected 979 data can also be verified by the intermediate Broker ensuring that it 980 stores/caches correct request/response and no malicious messages/ 981 requests are accepted. The Broker would still be able to perform 982 aggregation of data/requests collected. 984 Depending on the level of trust users and system designers place in 985 the CoAP pub/sub Broker, the use of end-to-end object security is 986 RECOMMENDED as described in [I-D.palombini-ace-coap-pubsub-profile]. 987 An example application that uses the CoAP pub/sub Broker and relies 988 on end-to-end object security is described in [RFC8387]. When only 989 end-to-end encryption is necessary and the CoAP Broker is trusted, 990 Payload Only Protection (Mode:PAYL) could be used. The Publisher 991 would wrap only the payload before sending it to the Broker and set 992 the option Content-Format to application/smpayl. Upon receival, the 993 Broker can read the unencrypted CoAP header to forward it to the 994 subscribers. 996 9. IANA Considerations 998 This document registers one attribute value in the Resource Type 999 (rt=) registry established with [RFC6690] and appends to the 1000 definition of one CoAP Response Code in the CoRE Parameters Registry. 1002 9.1. Resource Type value 'core.ps' 1004 o Attribute Value: core.ps 1006 o Description: Section 4 of [[This document]] 1008 o Reference: [[This document]] 1010 o Notes: None 1012 9.2. Resource Type value 'core.ps.discover' 1014 o Attribute Value: core.ps.discover 1016 o Description: Section 4 of [[This document]] 1018 o Reference: [[This document]] 1020 o Notes: None 1022 10. Acknowledgements 1024 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 1025 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 1026 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 1027 and reviews. 1029 11. References 1031 11.1. Normative References 1033 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1034 Requirement Levels", BCP 14, RFC 2119, 1035 DOI 10.17487/RFC2119, March 1997, 1036 . 1038 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1039 Resource Identifier (URI): Generic Syntax", STD 66, 1040 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1041 . 1043 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1044 and D. Orchard, "URI Template", RFC 6570, 1045 DOI 10.17487/RFC6570, March 2012, 1046 . 1048 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1049 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1050 . 1052 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1053 Application Protocol (CoAP)", RFC 7252, 1054 DOI 10.17487/RFC7252, June 2014, 1055 . 1057 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1058 Application Protocol (CoAP)", RFC 7641, 1059 DOI 10.17487/RFC7641, September 2015, 1060 . 1062 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1063 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1064 May 2017, . 1066 [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the 1067 Constrained Application Protocol", RFC 8516, 1068 DOI 10.17487/RFC8516, January 2019, 1069 . 1071 11.2. Informative References 1073 [I-D.ietf-core-object-security] 1074 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1075 "Object Security for Constrained RESTful Environments 1076 (OSCORE)", draft-ietf-core-object-security-16 (work in 1077 progress), March 2019. 1079 [I-D.ietf-core-resource-directory] 1080 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1081 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1082 resource-directory-20 (work in progress), March 2019. 1084 [I-D.palombini-ace-coap-pubsub-profile] 1085 Palombini, F., "CoAP Pub-Sub Profile for Authentication 1086 and Authorization for Constrained Environments (ACE)", 1087 draft-palombini-ace-coap-pubsub-profile-03 (work in 1088 progress), June 2018. 1090 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1091 DOI 10.17487/RFC5988, October 2010, 1092 . 1094 [RFC8387] Sethi, M., Arkko, J., Keranen, A., and H. Back, "Practical 1095 Considerations and Implementation Experiences in Securing 1096 Smart Object Networks", RFC 8387, DOI 10.17487/RFC8387, 1097 May 2018, . 1099 Authors' Addresses 1101 Michael Koster 1102 SmartThings 1104 Email: Michael.Koster@smartthings.com 1106 Ari Keranen 1107 Ericsson 1109 Email: ari.keranen@ericsson.com 1111 Jaime Jimenez 1112 Ericsson 1114 Email: jaime.jimenez@ericsson.com