idnits 2.17.1 draft-ietf-core-coap-pubsub-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 3, 2019) is 1939 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 1063, but no explicit reference was found in the text == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-15 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-18 == 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 (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Koster 3 Internet-Draft SmartThings 4 Intended status: Standards Track A. Keranen 5 Expires: July 7, 2019 J. Jimenez 6 Ericsson 7 January 3, 2019 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-06 12 Abstract 14 The Constrained Application Protocol (CoAP), and related extensions 15 are intended to support machine-to-machine communication in systems 16 where one or more nodes are resource constrained, in particular for 17 low power wireless sensor networks. This document defines a publish- 18 subscribe Broker for CoAP that extends the capabilities of CoAP for 19 supporting nodes with long breaks in connectivity and/or up-time. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on July 7, 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 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.1. CoAP 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 . . . . . . . . . . . . . . . . . . . 5 63 4. CoAP Pub/sub REST API . . . . . . . . . . . . . . . . . . . . 6 64 4.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 15 69 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 18 71 5. CoAP Pub/sub Operation with Resource Directory . . . . . . . 19 72 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 20 73 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 20 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 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 9.3. Response Code value '2.07' . . . . . . . . . . . . . . . 22 79 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 80 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 81 11.1. Normative References . . . . . . . . . . . . . . . . . . 23 82 11.2. Informative References . . . . . . . . . . . . . . . . . 23 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 85 1. Introduction 87 The Constrained Application Protocol (CoAP) [RFC7252] supports 88 machine-to-machine communication across networks of constrained 89 devices. CoAP uses a request/response model where clients make 90 requests to servers in order to request actions on resources. 91 Depending on the situation the same device may act either as a 92 server, a client, or both. 94 One important class of constrained devices includes devices that are 95 intended to run for years from a small battery, or by scavenging 96 energy from their environment. These devices have limited 97 reachability because they spend most of their time in a sleeping 98 state with no network connectivity. Devices may also have limited 99 reachability due to certain middle-boxes, such as Network Address 100 Translators (NATs) or firewalls. Such middle-boxes often prevent 101 connecting to a device from the Internet unless the connection was 102 initiated by the device. 104 For some applications the client/server and request/response 105 communication model is not optimal but publish-subscribe 106 communication with potentially many senders and/or receivers and 107 communication via topics rather than directly with endpoints may fit 108 better. 110 This document specifies simple extensions to CoAP for enabling 111 publish-subscribe communication using a Broker node that enables 112 store-and-forward messaging between two or more nodes. This model 113 facilitates communication of nodes with limited reachability, enables 114 simple many-to-many communication, and eases integration with other 115 publish-subscribe systems. 117 2. Terminology 119 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 120 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 121 specification are to be interpreted as described in [RFC2119]. 123 This specification requires readers to be familiar with all the terms 124 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 125 should also be familiar with the terms and concepts discussed in 126 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 127 format [RFC6570] is used to describe the REST API defined in this 128 specification. 130 This specification makes use of the following additional terminology: 132 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 133 published to a Broker and potential receivers can subscribe to the 134 Broker to receive messages. The publishers do not (need to) know 135 where the message will be eventually sent: the publications and 136 subscriptions are matched by a Broker and publications are 137 delivered by the Broker to subscribed receivers. 139 CoAP pub/sub service: A group of REST resources, as defined in this 140 document, which together implement the required features of this 141 specification. 143 CoAP pub/sub Broker: A server node capable of receiving messages 144 (publications) from and sending messages to other nodes, and able 145 to match subscriptions and publications in order to route messages 146 to the right destinations. The Broker can also temporarily store 147 publications to satisfy future subscriptions and pending 148 notifications. 150 CoAP pub/sub Client: A CoAP client which is capable of publish or 151 subscribe operations as defined in this specification. 153 Topic: A unique identifier for a particular item being published 154 and/or subscribed to. A Broker uses the topics to match 155 subscriptions to publications. A topic is a valid CoAP URI as 156 defined in [RFC7252] 158 3. Architecture 160 3.1. CoAP Pub/sub Architecture 162 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 163 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 164 sub REST API which is hosted by the Broker. State information is 165 updated between the Clients and the Broker. The CoAP pub/sub Broker 166 performs a store-and-forward of state update representations between 167 certain CoAP pub/sub Clients. Clients Subscribe to topics upon which 168 representations are Published by other Clients, which are forwarded 169 by the Broker to the subscribing clients. A CoAP pub/sub Broker may 170 be used as a REST resource proxy, retaining the last published 171 representation to supply in response to Read requests from Clients. 173 Clients pub/sub Broker 174 +-------+ | 175 | CoAP | | 176 |pub/sub|---------|------+ 177 |Client | | | +-------+ 178 +-------+ | +----| CoAP | 179 | |pub/sub| 180 +-------+ | +----|Broker | 181 | CoAP | | | +-------+ 182 |pub/sub|---------|------+ 183 |Client | | 184 +-------+ | 186 Figure 1: CoAP pub/sub Architecture 188 3.2. CoAP Pub/sub Broker 190 A CoAP pub/sub Broker is a CoAP Server that exposes a REST API for 191 clients to use to initiate publish-subscribe interactions. Avoiding 192 the need for direct reachability between clients, the Broker only 193 needs to be reachable from all clients. The Broker also needs to 194 have sufficient resources (storage, bandwidth, etc.) to host CoAP 195 resource services, and potentially buffer messages, on behalf of the 196 clients. 198 3.3. CoAP Pub/sub Client 200 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 201 CoAP pub/sub REST API defined in this document. Clients initiate 202 interactions with a CoAP pub/sub Broker. A data source (e.g., sensor 203 clients) can publish state updates to the Broker and data sinks 204 (e.g., actuator clients) can read from or subscribe to state updates 205 from the Broker. Application clients can make use of both publish 206 and subscribe in order to exchange state updates with data sources 207 and data sinks. 209 3.4. CoAP Pub/sub Topic 211 The clients and Broker use topics to identify a particular resource 212 or object in a publish-subscribe system. Topics are conventionally 213 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 214 "/EP-33543/sen/3303/0/5700". The topics are hosted by a Broker and 215 all the clients using the Broker share the same namespace for topics. 216 Every CoAP pub/sub topic has an associated link, consisting of a 217 reference path on the Broker using URI path [RFC3986] construction 218 and link attributes [RFC6690]. Every topic is associated with zero 219 or more stored representations and a content-format specified in the 220 link. A CoAP pub/sub topic value may alternatively consist of a 221 collection of one or more sub-topics, consisting of links to the sub- 222 topic URIs and indicated by a link-format content-format. Sub-topics 223 are also topics and may have their own sub-topics, forming a tree 224 structure of unique paths that is implemented using URIs. The full 225 URI of a topic includes a scheme and authority for the Broker, for 226 example "coaps://10.0.0.13:5684/EP-33543/sen/3303/0/5700". 228 3.5. brokerless Pub/sub 230 Figure 2 shows an arrangement for using CoAP pub/sub in a 231 "Brokerless" configuration between peer nodes. Nodes in a Brokerless 232 system may act as both Broker and client. A node that supports 233 Broker functionality may be pre-configured with topics that expose 234 services and resources. Brokerless peer nodes can be mixed with 235 client and Broker nodes in a system with full interoperability. 237 Peer pub/sub Peer 238 +-------+ | +-------+ 239 | CoAP | | | CoAP | 240 |pub/sub|---------|---------|pub/sub| 241 |Client | | |Broker | 242 +-------+ | +-------+ 243 | CoAP | | | CoAP | 244 |pub/sub|---------|---------|pub/sub| 245 |Broker | | |Client | 246 +-------+ | +-------+ 248 Figure 2: Brokerless pub/sub 250 4. CoAP Pub/sub REST API 252 This section defines the REST API exposed by a CoAP pub/sub Broker to 253 pub/sub Clients. The examples throughout this section assume the use 254 of CoAP [RFC7252]. A CoAP pub/sub Broker implementing this 255 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 256 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 257 section. Optimized implementations MAY support a subset of the 258 operations as required by particular constrained use cases. 260 4.1. DISCOVERY 262 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 263 Simple Discovery or through a Resource Directory (RD) 264 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 265 indicate its presence and availability on a network by exposing a 266 link to the entry point of its pub/sub API at its .well-known/core 267 location [RFC6690]. A CoAP pub/sub Broker MAY register its pub/sub 268 REST API entry point with a Resource Directory. Figure 3 shows an 269 example of a client discovering a local pub/sub API using CoAP Simple 270 Discovery. A Broker wishing to advertise the CoAP pub/sub API for 271 Simple Discovery or through a Resource Directory MUST use the link 272 relation rt=core.ps. A Broker MAY advertise its supported content 273 formats and other attributes in the link to its pub/sub API. 275 A CoAP pub/sub Broker MAY offer a topic discovery entry point to 276 enable Clients to find topics of interest, either by topic name or by 277 link attributes which may be registered when the topic is created. 278 Figure 4 shows an example of a client looking for a topic with a 279 resource type (rt) of "temperature" using Discover. The client then 280 receives the URI of the resource and its content-format. A pub/sub 281 Broker wishing to advertise topic discovery MUST use the relation 282 rt=core.ps.discover in the link. 284 A CoAP pub/sub Broker MAY provide topic discovery functionality 285 through the .well-known/core resource. Links to topics may be 286 exposed at .well-known/core in addition to links to the pub/sub API. 287 Figure 5 shows an example of topic discovery through .well-known/ 288 core. 290 Topics in the broker may be created in hierarchies (see {create}) 291 with parent topics having sub-topics. For a discovery the broker may 292 choose to not expose the sub-topics in order to limit amount of topic 293 links sent in a discovery response. The client can then perform 294 discovery for the parent topics it wants to discover the sub-topics. 296 The DISCOVER interface is specified as follows: 298 Interaction: Client -> Broker 300 Method: GET 302 URI Template: {+ps}/{+topic}{?q*} 304 URI Template Variables: ps := Pub/sub REST API entry point 305 (optional). The entry point of the pub/sub REST API, as obtained 306 from discovery, used to discover topics. 308 topic := The desired topic to return links for (optional). 310 q := Query Filter (optional). MAY contain a query filter list as 311 per [RFC6690] Section 4.1. 313 Content-Format: application/link-format 315 The following response codes are defined for the DISCOVER operation: 317 Success: 2.05 "Content" with an application/link-format payload 318 containing one or more matching entries for the Broker resource. 319 A pub/sub Broker SHOULD use the value "/ps/" for the base URI of 320 the pub/sub API wherever possible. 322 Failure: 4.04 "Not Found" is returned in case no matching entry is 323 found for a unicast request. 325 Failure: 4.00 "Bad Request" is returned in case of a malformed 326 request for a unicast request. 328 Failure: No error response to a multicast request. 330 Client Broker 331 | | 332 | ------ GET /.well-known/core?rt=core.ps ---->>| 333 | -- Content-Format: application/link-format ---| 334 | | 335 | <<--- 2.05 Content | 336 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 337 | | 339 Figure 3: Example of DISCOVER pub/sub function 341 Client Broker 342 | | 343 | ---------- GET /ps/?rt="temperature" ------->>| 344 | Content-Format: application/link-format | 345 | | 346 | <<-- 2.05 Content | 347 | ;rt="temperature";ct=50 ---| 348 | | 350 Figure 4: Example of DISCOVER topic 352 Client Broker 353 | | 354 | -------- GET /.well-known/core?ct=50 ------->>| 355 | Content-Format: application/link-format | 356 | | 357 | <<-- 2.05 Content | 358 | ;rt="temperature";ct=50 ---| 359 | | 361 Figure 5: Example of DISCOVER topic 363 4.2. CREATE 365 A CoAP pub/sub broker SHOULD allow Clients to create new topics on 366 the broker using CREATE. Some exceptions are for fixed brokerless 367 devices and pre-configured brokers in dedicated installations. A 368 client wishing to create a topic MUST use a CoAP POST to the pub/sub 369 API with a payload indicating the desired topic. The topic 370 specification sent in the payload MUST use a supported serialization 371 of the CoRE link format [RFC6690]. The target of the link MUST be a 372 URI formatted string. The client MUST indicate the desired content 373 format for publishes to the topic by using the ct (Content Format) 374 link attribute in the link-format payload. Additional link target 375 attributes and relation values may be included in the topic 376 specification link whena topic is created. 378 The client MAY indicate the lifetime of the topic by including the 379 Max-Age option in the CREATE request. 381 Topic hierarchies can be created by creating parent topics. A parent 382 topic is created with a POST using ct (Content Format) link attribute 383 value which describes a supported serialization of the CoRE link 384 format [RFC6690], such as application/link-format (ct=40) or its JSON 385 or CBOR serializations. If a topic is created which describes a link 386 serialization, that topic may then have sub-topics created under it 387 as shown in Figure 7. 389 Ony one level in the topic hierarchy may be created as a result of a 390 CREATE operation, unless create on PUBLISH is supported (see 391 Section 4.3). The topic string used in the link target MUST NOT 392 contain the "/" character. 394 A topic creator MUST include exactly one content format link 395 attribute value (ct) in the create payload. If the Broker does not 396 support the indicated format for both publish and subscribe, or if 397 there is more than one "ct" value included in the request, the Broker 398 MUST reject the operation with an error code of 4.00 "Bad Request". 400 Only one topic may be created per request. If there is more than one 401 link included in a CREATE request, the Broker MUST reject the 402 operation with an erroro code of 4.00 "Bad Request". 404 There is no default content format. If no ct is specified, the 405 Broker MUST reject the operation with an error code of 4.00 "Bad 406 Request". 408 A Broker MUST return a response code of "2.01 Created" if the topic 409 is created and return the URI path of the created topic via Location- 410 Path options. The Broker MUST return the appropriate 4.xx response 411 code indicating the reason for failure if a new topic can not be 412 created. Broker SHOULD remove topics if the Max-Age of the topic is 413 exceeded without any publishes to the topic. Broker SHOULD retain a 414 topic indefinitely if the Max-Age option is elided or is set to zero 415 upon topic creation. The lifetime of a topic MUST be refreshed upon 416 create operations with a target of an existing topic. 418 The CREATE interface is specified as follows: 420 Interaction: Client -> Broker 422 Method: POST 423 URI Template: {+ps}/{+topic} 425 URI Template Variables: ps := Pub/sub REST API entry point 426 (optional). The entry point of the pub/sub REST API, as obtained 427 from discovery, used to discover topics. 429 topic := The desired topic to return links for (optional). 431 Content-Format: application/link-format 433 Payload: The desired topic to CREATE 435 The following response codes are defined for the CREATE operation: 437 Success: 2.01 "Created". Successful Creation of the topic 439 Failure: 4.00 "Bad Request". Malformed request. 441 Failure: 4.01 "Unauthorized". Authorization failure. 443 Failure: 4.03 "Forbidden". Topic already exists. 445 Failure: 4.06 "Not Acceptable". Unsupported content format for 446 topic. 448 Figure 6 shows an example of a topic called "topic1" being 449 successfully created. 451 Client Broker 452 | | 453 | ---------- POST /ps/ ";ct=50" ------->| 454 | | 455 | <---------------- 2.01 Created ---------------| 456 | Location: /ps/topic1 | 457 | | 459 Figure 6: Example of CREATE topic 461 Client Broker 462 | | 463 | ----- POST /ps/ ";ct=40" ------>| 464 | | 465 | <---------------- 2.01 Created ---------------| 466 | Location: /ps/parent-topic/ | 467 | | 468 |-- POST /ps/parent-topic/ ";ct=50" ->| 469 | | 470 | <---------------- 2.01 Created ---------------| 471 | Location: /ps/parent-topic/subtopic | 472 | | 473 | | 475 Figure 7: Example of CREATE of topic hierarchy 477 4.3. PUBLISH 479 A CoAP pub/sub Broker MAY allow clients to PUBLISH to topics on the 480 Broker. A client MAY use the PUT or the POST method to publish state 481 updates to the CoAP pub/sub Broker. A client MUST use the content 482 format specified upon creation of a given topic to publish updates to 483 that topic. The Broker MUST reject publish operations which do not 484 use the specified content format. A CoAP client publishing on a 485 topic MAY indicate the maximum lifetime of the value by including the 486 Max-Age option in the publish request. The Broker MUST return a 487 response code of "2.04 Changed" if the publish is accepted. A Broker 488 MAY return a "4.04 Not Found" if the topic does not exist. A Broker 489 MAY return "4.29 Too Many Requests" if simple flow control as 490 described in Section 7 is implemented. 492 A Broker MUST accept PUBLISH operations using the PUT method. 493 PUBLISH operations using the PUT method replace any stored 494 representation associated with the topic, with the supplied 495 representation. A Broker MAY reject, or delay responses to, PUT 496 requests to a topic while pending resolution of notifications to 497 subscribers from previous PUT requests. 499 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 500 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 501 to a topic that does not exist, the Broker MUST create the topic 502 using the information in the PUT operation. The Broker MUST create a 503 topic with the URI-Path of the request, including all of the sub- 504 topics necessary, and create a topic link with the ct attribute set 505 to the content-format value from the header of the PUT request. If 506 topic is created, the Broker MUST return the response "2.01 Created" 507 with the URI of the created topic, including all of the created path 508 segments, returned via the Location-Path option. 510 Figure 9 shows an example of a topic being created on first PUBLISH. 512 A Broker MAY accept PUBLISH operations using the POST method. If a 513 Broker accepts PUBLISH using POST it shall respond with the 2.04 514 Changed status code. If an attempt is made to PUBLISH using POST to 515 a topic that does not exist, the Broker SHALL return a response 516 status indicating resource not found, such as HTTP 404 or CoAP 4.04. 518 A Broker MAY perform garbage collection of stored representations 519 which have been delivered to all subscribers or which have timed out. 520 A Broker MAY retain at least one most recently published 521 representation to return in response to SUBSCRIBE and READ requests. 523 A Broker MUST make a best-effort attempt to notify all clients 524 subscribed on a particular topic each time it receives a publish on 525 that topic. An example is shown in Figure 10. 527 If a client publishes to a Broker with the Max-Age option, the Broker 528 MUST include the same value for the Max-Age option in all 529 notifications. 531 A Broker MUST use CoAP Notification as described in [RFC7641] to 532 notify subscribed clients. 534 The PUBLISH operation is specified as follows: 536 Interaction: Client -> Broker 538 Method: PUT, POST 540 URI Template: {+ps}/{+topic} 542 URI Template Variables: ps := Pub/sub REST API entry point 543 (optional). The entry point of the pub/sub REST API, as obtained 544 from discovery, used to discover topics. 546 topic := The desired topic to return links for (optional). 548 Content-Format: Any valid CoAP content format 550 Payload: Representation of the topic value (CoAP resource state 551 representation) in the indicated content format 553 The following response codes are defined for the PUBLISH operation: 555 Success: 2.01 "Created". Successful publish, topic is created 557 Success: 2.04 "Changed". Successful publish, topic is updated 559 Failure: 4.00 "Bad Request". Malformed request. 561 Failure: 4.01 "Unauthorized". Authorization failure. 563 Failure: 4.04 "Not Found". Topic does not exist. 565 Failure: 4.29 "Too Many Requests". The client should slow down the 566 rate of publish messages for this topic (see Section 7). 568 Figure 8 shows an example of a new value being successfully published 569 to the topic "topic1". See Figure 10 for an example of a Broker 570 forwarding a message from a publishing client to a subscribed client. 572 Client Broker 573 | | 574 | ---------- PUT /ps/topic1 "1033.3" --------> | 575 | | 576 | | 577 | <--------------- 2.04 Changed---------------- | 578 | | 580 Figure 8: Example of PUBLISH 582 Client Broker 583 | | 584 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 585 | | 586 | | 587 | <--------------- 2.01 Created---------------- | 588 | Location: /ps/exa/mpl/e | 589 | | 591 Figure 9: Example of CREATE on PUBLISH 593 4.4. SUBSCRIBE 595 A CoAP pub/sub Broker MAY allow Clients to subscribe to topics on the 596 Broker using CoAP Observe as described in [RFC7641]. A CoAP pub/sub 597 Client wishing to Subscribe to a topic on a Broker MUST use a CoAP 598 GET with the Observe option set to 0 (zero). The Broker MAY add the 599 client to a list of observers. The Broker MUST return a response 600 code of "2.05 Content" along with the most recently published value 601 if the topic contains a valid value and the Broker can supply the 602 requested content format. The Broker MUST reject Subscribe requests 603 on a topic if the content format of the request is not the content 604 format the topic was created with. 606 If the topic was published with the Max-Age option, the Broker MUST 607 set the Max-Age option in the valid response to the amount of time 608 remaining for the value to be valid since the last publish operation 609 on that topic. The Broker MUST return a response code of "2.07 No 610 Content" if the topic has not yet been published to, or if Max-Age of 611 the previously stored value has expired. The Broker MUST return a 612 response code "4.04 Not Found" if the topic does not exist or has 613 been removed. 615 The Broker MUST return a response code "4.15 Unsupported Content 616 Format" if it can not return the requested content format. If a 617 Broker is unable to accept a new Subscription on a topic, it SHOULD 618 return the appropriate response code without the Observe option as 619 per [RFC7641] Section 4.1. 621 There is no explicit maximum lifetime of a Subscription, thus a 622 Broker may remove subscribers at any time. The Broker, upon removing 623 a Subscriber, will transmit the appropriate response code without the 624 Observe option, as per [RFC7641] Section 4.2, to the removed 625 Subscriber. 627 The SUBSCRIBE operation is specified as follows: 629 Interaction: Client -> Broker 631 Method: GET 633 Options: Observe:0 635 URI Template: {+ps}/{+topic} 637 URI Template Variables: ps := Pub/sub REST API entry point 638 (optional). The entry point of the pub/sub REST API, as obtained 639 from discovery, used to discover topics. 641 topic := The desired topic to return links for (optional). 643 The following response codes are defined for the SUBSCRIBE operation: 645 Success: 2.05 "Content". Successful subscribe, current value 646 included 648 Success: 2.07 "No Content". Successful subscribe, value not 649 included 651 Failure: 4.00 "Bad Request". Malformed request. 653 Failure: 4.01 "Unauthorized". Authorization failure. 655 Failure: 4.04 "Not Found". Topic does not exist. 657 Failure: 4.15 "Unsupported Content Format". Unsupported content 658 format. 660 Figure 10 shows an example of Client2 subscribing to "topic1" and 661 receiving a response from the Broker, with a subsequent notification. 662 The subscribe response from the Broker uses the last stored value 663 associated with the topic1. The notification from the Broker is sent 664 in response to the publish received from Client1. 666 Client1 Client2 Broker 667 | | Subscribe | 668 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 669 | | | 670 | | <---------- 2.05 Content Observe:10---------- | 671 | | | 672 | | | 673 | | Publish | 674 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 675 | | Notify | 676 | | <---------- 2.05 Content Observe:11 --------- | 677 | | | 679 Figure 10: Example of SUBSCRIBE 681 4.5. UNSUBSCRIBE 683 If a CoAP pub/sub Broker allows clients to SUBSCRIBE to topics on the 684 Broker, it MUST allow Clients to unsubscribe from topics on the 685 Broker using the CoAP Cancel Observation operation. A CoAP pub/sub 686 Client wishing to unsubscribe to a topic on a Broker MUST either use 687 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 688 Reset message in response to a publish, as per [RFC7641]. 690 The UNSUBSCRIBE operation is specified as follows: 692 Interaction: Client -> Broker 694 Method: GET 695 Options: Observe:1 697 URI Template: {+ps}/{+topic}{?q*} 699 URI Template Variables: ps := Pub/sub REST API entry point 700 (optional). The entry point of the pub/sub REST API, as obtained 701 from discovery, used to discover topics. 703 topic := The desired topic to return links for (optional). 705 q := Query Filter (optional). MAY contain a query filter list as 706 per [RFC6690] Section 4.1. 708 The following response codes are defined for the UNSUBSCRIBE 709 operation: 711 Success: 2.05 "Content". Successful unsubscribe, current value 712 included 714 Success: 2.07 "No Content". Successful unsubscribe, value not 715 included 717 Failure: 4.00 "Bad Request". Malformed request. 719 Failure: 4.01 "Unauthorized". Authorization failure. 721 Failure: 4.04 "Not Found". Topic does not exist. 723 Figure 11 shows an example of a client unsubscribe using the 724 Observe=1 cancellation method. 726 Client Broker 727 | | 728 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 729 | | 730 | <------------- 2.05 Content ----------------- | 731 | | 733 Figure 11: Example of UNSUBSCRIBE 735 4.6. READ 737 A CoAP pub/sub Broker MAY accept Read requests on a topic using the 738 the CoAP GET method if the content format of the request matches the 739 content format the topic was created with. The Broker MUST return a 740 response code of "2.05 Content" along with the most recently 741 published value if the topic contains a valid value and the Broker 742 can supply the requested content format. 744 If the topic was published with the Max-Age option, the Broker MUST 745 set the Max-Age option in the valid response to the amount of time 746 remaining for the topic to be valid since the last publish. The 747 Broker MUST return a response code of "2.07 No Content" if the Max- 748 Age of the previously stored value has expired, or if the topic has 749 not yet been published to. 751 The Broker MUST return a response code "4.04 Not Found" if the topic 752 does not exist or has been removed. The Broker MUST return a 753 response code "4.15 Unsupported Content Format" if the Broker can not 754 return the requested content format. 756 The READ operation is specified as follows: 758 Interaction: Client -> Broker 760 Method: GET 762 URI Template: {+ps}/{+topic} 764 URI Template Variables: ps := Pub/sub REST API entry point 765 (optional). The entry point of the pub/sub REST API, as obtained 766 from discovery, used to discover topics. 768 topic := The desired topic to return links for (optional). 770 The following response codes are defined for the READ operation: 772 Success: 2.05 "Content". Successful READ, current value included 774 Success: 2.07 "No Content". Topic exists, value not included 776 Failure: 4.00 "Bad Request". Malformed request. 778 Failure: 4.01 "Unauthorized". Authorization failure. 780 Failure: 4.04 "Not Found". Topic does not exist. 782 Failure: 4.15 "Unsupported Content Format". Unsupported content- 783 format. 785 Figure 12 shows an example of a successful READ from topic1, followed 786 by a Publish on the topic, followed at some time later by a read of 787 the updated value from the recent Publish. 789 Client1 Client2 Broker 790 | | Read | 791 | | --------------- GET /ps/topic1 -------------> | 792 | | | 793 | | <---------- 2.05 Content "1007.1"------------ | 794 | | | 795 | | | 796 | | Publish | 797 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 798 | | | 799 | | | 800 | | Read | 801 | | --------------- GET /ps/topic1 -------------> | 802 | | | 803 | | <----------- 2.05 Content "1033.3" ---------- | 804 | | | 806 Figure 12: Example of READ 808 4.7. REMOVE 810 A CoAP pub/sub Broker MAY allow clients to remove topics from the 811 Broker using the CoAP Delete method on the URI of the topic. The 812 CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is 813 successful. The Broker MUST return the appropriate 4.xx response 814 code indicating the reason for failure if the topic can not be 815 removed. 817 When a topic is removed for any reason, the Broker SHOULD remove all 818 of the observers from the list of observers and return a final 4.04 819 "Not Found" response as per [RFC7641] Section 3.2. If a topic which 820 has sub-topics is removed, then all of its sub-topics MUST be 821 recursively removed. 823 The REMOVE operation is specified as follows: 825 Interaction: Client -> Broker 827 Method: DELETE 829 URI Template: {+ps}/{+topic} 831 URI Template Variables: ps := Pub/sub REST API entry point 832 (optional). The entry point of the pub/sub REST API, as obtained 833 from discovery, used to discover topics. 835 topic := The desired topic to return links for (optional). 837 Content-Format: None 839 Response Payload: None 841 The following response codes are defined for the REMOVE operation: 843 Success: 2.02 "Deleted". Successful remove 845 Failure: 4.00 "Bad Request". Malformed request. 847 Failure: 4.01 "Unauthorized". Authorization failure. 849 Failure: 4.04 "Not Found". Topic does not exist. 851 Figure 13 shows a successful remove of topic1. 853 Client Broker 854 | | 855 | ------------- DELETE /ps/topic1 ------------> | 856 | | 857 | | 858 | <-------------- 2.02 Deleted ---------------- | 859 | | 861 Figure 13: Example of REMOVE 863 5. CoAP Pub/sub Operation with Resource Directory 865 A CoAP pub/sub Broker may register the base URI, which is the REST 866 API entry point for a pub/sub service, with a Resource Directory. A 867 pub/sub Client may use an RD to discover a pub/sub Broker. 869 A CoAP pub/sub Client may register links [RFC6690] with a Resource 870 Directory to enable discovery of created pub/sub topics. A pub/sub 871 Client may use an RD to discover pub/sub Topics. A client which 872 registers pub/sub Topics with an RD MUST use the context relation 873 (con) [I-D.ietf-core-resource-directory] to indicate that the context 874 of the registered links is the pub/sub Broker. 876 A CoAP pub/sub Broker may alternatively register links to its topics 877 to a Resource Directory by triggering the RD to retrieve it's links 878 from .well-known/core. In order to use this method, the links must 879 first be exposed in the .well-known/core of the pub/sub Broker. See 880 Section 4.1 in this document. 882 The pub/sub Broker triggers the RD to retrieve its links by sending a 883 POST with an empty payload to the .well-known/core of the Resource 884 Directory. The RD server will then retrieve the links from the 885 .well-known/core of the pub/sub Broker and incorporate them into the 886 Resource Directory. See [I-D.ietf-core-resource-directory] for 887 further details. 889 6. Sleep-Wake Operation 891 CoAP pub/sub provides a way for client nodes to sleep between 892 operations, conserving energy during idle periods. This is made 893 possible by shifting the server role to the Broker, allowing the 894 Broker to be always-on and respond to requests from other clients 895 while a particular client is sleeping. 897 For example, the Broker will retain the last state update received 898 from a sleeping client, in order to supply the most recent state 899 update to other clients in response to read and subscribe operations. 901 Likewise, the Broker will retain the last state update received on 902 the topic such that a sleeping client, upon waking, can perform a 903 read operation to the Broker to update its own state from the most 904 recent system state update. 906 7. Simple Flow Control 908 Since the Broker node has to potentially send a large amount of 909 notification messages for each publish message and it may be serving 910 a large amount of subscribers and publishers simultaneously, the 911 Broker may become overwhelmed if it receives many publish messages to 912 popular topics in a short period of time. 914 If the Broker is unable to serve a certain client that is sending 915 publish messages too fast, the Broker SHOULD respond with Response 916 Code 4.29, "Too Many Requests" [I-D.ietf-core-too-many-reqs] and set 917 the Max-Age Option to indicate the number of seconds after which the 918 client can retry. The Broker MAY stop creating notifications from 919 the publish messages from this client and to this topic for the 920 indicated time. 922 If a client receives the 4.29 Response Code from the Broker for a 923 publish message to a topic, it MUST NOT send new publish messages to 924 the Broker on the same topic before the time indicated in Max-Age has 925 passed. 927 8. Security Considerations 929 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 930 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 931 therefore the security considerations of those documents also apply 932 to this specification. Additionally, a CoAP pub/sub Broker and the 933 clients SHOULD authenticate each other and enforce access control 934 policies. A malicious client could subscribe to data it is not 935 authorized to or mount a denial of service attack against the Broker 936 by publishing a large number of resources. The authentication can be 937 performed using the already standardized DTLS offered mechanisms, 938 such as certificates. DTLS also allows communication security to be 939 established to ensure integrity and confidentiality protection of the 940 data exchanged between these relevant parties. Provisioning the 941 necessary credentials, trust anchors and authorization policies is 942 non-trivial and subject of ongoing work. 944 The use of a CoAP pub/sub Broker introduces challenges for the use of 945 end-to-end security between for example a client device on a sensor 946 network and a client application running in a cloud-based server 947 infrastructure since Brokers terminate the exchange. While running 948 separate DTLS sessions from the client device to the Broker and from 949 Broker to client application protects confidentially on those paths, 950 the client device does not know whether the commands coming from the 951 Broker are actually coming from the client application. Similarly, a 952 client application requesting data does not know whether the data 953 originated on the client device. For scenarios where end-to-end 954 security is desirable the use of application layer security is 955 unavoidable. Application layer security would then provide a 956 guarantee to the client device that any request originated at the 957 client application. Similarly, integrity protected sensor data from 958 a client device will also provide guarantee to the client application 959 that the data originated on the client device itself. The protected 960 data can also be verified by the intermediate Broker ensuring that it 961 stores/caches correct request/response and no malicious messages/ 962 requests are accepted. The Broker would still be able to perform 963 aggregation of data/requests collected. 965 Depending on the level of trust users and system designers place in 966 the CoAP pub/sub Broker, the use of end-to-end object security is 967 RECOMMENDED as described in [I-D.palombini-ace-coap-pubsub-profile]. 968 An example application that uses the CoAP pub/sub Broker and relies 969 on end-to-end object security is described in [RFC8387]. When only 970 end-to-end encryption is necessary and the CoAP Broker is trusted, 971 Payload Only Protection (Mode:PAYL) could be used. The Publisher 972 would wrap only the payload before sending it to the Broker and set 973 the option Content-Format to application/smpayl. Upon receival, the 974 Broker can read the unencrypted CoAP header to forward it to the 975 subscribers. 977 9. IANA Considerations 979 This document registers one attribute value in the Resource Type 980 (rt=) registry established with [RFC6690] and appends to the 981 definition of one CoAP Response Code in the CoRE Parameters Registry. 983 9.1. Resource Type value 'core.ps' 985 o Attribute Value: core.ps 987 o Description: Section 4 of [[This document]] 989 o Reference: [[This document]] 991 o Notes: None 993 9.2. Resource Type value 'core.ps.discover' 995 o Attribute Value: core.ps.discover 997 o Description: Section 4 of [[This document]] 999 o Reference: [[This document]] 1001 o Notes: None 1003 9.3. Response Code value '2.07' 1005 o Response Code: 2.07 1007 o Description: No Content 1009 o Reference: [[This document]] 1011 o Notes: The server sends this code to the client to indicate that 1012 the request was valid and accepted, but the response may contain 1013 an empty payload. It is comparable to and may be proxied with the 1014 HTTP 204 No Content status code. 1016 10. Acknowledgements 1018 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 1019 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 1020 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 1021 and reviews. 1023 11. References 1025 11.1. Normative References 1027 [I-D.ietf-core-too-many-reqs] 1028 Keranen, A., "Too Many Requests Response Code for the 1029 Constrained Application Protocol", draft-ietf-core-too- 1030 many-reqs-06 (work in progress), November 2018. 1032 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1033 Requirement Levels", BCP 14, RFC 2119, 1034 DOI 10.17487/RFC2119, March 1997, . 1037 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1038 Resource Identifier (URI): Generic Syntax", STD 66, 1039 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1040 . 1042 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1043 and D. Orchard, "URI Template", RFC 6570, 1044 DOI 10.17487/RFC6570, March 2012, . 1047 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1048 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1049 . 1051 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1052 Application Protocol (CoAP)", RFC 7252, 1053 DOI 10.17487/RFC7252, June 2014, . 1056 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1057 Application Protocol (CoAP)", RFC 7641, 1058 DOI 10.17487/RFC7641, September 2015, . 1061 11.2. Informative References 1063 [I-D.ietf-core-object-security] 1064 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1065 "Object Security for Constrained RESTful Environments 1066 (OSCORE)", draft-ietf-core-object-security-15 (work in 1067 progress), August 2018. 1069 [I-D.ietf-core-resource-directory] 1070 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1071 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1072 resource-directory-18 (work in progress), December 2018. 1074 [I-D.palombini-ace-coap-pubsub-profile] 1075 Palombini, F., "CoAP Pub-Sub Profile for Authentication 1076 and Authorization for Constrained Environments (ACE)", 1077 draft-palombini-ace-coap-pubsub-profile-03 (work in 1078 progress), June 2018. 1080 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1081 DOI 10.17487/RFC5988, October 2010, . 1084 [RFC8387] Sethi, M., Arkko, J., Keranen, A., and H. Back, "Practical 1085 Considerations and Implementation Experiences in Securing 1086 Smart Object Networks", RFC 8387, DOI 10.17487/RFC8387, 1087 May 2018, . 1089 Authors' Addresses 1091 Michael Koster 1092 SmartThings 1094 Email: Michael.Koster@smartthings.com 1096 Ari Keranen 1097 Ericsson 1099 Email: ari.keranen@ericsson.com 1101 Jaime Jimenez 1102 Ericsson 1104 Email: jaime.jimenez@ericsson.com