idnits 2.17.1 draft-ietf-core-coap-pubsub-10.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 (4 May 2022) is 722 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-09) exists of draft-ietf-ace-pubsub-profile-04 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group M. Koster 3 Internet-Draft SmartThings 4 Intended status: Standards Track A. Keranen 5 Expires: 5 November 2022 J. Jimenez 6 Ericsson 7 4 May 2022 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-10 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 5 November 2022. 38 Copyright Notice 40 Copyright (c) 2022 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 (https://trustee.ietf.org/ 45 license-info) in effect on the date of publication of this document. 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. Code Components 48 extracted from this document must include Revised BSD License text as 49 described in Section 4.e of the Trust Legal Provisions and are 50 provided without warranty as described in the Revised BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 4. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4.1. CoAP Pub/sub Architecture . . . . . . . . . . . . . . . . 4 59 4.2. CoAP Pub/sub Broker . . . . . . . . . . . . . . . . . . . 5 60 4.3. CoAP Pub/sub Client . . . . . . . . . . . . . . . . . . . 5 61 4.4. CoAP Pub/sub Topic . . . . . . . . . . . . . . . . . . . 5 62 4.5. Brokerless Pub/sub . . . . . . . . . . . . . . . . . . . 6 63 5. CoAP Pub/sub REST API . . . . . . . . . . . . . . . . . . . . 7 64 5.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 7 65 5.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 5.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 5.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 14 68 5.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 16 69 5.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 17 70 5.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 18 71 6. CoAP Pub/sub Operation with Resource Directory . . . . . . . 20 72 7. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 20 73 8. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 21 74 9. Security Considerations . . . . . . . . . . . . . . . . . . . 21 75 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 76 10.1. Resource Type value 'core.ps' . . . . . . . . . . . . . 22 77 10.2. Resource Type value 'core.ps.discover' . . . . . . . . . 22 78 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 79 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 80 12.1. Normative References . . . . . . . . . . . . . . . . . . 23 81 12.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. Notational Conventions 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 3. Terminology 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 [RFC9176]. The URI template format [RFC6570] is used 130 to describe the REST API defined in this specification. 132 This specification makes use of the following additional terminology: 134 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 135 published to a Broker and potential receivers can subscribe to the 136 Broker to receive messages. The publishers do not (need to) know 137 where the message will be eventually sent: the publications and 138 subscriptions are matched by a Broker and publications are 139 delivered by the Broker to subscribed receivers. 141 CoAP pub/sub service: A group of REST resources, as defined in this 142 document, which together implement the required features of this 143 specification. 145 CoAP pub/sub Broker: A server node capable of receiving messages 146 (publications) from and sending messages to other nodes, and able 147 to match subscriptions and publications in order to route messages 148 to the right destinations. The Broker can also temporarily store 149 publications to satisfy future subscriptions and pending 150 notifications. 152 CoAP pub/sub Client: A CoAP client which is capable of publish or 153 subscribe operations as defined in this specification. 155 Topic: A unique identifier for a particular item being published 156 and/or subscribed to. A Broker uses the topics to match 157 subscriptions to publications. A reference to a Topic on a Broker 158 is a valid CoAP URI as defined in [RFC7252] 160 4. Architecture 162 4.1. CoAP Pub/sub Architecture 164 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 165 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 166 sub REST API which is hosted by the Broker. State information is 167 updated between the Clients and the Broker. The CoAP pub/sub Broker 168 performs a store-and-forward of state update representations between 169 certain CoAP pub/sub Clients. Clients Subscribe to topics upon which 170 representations are Published by other Clients, which are forwarded 171 by the Broker to the subscribing clients. A CoAP pub/sub Broker may 172 be used as a REST resource proxy, retaining the last published 173 representation to supply in response to Read requests from Clients. 175 Clients pub/sub Broker 176 +-------+ | 177 | CoAP | | 178 |pub/sub|---------|------+ 179 |Client | | | +-------+ 180 +-------+ | +----| CoAP | 181 | |pub/sub| 182 +-------+ | +----|Broker | 183 | CoAP | | | +-------+ 184 |pub/sub|---------|------+ 185 |Client | | 186 +-------+ | 188 Figure 1: CoAP pub/sub Architecture 190 4.2. CoAP Pub/sub Broker 192 A CoAP pub/sub Broker is a CoAP Server that exposes a REST API for 193 clients to use to initiate publish-subscribe interactions. Avoiding 194 the need for direct reachability between clients, the Broker only 195 needs to be reachable from all clients. The Broker also needs to 196 have sufficient resources (storage, bandwidth, etc.) to host CoAP 197 resource services, and potentially buffer messages, on behalf of the 198 clients. 200 4.3. CoAP Pub/sub Client 202 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 203 CoAP pub/sub REST API defined in this document. Clients initiate 204 interactions with a CoAP pub/sub Broker. A data source (e.g., sensor 205 clients) can publish state updates to the Broker and data sinks 206 (e.g., actuator clients) can read from or subscribe to state updates 207 from the Broker. Application clients can make use of both publish 208 and subscribe in order to exchange state updates with data sources 209 and data sinks. 211 4.4. CoAP Pub/sub Topic 213 The clients and Broker use topics to identify a particular resource 214 or object in a publish-subscribe system. Topics are conventionally 215 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 216 "/EP-33543/sen/3303/0/5700". The topics are hosted by a Broker and 217 all the clients using the Broker share the same namespace for topics. 219 Every CoAP pub/sub topic has an associated link, consisting of a 220 reference path on the Broker using URI path [RFC3986] construction 221 and link attributes [RFC6690]. Every topic is associated with zero 222 or more stored representations and a content-format specified in the 223 link. A CoAP pub/sub topic value may alternatively consist of a 224 collection of one or more sub-topics, consisting of links to the sub- 225 topic URIs and indicated by a link-format content-format. Sub-topics 226 are also topics and may have their own sub-topics, forming a tree 227 structure of unique paths that is implemented using URIs. The full 228 URI of a topic includes a scheme and authority for the Broker, for 229 example "coaps://192.0.2.13:5684/EP-33543/sen/3303/0/5700". 231 A Topic may have a lifetime defined by using the CoAP Max-Age option 232 on topic creation, or on publish operations to the topic. The 233 lifetime is refreshed each time a representation is published to the 234 topic. If the lifetime expires, the topic is removed from discovery 235 responses, returns errors on subscription, and any outstanding 236 subscriptions are cancelled. 238 4.5. Brokerless Pub/sub 240 In some use cases, it is desireable to use pub/sub semantics for 241 peer-to-peer communication, but it is not feasible or desireable to 242 include a separate node on the network to serve as a Broker. In 243 other use cases, it is desireable to enable one-way-only 244 communication, such as sensors pushing updates to a service. 246 Figure 2 shows an arrangement for using CoAP pub/sub in a 247 "Brokerless" configuration between peer nodes. Nodes in a Brokerless 248 system may act as both Broker and client. A node that supports 249 Broker functionality may be pre-configured with topics that expose 250 services and resources. Brokerless peer nodes can be mixed with 251 client and Broker nodes in a system with full interoperability. 253 Peer pub/sub Peer 254 +-------+ | +-------+ 255 | CoAP | | | CoAP | 256 |pub/sub|---------|---------|pub/sub| 257 |Client | | |Broker | 258 +-------+ | +-------+ 259 | CoAP | | | CoAP | 260 |pub/sub|---------|---------|pub/sub| 261 |Broker | | |Client | 262 +-------+ | +-------+ 264 Figure 2: Brokerless pub/sub 266 5. CoAP Pub/sub REST API 268 This section defines the REST API exposed by a CoAP pub/sub Broker to 269 pub/sub Clients. The examples throughout this section assume the use 270 of CoAP [RFC7252]. A CoAP pub/sub Broker implementing this 271 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 272 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 273 section. Optimized implementations MAY support a subset of the 274 operations as required by particular constrained use cases. 276 5.1. DISCOVERY 278 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 279 Simple Discovery or through a Resource Directory (RD) [RFC9176]. A 280 CoAP pub/sub Broker SHOULD indicate its presence and availability on 281 a network by exposing a link to the entry point of its pub/sub API at 282 its .well-known/core location [RFC6690]. A CoAP pub/sub Broker MAY 283 register its pub/sub REST API entry point with a Resource Directory. 284 Figure 3 shows an example of a client discovering a local pub/sub API 285 using CoAP Simple Discovery. A Broker wishing to advertise the CoAP 286 pub/sub API for Simple Discovery or through a Resource Directory MUST 287 use the link relation rt=core.ps. A Broker MAY advertise its 288 supported content formats and other attributes in the link to its 289 pub/sub API. 291 A CoAP pub/sub Broker MAY offer a topic discovery entry point to 292 enable Clients to find topics of interest, either by topic name or by 293 link attributes which may be registered when the topic is created. 294 Figure 4 shows an example of a client looking for a topic with a 295 resource type (rt) of "temperature" using Discover. The client then 296 receives the URI of the resource and its content-format. A pub/sub 297 Broker wishing to advertise topic discovery MUST use the relation 298 rt=core.ps.discover in the link. 300 A CoAP pub/sub Broker MAY provide topic discovery functionality 301 through the .well-known/core resource. Links to topics may be 302 exposed at .well-known/core in addition to links to the pub/sub API. 303 Figure 5 shows an example of topic discovery through .well-known/ 304 core. 306 Topics in the broker may be created in hierarchies (see Section 5.2) 307 with parent topics having sub-topics. For a discovery the broker may 308 choose to not expose the sub-topics in order to limit amount of topic 309 links sent in a discovery response. The client can then perform 310 discovery for the parent topics it wants to discover the sub-topics. 312 The DISCOVER interface is specified as follows: 314 Interaction: Client -> Broker 315 Method: GET 316 URI Template: {+ps}/{+topic}{?q\*} 317 URI Template Variables: 318 ps := Pub/sub REST API entry point (optional). 319 Entry point of the pub/sub topic discovery API. 320 topic := The desired topic to return links for (optional). 321 q := Query Filter (optional). 322 MAY contain a query filter list as per RFC6690 Section 4.1. 323 Content-Format: application/link-format 325 The following response codes are defined for the DISCOVER operation: 327 Success: 2.05 "Content" with an application/link-format payload 328 containing one or more matching entries for the Broker resource. 329 A pub/sub Broker SHOULD use the value "/ps/" for the base URI of 330 the pub/sub API wherever possible. 332 Failure: 4.04 "Not Found" is returned in case no matching entry is 333 found for a unicast request. 335 Failure: 4.00 "Bad Request" is returned in case of a malformed 336 request for a unicast request. 338 Failure: No error response to a multicast request. 340 Client Broker 341 | | 342 | ------ GET /.well-known/core?rt=core.ps ---->>| 343 | -- Content-Format: application/link-format ---| 344 | | 345 | <<--- 2.05 Content | 346 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 347 | | 349 Figure 3: Example of DISCOVER pub/sub function 351 Client Broker 352 | | 353 | ---------- GET /ps/?rt="temperature" ------->>| 354 | Content-Format: application/link-format | 355 | | 356 | <<-- 2.05 Content | 357 | ;rt="temperature";ct=50 ---| 358 | | 360 Figure 4: Example of DISCOVER topic 362 Client Broker 363 | | 364 | -------- GET /.well-known/core?ct=50 ------->>| 365 | Content-Format: application/link-format | 366 | | 367 | <<-- 2.05 Content | 368 | ;rt="temperature";ct=50 ---| 369 | | 371 Figure 5: Example of DISCOVER topic 373 5.2. CREATE 375 A CoAP pub/sub broker SHOULD allow Clients to create new topics on 376 the broker using CREATE. Some exceptions are for fixed brokerless 377 devices and pre-configured brokers in dedicated installations. A 378 client wishing to create a topic MUST use a CoAP POST to the pub/sub 379 API with a payload indicating the desired topic. The topic 380 specification sent in the payload MUST use a supported serialization 381 of the CoRE link format [RFC6690]. The target of the link MUST be a 382 URI formatted string. The client MUST indicate the desired content 383 format for publishes to the topic by using the ct (Content Format) 384 link attribute in the link-format payload. Additional link target 385 attributes and relation values MAY be included in the topic 386 specification link when a topic is created. 388 The client MAY indicate the lifetime of the topic by including the 389 Max-Age option in the CREATE request. 391 Topic hierarchies can be created by creating parent topics. A parent 392 topic is created with a POST using ct (Content Format) link attribute 393 value which describes a supported serialization of the CoRE link 394 format [RFC6690], such as application/link-format (ct=40) or its JSON 395 or CBOR serializations. If a topic is created which describes a link 396 serialization, that topic may then have sub-topics created under it 397 as shown in Figure 7. 399 Ony one level in the topic hierarchy may be created as a result of a 400 CREATE operation, unless create on PUBLISH is supported (see 401 Section 5.3). The topic string used in the link target MUST NOT 402 contain the "/" character. 404 A topic creator MUST include exactly one content format link 405 attribute value (ct) in the create payload. If the content format 406 option is not included or if the option is repeated, the Broker MUST 407 reject the operation with an error code of "4.00 Bad Request". 409 Only one topic may be created per request. If there is more than one 410 link included in a CREATE request, the Broker MUST reject the 411 operation with an error code of "4.00 Bad Request". 413 A Broker MUST return a response code of "2.01 Created" if the topic 414 is created and MUST return the URI path of the created topic via 415 Location-Path options. If a new topic can not be created, the Broker 416 MUST return the appropriate 4.xx response code indicating the reason 417 for failure. 419 A Broker SHOULD remove topics if the Max-Age of the topic is exceeded 420 without any publishes to the topic. A Broker SHOULD retain a topic 421 indefinitely if the Max-Age option is elided or is set to zero upon 422 topic creation. The lifetime of a topic MUST be refreshed upon 423 create operations with a target of an existing topic. 425 A topic creator SHOULD PUBLISH an initial value to a newly-created 426 Topic in order to enable responses to READ and SUBSCRIBE requests 427 that may be submitted after the topic is discoverable. 429 The CREATE interface is specified as follows: 431 Interaction: Client -> Broker 433 Method: POST 435 URI Template: {+ps}/{+topic} 437 URI Template Variables: ps := Pub/sub REST API entry point 438 (optional). The entry point of the pub/sub REST API, as obtained 439 from discovery, used to discover topics. 441 topic := The desired topic to return links for (optional). 443 Content-Format: application/link-format 445 Payload: The desired topic to CREATE 447 The following response codes are defined for the CREATE operation: 449 Success: 2.01 "Created". Successful Creation of the topic 451 Failure: 4.00 "Bad Request". Malformed request. 453 Failure: 4.01 "Unauthorized". Authorization failure. 455 Figure 6 shows an example of a topic called "topic1" being 456 successfully created. 458 Client Broker 459 | | 460 | ---------- POST /ps/ ";ct=50" ------->| 461 | | 462 | <---------------- 2.01 Created ---------------| 463 | Location: /ps/topic1 | 464 | | 466 Figure 6: Example of CREATE topic 468 Client Broker 469 | | 470 | ----- POST /ps/ ";ct=40" ------>| 471 | | 472 | <---------------- 2.01 Created ---------------| 473 | Location: /ps/parent-topic/ | 474 | | 475 |-- POST /ps/parent-topic/ ";ct=50" ->| 476 | | 477 | <---------------- 2.01 Created ---------------| 478 | Location: /ps/parent-topic/subtopic | 479 | | 480 | | 482 Figure 7: Example of CREATE of topic hierarchy 484 5.3. PUBLISH 486 A CoAP pub/sub Broker MAY allow clients to PUBLISH to topics on the 487 Broker. A client MAY use the PUT or the POST method to publish state 488 updates to the CoAP pub/sub Broker. A client MUST use the content 489 format specified upon creation of a given topic to publish updates to 490 that topic. The Broker MUST reject publish operations which do not 491 use the specified content format. A CoAP client publishing on a 492 topic MAY indicate the maximum lifetime of the value by including the 493 Max-Age option in the publish request. The Broker MUST return a 494 response code of "2.04 Changed" if the publish is accepted. A Broker 495 MAY return a "4.04 Not Found" if the topic does not exist. A Broker 496 MAY return "4.29 Too Many Requests" if simple flow control as 497 described in Section 8 is implemented. 499 A Broker MUST accept PUBLISH operations using the PUT method. 500 PUBLISH operations using the PUT method replace any stored 501 representation associated with the topic, with the supplied 502 representation. A Broker MAY reject, or delay responses to, PUT 503 requests to a topic while pending resolution of notifications to 504 subscribers from previous PUT requests. 506 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 507 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 508 to a topic that does not exist, the Broker MUST create the topic 509 using the information in the PUT operation. The Broker MUST create a 510 topic with the URI-Path of the request, including all of the sub- 511 topics necessary, and create a topic link with the ct attribute set 512 to the content-format value from the header of the PUT request. If 513 topic is created, the Broker MUST return the response "2.01 Created" 514 with the URI of the created topic, including all of the created path 515 segments, returned via the Location-Path option. 517 Figure 9 shows an example of a topic being created on first PUBLISH. 519 A Broker MAY accept PUBLISH operations using the POST method. If a 520 Broker accepts PUBLISH using POST it shall respond with the 2.04 521 Changed status code. If an attempt is made to PUBLISH using POST to 522 a topic that does not exist, the Broker SHALL return a response 523 status indicating resource not found, such as HTTP 404 or CoAP 4.04. 525 A Broker MAY perform garbage collection of stored representations 526 which have been delivered to all subscribers or which have timed out. 527 A Broker MAY retain at least one most recently published 528 representation to return in response to SUBSCRIBE and READ requests. 530 A Broker MUST make a best-effort attempt to notify all clients 531 subscribed on a particular topic each time it receives a publish on 532 that topic. An example is shown in Figure 10. 534 If a client publishes to a Broker without the Max-Age option, the 535 Broker MUST refresh the topic lifetime with the most recently set 536 Max-Age value, and the Broker MUST include the most recently set Max- 537 Age value in the Max-Age option of all notifications. 539 If a client publishes to a Broker with the Max-Age option, the Broker 540 MUST include the same value for the Max-Age option in all 541 notifications. 543 A Broker MUST use CoAP Notification as described in [RFC7641] to 544 notify subscribed clients. 546 The PUBLISH operation is specified as follows: 548 Interaction: Client -> Broker 550 Method: PUT, POST 552 URI Template: {+ps}/{+topic} 553 URI Template Variables: ps := Pub/sub REST API entry point 554 (optional). The entry point of the pub/sub REST API, as obtained 555 from discovery, used to discover topics. 557 topic := The desired topic to return links for (optional). 559 Content-Format: Any valid CoAP content format 561 Payload: Representation of the topic value (CoAP resource state 562 representation) in the indicated content format 564 The following response codes are defined for the PUBLISH operation: 566 Success: 2.01 "Created". Successful publish, topic is created 568 Success: 2.04 "Changed". Successful publish, topic is updated 570 Failure: 4.00 "Bad Request". Malformed request. 572 Failure: 4.01 "Unauthorized". Authorization failure. 574 Failure: 4.04 "Not Found". Topic does not exist. 576 Failure: 4.29 "Too Many Requests". The client should slow down the 577 rate of publish messages for this topic (see Section 8). 579 Figure 8 shows an example of a new value being successfully published 580 to the topic "topic1". See Figure 10 for an example of a Broker 581 forwarding a message from a publishing client to a subscribed client. 583 Client Broker 584 | | 585 | ---------- PUT /ps/topic1 "1033.3" --------> | 586 | | 587 | | 588 | <--------------- 2.04 Changed---------------- | 589 | | 591 Figure 8: Example of PUBLISH 593 Client Broker 594 | | 595 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 596 | | 597 | | 598 | <--------------- 2.01 Created---------------- | 599 | Location: /ps/exa/mpl/e | 600 | | 601 Figure 9: Example of CREATE on PUBLISH 603 5.4. SUBSCRIBE 605 A CoAP pub/sub Broker MAY allow Clients to subscribe to topics on the 606 Broker using CoAP Observe as described in [RFC7641]. A CoAP pub/sub 607 Client wishing to Subscribe to a topic on a Broker MUST use a CoAP 608 GET with the Observe option set to 0 (zero). The Broker MAY add the 609 client to a list of observers. The Broker MUST return a response 610 code of "2.05 Content" along with the most recently published value 611 if the topic contains a valid value and the Broker can supply the 612 requested content format. The Broker MUST reject Subscribe requests 613 on a topic if the content format of the request is not the content 614 format the topic was created with. 616 If the topic was published with the Max-Age option, the Broker MUST 617 set the Max-Age option in the valid response to the amount of time 618 remaining for the value to be valid since the last publish operation 619 on that topic. 621 The Broker MUST return a response code "4.04 Not Found" if the topic 622 does not exist or has been removed, or if Max-Age of a previously 623 published representation has expired. 625 If a Topic has been created but not yet published to when a SUBSCRIBE 626 to the topic is received, the Broker MAY acknowledge and queue the 627 pending SUBSCRIBE and defer the response until an initial PUBLISH 628 occurs. 630 The Broker MUST return a response code "4.15 Unsupported Content 631 Format" if it can not return the requested content format. If a 632 Broker is unable to accept a new Subscription on a topic, it SHOULD 633 return the appropriate response code without the Observe option as 634 per [RFC7641] Section 4.1. 636 There is no explicit maximum lifetime of a Subscription, thus a 637 Broker may remove subscribers at any time. The Broker, upon removing 638 a Subscriber, will transmit the appropriate response code without the 639 Observe option, as per [RFC7641] Section 4.2, to the removed 640 Subscriber. 642 The SUBSCRIBE operation is specified as follows: 644 Interaction: Client -> Broker 646 Method: GET 648 Options: Observe:0 649 URI Template: {+ps}/{+topic} 651 URI Template Variables: ps := Pub/sub REST API entry point 652 (optional). The entry point of the pub/sub REST API, as obtained 653 from discovery, used to discover topics. 655 topic := The desired topic to return links for (optional). 657 The following response codes are defined for the SUBSCRIBE operation: 659 Success: 2.05 "Content". Successful subscribe, current value 660 included 662 Failure: 4.00 "Bad Request". Malformed request. 664 Failure: 4.01 "Unauthorized". Authorization failure. 666 Failure: 4.04 "Not Found". Topic does not exist. 668 Failure: 4.15 "Unsupported Content Format". Unsupported content 669 format. 671 Figure 10 shows an example of Client2 subscribing to "topic1" and 672 receiving a response from the Broker, with a subsequent notification. 673 The subscribe response from the Broker uses the last stored value 674 associated with the topic1. The notification from the Broker is sent 675 in response to the publish received from Client1. 677 Client1 Client2 Broker 678 | | Subscribe | 679 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 680 | | | 681 | | <---------- 2.05 Content Observe:10---------- | 682 | | | 683 | | | 684 | | Publish | 685 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 686 | | Notify | 687 | | <---------- 2.05 Content Observe:11 --------- | 688 | | | 690 Figure 10: Example of SUBSCRIBE 692 5.5. UNSUBSCRIBE 694 If a CoAP pub/sub Broker allows clients to SUBSCRIBE to topics on the 695 Broker, it MUST allow Clients to unsubscribe from topics on the 696 Broker using the CoAP Cancel Observation operation. A CoAP pub/sub 697 Client wishing to unsubscribe to a topic on a Broker MUST either use 698 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 699 Reset message in response to a publish, as per [RFC7641]. 701 The UNSUBSCRIBE operation is specified as follows: 703 Interaction: Client -> Broker 705 Method: GET 707 Options: Observe:1 709 URI Template: {+ps}/{+topic}{?q*} 711 URI Template Variables: ps := Pub/sub REST API entry point 712 (optional). The entry point of the pub/sub REST API, as obtained 713 from discovery, used to discover topics. 715 topic := The desired topic to return links for (optional). 717 q := Query Filter (optional). MAY contain a query filter list as 718 per [RFC6690] Section 4.1. 720 The following response codes are defined for the UNSUBSCRIBE 721 operation: 723 Success: 2.05 "Content". Successful unsubscribe, current value 724 included 726 Success: 2.07 "No Content". Successful unsubscribe, value not 727 included 729 Failure: 4.00 "Bad Request". Malformed request. 731 Failure: 4.01 "Unauthorized". Authorization failure. 733 Failure: 4.04 "Not Found". Topic does not exist. 735 Figure 11 shows an example of a client unsubscribe using the 736 Observe=1 cancellation method. 738 Client Broker 739 | | 740 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 741 | | 742 | <------------- 2.05 Content ----------------- | 743 | | 745 Figure 11: Example of UNSUBSCRIBE 747 5.6. READ 749 A CoAP pub/sub Broker MAY accept Read requests on a topic using the 750 the CoAP GET method if the content format of the request matches the 751 content format the topic was created with. The Broker MUST return a 752 response code of "2.05 Content" along with the most recently 753 published value if the topic contains a valid value and the Broker 754 can supply the requested content format. 756 If the topic was published with the Max-Age option, the Broker MUST 757 set the Max-Age option in the valid response to the amount of time 758 remaining for the value to be valid since the last publish operation 759 on that topic. 761 The Broker MUST return a response code "4.04 Not Found" if the topic 762 does not exist or has been removed, or if Max-Age of a previously 763 published representation has expired. 765 If a Topic has been created but not yet published to when a READ to 766 the topic is received, the Broker MAY acknowledge and queue the 767 pending READ, and defer the response until an initial PUBLISH occurs. 769 The Broker MUST return a response code "4.15 Unsupported Content 770 Format" if the Broker can not return the requested content format. 772 The READ operation is specified as follows: 774 Interaction: Client -> Broker 776 Method: GET 778 URI Template: {+ps}/{+topic} 780 URI Template Variables: ps := Pub/sub REST API entry point 781 (optional). The entry point of the pub/sub REST API, as obtained 782 from discovery, used to discover topics. 784 topic := The desired topic to return links for (optional). 786 The following response codes are defined for the READ operation: 788 Success: 2.05 "Content". Successful READ, current value included 790 Failure: 4.00 "Bad Request". Malformed request. 792 Failure: 4.01 "Unauthorized". Authorization failure. 794 Failure: 4.04 "Not Found". Topic does not exist. 796 Failure: 4.15 "Unsupported Content Format". Unsupported content- 797 format. 799 Figure 12 shows an example of a successful READ from topic1, followed 800 by a Publish on the topic, followed at some time later by a read of 801 the updated value from the recent Publish. 803 Client1 Client2 Broker 804 | | Read | 805 | | --------------- GET /ps/topic1 -------------> | 806 | | | 807 | | <---------- 2.05 Content "1007.1"------------ | 808 | | | 809 | | | 810 | | Publish | 811 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 812 | | | 813 | | | 814 | | Read | 815 | | --------------- GET /ps/topic1 -------------> | 816 | | | 817 | | <----------- 2.05 Content "1033.3" ---------- | 818 | | | 820 Figure 12: Example of READ 822 5.7. REMOVE 824 A CoAP pub/sub Broker MAY allow clients to remove topics from the 825 Broker using the CoAP Delete method on the URI of the topic. The 826 CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is 827 successful. The Broker MUST return the appropriate 4.xx response 828 code indicating the reason for failure if the topic can not be 829 removed. 831 When a topic is removed for any reason, the Broker SHOULD remove all 832 of the observers from the list of observers and return a final 4.04 833 "Not Found" response as per [RFC7641] Section 3.2. If a topic which 834 has sub-topics is removed, then all of its sub-topics MUST be 835 recursively removed. 837 The REMOVE operation is specified as follows: 839 Interaction: Client -> Broker 841 Method: DELETE 843 URI Template: {+ps}/{+topic} 845 URI Template Variables: ps := Pub/sub REST API entry point 846 (optional). The entry point of the pub/sub REST API, as obtained 847 from discovery, used to discover topics. 849 topic := The desired topic to return links for (optional). 851 Content-Format: None 853 Response Payload: None 855 The following response codes are defined for the REMOVE operation: 857 Success: 2.02 "Deleted". Successful remove 859 Failure: 4.00 "Bad Request". Malformed request. 861 Failure: 4.01 "Unauthorized". Authorization failure. 863 Failure: 4.04 "Not Found". Topic does not exist. 865 Figure 13 shows a successful remove of topic1. 867 Client Broker 868 | | 869 | ------------- DELETE /ps/topic1 ------------> | 870 | | 871 | | 872 | <-------------- 2.02 Deleted ---------------- | 873 | | 875 Figure 13: Example of REMOVE 877 6. CoAP Pub/sub Operation with Resource Directory 879 A CoAP pub/sub Broker may register the base URI, which is the REST 880 API entry point for a pub/sub service, with a Resource Directory. A 881 pub/sub Client may use an RD to discover a pub/sub Broker. 883 A CoAP pub/sub Client may register links [RFC6690] with a Resource 884 Directory to enable discovery of created pub/sub topics. A pub/sub 885 Client may use an RD to discover pub/sub Topics. A client which 886 registers pub/sub Topics with an RD MUST use the context relation 887 (con) [RFC9176] to indicate that the context of the registered links 888 is the pub/sub Broker. 890 A CoAP pub/sub Broker may alternatively register links to its topics 891 to a Resource Directory by triggering the RD to retrieve it's links 892 from .well-known/core. In order to use this method, the links must 893 first be exposed in the .well-known/core of the pub/sub Broker. See 894 Section 5.1 in this document. 896 The pub/sub Broker triggers the RD to retrieve its links by sending a 897 POST with an empty payload to the .well-known/core of the Resource 898 Directory. The RD server will then retrieve the links from the 899 .well-known/core of the pub/sub Broker and incorporate them into the 900 Resource Directory. See [RFC9176] for further details. 902 7. Sleep-Wake Operation 904 CoAP pub/sub provides a way for client nodes to sleep between 905 operations, conserving energy during idle periods. This is made 906 possible by shifting the server role to the Broker, allowing the 907 Broker to be always-on and respond to requests from other clients 908 while a particular client is sleeping. 910 For example, the Broker will retain the last state update received 911 from a sleeping client, in order to supply the most recent state 912 update to other clients in response to read and subscribe operations. 914 Likewise, the Broker will retain the last state update received on 915 the topic such that a sleeping client, upon waking, can perform a 916 read operation to the Broker to update its own state from the most 917 recent system state update. 919 8. Simple Flow Control 921 Since the Broker node has to potentially send a large amount of 922 notification messages for each publish message and it may be serving 923 a large amount of subscribers and publishers simultaneously, the 924 Broker may become overwhelmed if it receives many publish messages to 925 popular topics in a short period of time. 927 If the Broker is unable to serve a certain client that is sending 928 publish messages too fast, the Broker SHOULD respond with Response 929 Code 4.29, "Too Many Requests" [RFC8516] and set the Max-Age Option 930 to indicate the number of seconds after which the client can retry. 931 The Broker MAY stop creating notifications from the publish messages 932 from this client and to this topic for the indicated time. 934 If a client receives the 4.29 Response Code from the Broker for a 935 publish message to a topic, it MUST NOT send new publish messages to 936 the Broker on the same topic before the time indicated in Max-Age has 937 passed. 939 9. Security Considerations 941 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 942 [RFC9176], and Web Linking [RFC5988] and therefore the security 943 considerations of those documents also apply to this specification. 944 Additionally, a CoAP pub/sub Broker and the clients SHOULD 945 authenticate each other and enforce access control policies. A 946 malicious client could subscribe to data it is not authorized to or 947 mount a denial of service attack against the Broker by publishing a 948 large number of resources. The authentication can be performed using 949 the already standardized DTLS offered mechanisms, such as 950 certificates. DTLS also allows communication security to be 951 established to ensure integrity and confidentiality protection of the 952 data exchanged between these relevant parties. Provisioning the 953 necessary credentials, trust anchors and authorization policies is 954 non-trivial and subject of ongoing work. 956 The use of a CoAP pub/sub Broker introduces challenges for the use of 957 end-to-end security between for example a client device on a sensor 958 network and a client application running in a cloud-based server 959 infrastructure since Brokers terminate the exchange. While running 960 separate DTLS sessions from the client device to the Broker and from 961 Broker to client application protects confidentially on those paths, 962 the client device does not know whether the commands coming from the 963 Broker are actually coming from the client application. Similarly, a 964 client application requesting data does not know whether the data 965 originated on the client device. For scenarios where end-to-end 966 security is desirable the use of application layer security is 967 unavoidable. Application layer security would then provide a 968 guarantee to the client device that any request originated at the 969 client application. Similarly, integrity protected sensor data from 970 a client device will also provide guarantee to the client application 971 that the data originated on the client device itself. The protected 972 data can also be verified by the intermediate Broker ensuring that it 973 stores/caches correct request/response and no malicious messages/ 974 requests are accepted. The Broker would still be able to perform 975 aggregation of data/requests collected. 977 Depending on the level of trust users and system designers place in 978 the CoAP pub/sub Broker, the use of end-to-end object security is 979 RECOMMENDED as described in [I-D.ietf-ace-pubsub-profile]. An 980 example application that uses the CoAP pub/sub Broker and relies on 981 end-to-end object security is described in [RFC8387]. When only end- 982 to-end encryption is necessary and the CoAP Broker is trusted, 983 Payload Only Protection (Mode:PAYL) could be used. The Publisher 984 would wrap only the payload before sending it to the Broker and set 985 the option Content-Format to application/smpayl. Upon receival, the 986 Broker can read the unencrypted CoAP header to forward it to the 987 subscribers. 989 10. IANA Considerations 991 This document registers one attribute value in the Resource Type 992 (rt=) registry established with [RFC6690] and appends to the 993 definition of one CoAP Response Code in the CoRE Parameters Registry. 995 10.1. Resource Type value 'core.ps' 997 * Attribute Value: core.ps 999 * Description: Section 5 of [[This document]] 1001 * Reference: [[This document]] 1003 * Notes: None 1005 10.2. Resource Type value 'core.ps.discover' 1007 * Attribute Value: core.ps.discover 1009 * Description: Section 5 of [[This document]] 1011 * Reference: [[This document]] 1013 * Notes: None 1015 11. Acknowledgements 1017 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 1018 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 1019 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 1020 and reviews. 1022 12. References 1024 12.1. Normative References 1026 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1027 Requirement Levels", BCP 14, RFC 2119, 1028 DOI 10.17487/RFC2119, March 1997, 1029 . 1031 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1032 Resource Identifier (URI): Generic Syntax", STD 66, 1033 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1034 . 1036 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1037 and D. Orchard, "URI Template", RFC 6570, 1038 DOI 10.17487/RFC6570, March 2012, 1039 . 1041 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1042 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1043 . 1045 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1046 Application Protocol (CoAP)", RFC 7252, 1047 DOI 10.17487/RFC7252, June 2014, 1048 . 1050 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1051 Application Protocol (CoAP)", RFC 7641, 1052 DOI 10.17487/RFC7641, September 2015, 1053 . 1055 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1056 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1057 May 2017, . 1059 [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the 1060 Constrained Application Protocol", RFC 8516, 1061 DOI 10.17487/RFC8516, January 2019, 1062 . 1064 [RFC9176] Amsuess, C., Ed., Shelby, Z., Koster, M., Bormann, C., and 1065 P. van der Stok, "Constrained RESTful Environments (CoRE) 1066 Resource Directory", RFC 9176, DOI 10.17487/RFC9176, April 1067 2022, . 1069 12.2. Informative References 1071 [I-D.ietf-ace-pubsub-profile] 1072 Palombini, F. and C. Sengul, "Pub-Sub Profile for 1073 Authentication and Authorization for Constrained 1074 Environments (ACE)", Work in Progress, Internet-Draft, 1075 draft-ietf-ace-pubsub-profile-04, 29 December 2021, 1076 . 1079 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1080 DOI 10.17487/RFC5988, October 2010, 1081 . 1083 [RFC8387] Sethi, M., Arkko, J., Keranen, A., and H. Back, "Practical 1084 Considerations and Implementation Experiences in Securing 1085 Smart Object Networks", RFC 8387, DOI 10.17487/RFC8387, 1086 May 2018, . 1088 Authors' Addresses 1090 Michael Koster 1091 SmartThings 1092 Email: Michael.Koster@smartthings.com 1094 Ari Keranen 1095 Ericsson 1096 Email: ari.keranen@ericsson.com 1098 Jaime Jimenez 1099 Ericsson 1100 Email: jaime.jimenez@ericsson.com