idnits 2.17.1 draft-ietf-core-coap-pubsub-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 2, 2018) is 2122 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 1055, but no explicit reference was found in the text == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-13 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-14 == 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: January 3, 2019 J. Jimenez 6 Ericsson 7 July 2, 2018 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-05 12 Abstract 14 The Constrained Application Protocol (CoAP), and related extensions 15 are intended to support machine-to-machine communication in systems 16 where one or more nodes are resource constrained, in particular for 17 low power wireless sensor networks. This document defines a publish- 18 subscribe Broker for CoAP that extends the capabilities of CoAP for 19 supporting nodes with long breaks in connectivity and/or up-time. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 3, 2019. 38 Copyright Notice 40 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . . . . 21 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 . . . . . . . . . . . . . . . . . . . . . . . . . 22 81 11.1. Normative References . . . . . . . . . . . . . . . . . . 22 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 server 92 or a client. 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 This document specifies the means for nodes with limited reachability 105 to communicate using simple extensions to CoAP. The extensions 106 enable publish-subscribe communication using a Broker node that 107 enables store-and-forward messaging between two or more nodes. 108 Furthermore the extensions facilitate many-to-many communication 109 using CoAP. 111 2. Terminology 113 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 114 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 115 specification are to be interpreted as described in [RFC2119]. 117 This specification requires readers to be familiar with all the terms 118 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 119 should also be familiar with the terms and concepts discussed in 120 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 121 format [RFC6570] is used to describe the REST API defined in this 122 specification. 124 This specification makes use of the following additional terminology: 126 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 127 published to a Broker and potential receivers can subscribe to the 128 Broker to receive messages. The publishers do not (need to) know 129 where the message will be eventually sent: the publications and 130 subscriptions are matched by a Broker and publications are 131 delivered by the Broker to subscribed receivers. 133 CoAP pub/sub service: A group of REST resources, as defined in this 134 document, which together implement the required features of this 135 specification. 137 CoAP pub/sub Broker: A server node capable of receiving messages 138 (publications) from and sending messages to other nodes, and able 139 to match subscriptions and publications in order to route messages 140 to the right destinations. The Broker can also temporarily store 141 publications to satisfy future subscriptions and pending 142 notifications. 144 CoAP pub/sub Client: A CoAP client which is capable of publish or 145 subscribe operations as defined in this specification. 147 Topic: A unique identifier for a particular item being published 148 and/or subscribed to. A Broker uses the topics to match 149 subscriptions to publications. A topic is a valid CoAP URI as 150 defined in [RFC7252] 152 3. Architecture 154 3.1. CoAP Pub/sub Architecture 156 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 157 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 158 sub REST API which is hosted by the Broker. State information is 159 updated between the Clients and the Broker. The CoAP pub/sub Broker 160 performs a store-and-forward of state update representations between 161 certain CoAP pub/sub Clients. Clients Subscribe to topics upon which 162 representations are Published by other Clients, which are forwarded 163 by the Broker to the subscribing clients. A CoAP pub/sub Broker may 164 be used as a REST resource proxy, retaining the last published 165 representation to supply in response to Read requests from Clients. 167 Clients pub/sub Broker 168 +-------+ | 169 | CoAP | | 170 |pub/sub|---------|------+ 171 |Client | | | +-------+ 172 +-------+ | +----| CoAP | 173 | |pub/sub| 174 +-------+ | +----|Broker | 175 | CoAP | | | +-------+ 176 |pub/sub|---------|------+ 177 |Client | | 178 +-------+ | 180 Figure 1: CoAP pub/sub Architecture 182 3.2. CoAP Pub/sub Broker 184 A CoAP pub/sub Broker is a CoAP Server that exposes a REST API for 185 clients to use to initiate publish-subscribe interactions. Avoiding 186 the need for direct reachability between clients, the Broker only 187 needs to be reachable from all clients. The Broker also needs to 188 have sufficient resources (storage, bandwidth, etc.) to host CoAP 189 resource services, and potentially buffer messages, on behalf of the 190 clients. 192 3.3. CoAP Pub/sub Client 194 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 195 CoAP pub/sub REST API defined in this document. Clients initiate 196 interactions with a CoAP pub/sub Broker. A data source (e.g., sensor 197 clients) can publish state updates to the Broker and data sinks 198 (e.g., actuator clients) can read from or subscribe to state updates 199 from the Broker. Application clients can make use of both publish 200 and subscribe in order to exchange state updates with data sources 201 and data sinks. 203 3.4. CoAP Pub/sub Topic 205 The clients and Broker use topics to identify a particular resource 206 or object in a publish-subscribe system. Topics are conventionally 207 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 208 "/EP-33543/sen/3303/0/5700". The topics are hosted by a Broker and 209 all the clients using the Broker share the same namespace for topics. 210 Every CoAP pub/sub topic has an associated link, consisting of a 211 reference path on the Broker using URI path [RFC3986] construction 212 and link attributes [RFC6690]. Every topic is associated with zero 213 or more stored representations and a content-format specified in the 214 link. A CoAP pub/sub topic value may alternatively consist of a 215 collection of one or more sub-topics, consisting of links to the sub- 216 topic URIs and indicated by a link-format content-format. Sub-topics 217 are also topics and may have their own sub-topics, forming a tree 218 structure of unique paths that is implemented using URIs. The full 219 URI of a topic includes a schems and authority for the Broker, for 220 example "coaps://10.0.0.13:5684/EP-33543/sen/3303/0/5700". 222 3.5. brokerless Pub/sub 224 Figure 2 shows an arrangement for using CoAP pub/sub in a 225 "Brokerless" configuration between peer nodes. Nodes in a Brokerless 226 system may act as both Broker and client. A node that supports 227 Broker functionality may be pre-configured with topics that expose 228 services and resources. Brokerless peer nodes can be mixed with 229 client and Broker nodes in a system with full interoperability. 231 Peer pub/sub Peer 232 +-------+ | +-------+ 233 | CoAP | | | CoAP | 234 |pub/sub|---------|---------|pub/sub| 235 |Client | | |Broker | 236 +-------+ | +-------+ 237 | CoAP | | | CoAP | 238 |pub/sub|---------|---------|pub/sub| 239 |Broker | | |Client | 240 +-------+ | +-------+ 242 Figure 2: Brokerless pub/sub 244 4. CoAP Pub/sub REST API 246 This section defines the REST API exposed by a CoAP pub/sub Broker to 247 pub/sub Clients. The examples throughout this section assume the use 248 of CoAP [RFC7252]. A CoAP pub/sub Broker implementing this 249 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 250 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 251 section. Optimized implementations MAY support a subset of the 252 operations as required by particular constrained use cases. 254 4.1. DISCOVERY 256 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 257 Simple Discovery or through a Resource Directory (RD) 258 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 259 indicate its presence and availability on a network by exposing a 260 link to the entry point of its pub/sub API at its .well-known/core 261 location [RFC6690]. A CoAP pub/sub Broker MAY register its pub/sub 262 REST API entry point with a Resource Directory. Figure 3 shows an 263 example of a client discovering a local pub/sub API using CoAP Simple 264 Discovery. A Broker wishing to advertise the CoAP pub/sub API for 265 Simple Discovery or through a Resource Directory MUST use the link 266 relation rt=core.ps. A Broker MAY advertise its supported content 267 formats and other attributes in the link to its pub/sub API. 269 A CoAP pub/sub Broker MAY offer a topic discovery entry point to 270 enable Clients to find topics of interest, either by topic name or by 271 link attributes which may be registered when the topic is created. 272 Figure 4 shows an example of a client looking for a topic with a 273 resource type (rt) of "temperature" using Discover. The client then 274 receives the URI of the resource and its content-format. A pub/sub 275 Broker wishing to advertise topic discovery MUST use the relation 276 rt=core.ps.discover in the link. 278 A CoAP pub/sub Broker MAY provide topic discovery functionality 279 through the .well-known/core resource. Links to topics may be 280 exposed at .well-known/core in addition to links to the pub/sub API. 281 Figure 5 shows an example of topic discovery through .well-known/ 282 core. 284 Topics in the broker may be created in hierarchies (see {create}) 285 with parent topics having sub-topics. For a discovery the broker may 286 choose to not expose the sub-topics in order to limit amount of topic 287 links sent in a discovery response. The client can then perform 288 discovery for the parent topics it wants to discover the sub-topics. 290 The DISCOVER interface is specified as follows: 292 Interaction: Client -> Broker 294 Method: GET 296 URI Template: {+ps}/{+topic}{?q*} 298 URI Template Variables: ps := Pub/sub REST API entry point 299 (optional). The entry point of the pub/sub REST API, as obtained 300 from discovery, used to discover topics. 302 topic := The desired topic to return links for (optional). 304 q := Query Filter (optional). MAY contain a query filter list as 305 per [RFC6690] Section 4.1. 307 Content-Format: application/link-format 309 The following response codes are defined for the DISCOVER operation: 311 Success: 2.05 "Content" with an application/link-format payload 312 containing one or more matching entries for the Broker resource. 313 A pub/sub Broker SHOULD use the value "/ps/" for the base URI of 314 the pub/sub API wherever possible. 316 Failure: 4.04 "Not Found" is returned in case no matching entry is 317 found for a unicast request. 319 Failure: 4.00 "Bad Request" is returned in case of a malformed 320 request for a unicast request. 322 Failure: No error response to a multicast request. 324 Client Broker 325 | | 326 | ------ GET /.well-known/core?rt=core.ps ---->>| 327 | -- Content-Format: application/link-format ---| 328 | | 329 | <<--- 2.05 Content | 330 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 331 | | 333 Figure 3: Example of DISCOVER pub/sub function 335 Client Broker 336 | | 337 | ---------- GET /ps/?rt="temperature" ------->>| 338 | Content-Format: application/link-format | 339 | | 340 | <<-- 2.05 Content | 341 | ;rt="temperature";ct=50 ---| 342 | | 344 Figure 4: Example of DISCOVER topic 346 Client Broker 347 | | 348 | -------- GET /.well-known/core?ct=50 ------->>| 349 | Content-Format: application/link-format | 350 | | 351 | <<-- 2.05 Content | 352 | ;rt="temperature";ct=50 ---| 353 | | 355 Figure 5: Example of DISCOVER topic 357 4.2. CREATE 359 A CoAP pub/sub broker SHOULD allow Clients to create new topics on 360 the broker using CREATE. Some exceptions are for fixed brokerless 361 devices and pre-configured brokers in dedicated installations. A 362 client wishing to create a topic MUST use a CoAP POST to the pub/sub 363 API with a payload indicating the desired topic. The topic 364 specification sent in the payload MUST use a supported serialization 365 of the CoRE link format [RFC6690]. The target of the link MUST be a 366 URI formatted string. The client MUST indicate the desired content 367 format for publishes to the topic by using the ct (Content Format) 368 link attribute in the link-format payload. The client MAY indicate 369 the lifetime of the topic by including the Max-Age option in the 370 CREATE request. 372 Topics may be created as sub-topics of other topics. A client MAY 373 create a topic with a ct (Content Format) link attribute value which 374 describes a supported serialization of the CoRE link format [RFC6690] 375 such as application/link-format (ct=40) or its JSON or CBOR 376 serializations. If a topic is created which describes a link 377 serialization, that topic may then have sub-topics created under it 378 as shown in Figure 7. 380 Ony one level in the topic hierarchy may be created as a result of a 381 CREATE operation, unless create on PUBLISH is supported (see 382 Section 4.3). The topic string used in the link target MUST NOT 383 contain the "/" character. 385 A topic creator MUST include exactly one content format link 386 attribute value (ct) in the create payload. If the Broker does not 387 support the indicated format for both publish and subscribe, it MUST 388 reject the operation with an error code of 4.00 "Bad Request". 390 There is no default content format. If no ct is specified, the 391 Broker MUST reject the operation with an error code of 4.00 "Bad 392 Request". 394 A Broker MUST return a response code of "2.01 Created" if the topic 395 is created and return the URI path of the created topic via Location- 396 Path options. The Broker MUST return the appropriate 4.xx response 397 code indicating the reason for failure if a new topic can not be 398 created. Broker SHOULD remove topics if the Max-Age of the topic is 399 exceeded without any publishes to the topic. Broker SHOULD retain a 400 topic indefinitely if the Max-Age option is elided or is set to zero 401 upon topic creation. The lifetime of a topic MUST be refreshed upon 402 create operations with a target of an existing topic. 404 Topic hierarchies can be created by creating parent topics. A parent 405 topic is created with a POST using ct (Content Format) link attribute 406 value which describes a supported serialization of the CoRE link 407 format [RFC6690], such as application/link-format (ct=40) or its JSON 408 or CBOR serializations. If a topic is created which describes a link 409 serialization, that topic may then have sub-topics created under it 410 as shown in Figure 7. 412 The CREATE interface is specified as follows: 414 Interaction: Client -> Broker 416 Method: POST 417 URI Template: {+ps}/{+topic} 419 URI Template Variables: ps := Pub/sub REST API entry point 420 (optional). The entry point of the pub/sub REST API, as obtained 421 from discovery, used to discover topics. 423 topic := The desired topic to return links for (optional). 425 Content-Format: application/link-format 427 Payload: The desired topic to CREATE 429 The following response codes are defined for the CREATE operation: 431 Success: 2.01 "Created". Successful Creation of the topic 433 Failure: 4.00 "Bad Request". Malformed request. 435 Failure: 4.01 "Unauthorized". Authorization failure. 437 Failure: 4.03 "Forbidden". Topic already exists. 439 Failure: 4.06 "Not Acceptable". Unsupported content format for 440 topic. 442 Figure 6 shows an example of a topic called "topic1" being 443 successfully created. 445 Client Broker 446 | | 447 | ---------- POST /ps/ ";ct=50" ------->| 448 | | 449 | <---------------- 2.01 Created ---------------| 450 | Location: /ps/topic1 | 451 | | 453 Figure 6: Example of CREATE topic 455 Client Broker 456 | | 457 | ----- POST /ps/ ";ct=40" ------>| 458 | | 459 | <---------------- 2.01 Created ---------------| 460 | Location: /ps/parent-topic/ | 461 | | 462 |-- POST /ps/parent-topic/ ";ct=50" ->| 463 | | 464 | <---------------- 2.01 Created ---------------| 465 | Location: /ps/parent-topic/subtopic | 466 | | 467 | | 469 Figure 7: Example of CREATE of topic hierarchy 471 4.3. PUBLISH 473 A CoAP pub/sub Broker MAY allow clients to PUBLISH to topics on the 474 Broker. A client MAY use the PUT or the POST method to publish state 475 updates to the CoAP pub/sub Broker. A client MUST use the content 476 format specified upon creation of a given topic to publish updates to 477 that topic. The Broker MUST reject publish operations which do not 478 use the specified content format. A CoAP client publishing on a 479 topic MAY indicate the maximum lifetime of the value by including the 480 Max-Age option in the publish request. The Broker MUST return a 481 response code of "2.04 Changed" if the publish is accepted. A Broker 482 MAY return a "4.04 Not Found" if the topic does not exist. A Broker 483 MAY return "4.29 Too Many Requests" if simple flow control as 484 described in Section 7 is implemented. 486 A Broker MUST accept PUBLISH operations using the PUT method. 487 PUBLISH operations using the PUT method replace any stored 488 representation associated with the topic, with the supplied 489 representation. A Broker MAY reject, or delay responses to, PUT 490 requests to a topic while pending resolution of notifications to 491 subscribers from previous PUT requests. 493 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 494 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 495 to a topic that does not exist, the Broker MUST create the topic 496 using the information in the PUT operation. The Broker MUST create a 497 topic with the URI-Path of the request, including all of the sub- 498 topics necessary, and create a topic link with the ct attribute set 499 to the content-format value from the header of the PUT request. If 500 topic is created, the Broker MUST return the response "2.01 Created" 501 with the URI of the created topic, including all of the created path 502 segments, returned via the Location-Path option. 504 Figure 9 shows an example of a topic being created on first PUBLISH. 506 A Broker MAY accept PUBLISH operations using the POST method. If a 507 Broker accepts PUBLISH using POST it shall respond with the 2.04 508 Changed status code. If an attempt is made to PUBLISH using POST to 509 a topic that does not exist, the Broker SHALL return a response 510 status indicating resource not found, such as HTTP 404 or CoAP 4.04. 512 A Broker MAY perform garbage collection of stored representations 513 which have been delivered to all subscribers or which have timed out. 514 A Broker MAY retain at least one most recently published 515 representation to return in response to SUBSCRIBE and READ requests. 517 A Broker MUST make a best-effort attempt to notify all clients 518 subscribed on a particular topic each time it receives a publish on 519 that topic. An example is shown in Figure 10. 521 If a client publishes to a Broker with the Max-Age option, the Broker 522 MUST include the same value for the Max-Age option in all 523 notifications. 525 A Broker MUST use CoAP Notification as described in [RFC7641] to 526 notify subscribed clients. 528 The PUBLISH operation is specified as follows: 530 Interaction: Client -> Broker 532 Method: PUT, POST 534 URI Template: {+ps}/{+topic} 536 URI Template Variables: ps := Pub/sub REST API entry point 537 (optional). The entry point of the pub/sub REST API, as obtained 538 from discovery, used to discover topics. 540 topic := The desired topic to return links for (optional). 542 Content-Format: Any valid CoAP content format 544 Payload: Representation of the topic value (CoAP resource state 545 representation) in the indicated content format 547 The following response codes are defined for the PUBLISH operation: 549 Success: 2.01 "Created". Successful publish, topic is created 551 Success: 2.04 "Changed". Successful publish, topic is updated 553 Failure: 4.00 "Bad Request". Malformed request. 555 Failure: 4.01 "Unauthorized". Authorization failure. 557 Failure: 4.04 "Not Found". Topic does not exist. 559 Failure: 4.29 "Too Many Requests". The client should slow down the 560 rate of publish messages for this topic (see Section 7). 562 Figure 8 shows an example of a new value being successfully published 563 to the topic "topic1". See Figure 10 for an example of a Broker 564 forwarding a message from a publishing client to a subscribed client. 566 Client Broker 567 | | 568 | ---------- PUT /ps/topic1 "1033.3" --------> | 569 | | 570 | | 571 | <--------------- 2.04 Changed---------------- | 572 | | 574 Figure 8: Example of PUBLISH 576 Client Broker 577 | | 578 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 579 | | 580 | | 581 | <--------------- 2.01 Created---------------- | 582 | Location: /ps/exa/mpl/e | 583 | | 585 Figure 9: Example of CREATE on PUBLISH 587 4.4. SUBSCRIBE 589 A CoAP pub/sub Broker MAY allow Clients to subscribe to topics on the 590 Broker using CoAP Observe as described in [RFC7641]. A CoAP pub/sub 591 Client wishing to Subscribe to a topic on a Broker MUST use a CoAP 592 GET with the Observe option set to 0 (zero). The Broker MAY add the 593 client to a list of observers. The Broker MUST return a response 594 code of "2.05 Content" along with the most recently published value 595 if the topic contains a valid value and the Broker can supply the 596 requested content format. The Broker MUST reject Subscribe requests 597 on a topic if the content format of the request is not the content 598 format the topic was created with. 600 If the topic was published with the Max-Age option, the Broker MUST 601 set the Max-Age option in the valid response to the amount of time 602 remaining for the value to be valid since the last publish operation 603 on that topic. The Broker MUST return a response code of "2.07 No 604 Content" if the topic has not yet been published to, or if Max-Age of 605 the previously stored value has expired. The Broker MUST return a 606 response code "4.04 Not Found" if the topic does not exist or has 607 been removed. 609 The Broker MUST return a response code "4.15 Unsupported Content 610 Format" if it can not return the requested content format. If a 611 Broker is unable to accept a new Subscription on a topic, it SHOULD 612 return the appropriate response code without the Observe option as 613 per [RFC7641] Section 4.1. 615 There is no explicit maximum lifetime of a Subscription, thus a 616 Broker may remove subscribers at any time. The Broker, upon removing 617 a Subscriber, will transmit the appropriate response code without the 618 Observe option, as per [RFC7641] Section 4.2, to the removed 619 Subscriber. 621 The SUBSCRIBE operation is specified as follows: 623 Interaction: Client -> Broker 625 Method: GET 627 Options: Observe:0 629 URI Template: {+ps}/{+topic} 631 URI Template Variables: ps := Pub/sub REST API entry point 632 (optional). The entry point of the pub/sub REST API, as obtained 633 from discovery, used to discover topics. 635 topic := The desired topic to return links for (optional). 637 The following response codes are defined for the SUBSCRIBE operation: 639 Success: 2.05 "Content". Successful subscribe, current value 640 included 642 Success: 2.07 "No Content". Successful subscribe, value not 643 included 645 Failure: 4.00 "Bad Request". Malformed request. 647 Failure: 4.01 "Unauthorized". Authorization failure. 649 Failure: 4.04 "Not Found". Topic does not exist. 651 Failure: 4.15 "Unsupported Content Format". Unsupported content 652 format. 654 Figure 10 shows an example of Client2 subscribing to "topic1" and 655 receiving a response from the Broker, with a subsequent notification. 656 The subscribe response from the Broker uses the last stored value 657 associated with the topic1. The notification from the Broker is sent 658 in response to the publish received from Client1. 660 Client1 Client2 Broker 661 | | Subscribe | 662 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 663 | | | 664 | | <---------- 2.05 Content Observe:10---------- | 665 | | | 666 | | | 667 | | Publish | 668 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 669 | | Notify | 670 | | <---------- 2.05 Content Observe:11 --------- | 671 | | | 673 Figure 10: Example of SUBSCRIBE 675 4.5. UNSUBSCRIBE 677 If a CoAP pub/sub Broker allows clients to SUBSCRIBE to topics on the 678 Broker, it MUST allow Clients to unsubscribe from topics on the 679 Broker using the CoAP Cancel Observation operation. A CoAP pub/sub 680 Client wishing to unsubscribe to a topic on a Broker MUST either use 681 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 682 Reset message in response to a publish, as per [RFC7641]. 684 The UNSUBSCRIBE operation is specified as follows: 686 Interaction: Client -> Broker 688 Method: GET 689 Options: Observe:1 691 URI Template: {+ps}/{+topic}{?q*} 693 URI Template Variables: ps := Pub/sub REST API entry point 694 (optional). The entry point of the pub/sub REST API, as obtained 695 from discovery, used to discover topics. 697 topic := The desired topic to return links for (optional). 699 q := Query Filter (optional). MAY contain a query filter list as 700 per [RFC6690] Section 4.1. 702 The following response codes are defined for the UNSUBSCRIBE 703 operation: 705 Success: 2.05 "Content". Successful unsubscribe, current value 706 included 708 Success: 2.07 "No Content". Successful unsubscribe, value not 709 included 711 Failure: 4.00 "Bad Request". Malformed request. 713 Failure: 4.01 "Unauthorized". Authorization failure. 715 Failure: 4.04 "Not Found". Topic does not exist. 717 Figure 11 shows an example of a client unsubscribe using the 718 Observe=1 cancellation method. 720 Client Broker 721 | | 722 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 723 | | 724 | <------------- 2.05 Content ----------------- | 725 | | 727 Figure 11: Example of UNSUBSCRIBE 729 4.6. READ 731 A CoAP pub/sub Broker MAY accept Read requests on a topic using the 732 the CoAP GET method if the content format of the request matches the 733 content format the topic was created with. The Broker MUST return a 734 response code of "2.05 Content" along with the most recently 735 published value if the topic contains a valid value and the Broker 736 can supply the requested content format. 738 If the topic was published with the Max-Age option, the Broker MUST 739 set the Max-Age option in the valid response to the amount of time 740 remaining for the topic to be valid since the last publish. The 741 Broker MUST return a response code of "2.07 No Content" if the Max- 742 Age of the previously stored value has expired, or if the topic has 743 not yet been published to. 745 The Broker MUST return a response code "4.04 Not Found" if the topic 746 does not exist or has been removed. The Broker MUST return a 747 response code "4.15 Unsupported Content Format" if the Broker can not 748 return the requested content format. 750 The READ operation is specified as follows: 752 Interaction: Client -> Broker 754 Method: GET 756 URI Template: {+ps}/{+topic} 758 URI Template Variables: ps := Pub/sub REST API entry point 759 (optional). The entry point of the pub/sub REST API, as obtained 760 from discovery, used to discover topics. 762 topic := The desired topic to return links for (optional). 764 The following response codes are defined for the READ operation: 766 Success: 2.05 "Content". Successful READ, current value included 768 Success: 2.07 "No Content". Topic exists, value not included 770 Failure: 4.00 "Bad Request". Malformed request. 772 Failure: 4.01 "Unauthorized". Authorization failure. 774 Failure: 4.04 "Not Found". Topic does not exist. 776 Failure: 4.15 "Unsupported Content Format". Unsupported content- 777 format. 779 Figure 12 shows an example of a successful READ from topic1, followed 780 by a Publish on the topic, followed at some time later by a read of 781 the updated value from the recent Publish. 783 Client1 Client2 Broker 784 | | Read | 785 | | --------------- GET /ps/topic1 -------------> | 786 | | | 787 | | <---------- 2.05 Content "1007.1"------------ | 788 | | | 789 | | | 790 | | Publish | 791 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 792 | | | 793 | | | 794 | | Read | 795 | | --------------- GET /ps/topic1 -------------> | 796 | | | 797 | | <----------- 2.05 Content "1033.3" ---------- | 798 | | | 800 Figure 12: Example of READ 802 4.7. REMOVE 804 A CoAP pub/sub Broker MAY allow clients to remove topics from the 805 Broker using the CoAP Delete method on the URI of the topic. The 806 CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is 807 successful. The Broker MUST return the appropriate 4.xx response 808 code indicating the reason for failure if the topic can not be 809 removed. 811 When a topic is removed for any reason, the Broker SHOULD remove all 812 of the observers from the list of observers and return a final 4.04 813 "Not Found" response as per [RFC7641] Section 3.2. If a topic which 814 has sub-topics is removed, then all of its sub-topics MUST be 815 recursively removed. 817 The REMOVE operation is specified as follows: 819 Interaction: Client -> Broker 821 Method: DELETE 823 URI Template: {+ps}/{+topic} 825 URI Template Variables: ps := Pub/sub REST API entry point 826 (optional). The entry point of the pub/sub REST API, as obtained 827 from discovery, used to discover topics. 829 topic := The desired topic to return links for (optional). 831 Content-Format: None 833 Response Payload: None 835 The following response codes are defined for the REMOVE operation: 837 Success: 2.02 "Deleted". Successful remove 839 Failure: 4.00 "Bad Request". Malformed request. 841 Failure: 4.01 "Unauthorized". Authorization failure. 843 Failure: 4.04 "Not Found". Topic does not exist. 845 Figure 13 shows a successful remove of topic1. 847 Client Broker 848 | | 849 | ------------- DELETE /ps/topic1 ------------> | 850 | | 851 | | 852 | <-------------- 2.02 Deleted ---------------- | 853 | | 855 Figure 13: Example of REMOVE 857 5. CoAP Pub/sub Operation with Resource Directory 859 A CoAP pub/sub Broker may register the base URI, which is the REST 860 API entry point for a pub/sub service, with a Resource Directory. A 861 pub/sub Client may use an RD to discover a pub/sub Broker. 863 A CoAP pub/sub Client may register links [RFC6690] with a Resource 864 Directory to enable discovery of created pub/sub topics. A pub/sub 865 Client may use an RD to discover pub/sub Topics. A client which 866 registers pub/sub Topics with an RD MUST use the context relation 867 (con) [I-D.ietf-core-resource-directory] to indicate that the context 868 of the registered links is the pub/sub Broker. 870 A CoAP pub/sub Broker may alternatively register links to its topics 871 to a Resource Directory by triggering the RD to retrieve it's links 872 from .well-known/core. In order to use this method, the links must 873 first be exposed in the .well-known/core of the pub/sub Broker. See 874 Section 4.1 in this document. 876 The pub/sub Broker triggers the RD to retrieve its links by sending a 877 POST with an empty payload to the .well-known/core of the Resource 878 Directory. The RD server will then retrieve the links from the 879 .well-known/core of the pub/sub Broker and incorporate them into the 880 Resource Directory. See [I-D.ietf-core-resource-directory] for 881 further details. 883 6. Sleep-Wake Operation 885 CoAP pub/sub provides a way for client nodes to sleep between 886 operations, conserving energy during idle periods. This is made 887 possible by shifting the server role to the Broker, allowing the 888 Broker to be always-on and respond to requests from other clients 889 while a particular client is sleeping. 891 For example, the Broker will retain the last state update received 892 from a sleeping client, in order to supply the most recent state 893 update to other clients in response to read and subscribe operations. 895 Likewise, the Broker will retain the last state update received on 896 the topic such that a sleeping client, upon waking, can perform a 897 read operation to the Broker to update its own state from the most 898 recent system state update. 900 7. Simple Flow Control 902 Since the Broker node has to potentially send a large amount of 903 notification messages for each publish message and it may be serving 904 a large amount of subscribers and publishers simultaneously, the 905 Broker may become overwhelmed if it receives many publish messages to 906 popular topics in a short period of time. 908 If the Broker is unable to serve a certain client that is sending 909 publish messages too fast, the Broker SHOULD respond with Response 910 Code 4.29, "Too Many Requests" [I-D.keranen-core-too-many-reqs] and 911 set the Max-Age Option to indicate the number of seconds after which 912 the client can retry. The Broker MAY stop creating notifications 913 from the publish messages from this client and to this topic for the 914 indicated time. 916 If a client receives the 4.29 Response Code from the Broker for a 917 publish message to a topic, it MUST NOT send new publish messages to 918 the Broker on the same topic before the time indicated in Max-Age has 919 passed. 921 8. Security Considerations 923 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 924 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 925 therefore the security considerations of those documents also apply 926 to this specification. Additionally, a CoAP pub/sub Broker and the 927 clients SHOULD authenticate each other and enforce access control 928 policies. A malicious client could subscribe to data it is not 929 authorized to or mount a denial of service attack against the Broker 930 by publishing a large number of resources. The authentication can be 931 performed using the already standardized DTLS offered mechanisms, 932 such as certificates. DTLS also allows communication security to be 933 established to ensure integrity and confidentiality protection of the 934 data exchanged between these relevant parties. Provisioning the 935 necessary credentials, trust anchors and authorization policies is 936 non-trivial and subject of ongoing work. 938 The use of a CoAP pub/sub Broker introduces challenges for the use of 939 end-to-end security between for example a client device on a sensor 940 network and a client application running in a cloud-based server 941 infrastructure since Brokers terminate the exchange. While running 942 separate DTLS sessions from the client device to the Broker and from 943 Broker to client application protects confidentially on those paths, 944 the client device does not know whether the commands coming from the 945 Broker are actually coming from the client application. Similarly, a 946 client application requesting data does not know whether the data 947 originated on the client device. For scenarios where end-to-end 948 security is desirable the use of application layer security is 949 unavoidable. Application layer security would then provide a 950 guarantee to the client device that any request originated at the 951 client application. Similarly, integrity protected sensor data from 952 a client device will also provide guarantee to the client application 953 that the data originated on the client device itself. The protected 954 data can also be verified by the intermediate Broker ensuring that it 955 stores/caches correct request/response and no malicious messages/ 956 requests are accepted. The Broker would still be able to perform 957 aggregation of data/requests collected. 959 Depending on the level of trust users and system designers place in 960 the CoAP pub/sub Broker, the use of end-to-end object security is 961 RECOMMENDED as described in [I-D.palombini-ace-coap-pubsub-profile]. 962 When only end-to-end encryption is necessary and the CoAP Broker is 963 trusted, Payload Only Protection (Mode:PAYL) could be used. The 964 Publisher would wrap only the payload before sending it to the Broker 965 and set the option Content-Format to application/smpayl. Upon 966 receival, the Broker can read the unencrypted CoAP header to forward 967 it to the subscribers. 969 9. IANA Considerations 971 This document registers one attribute value in the Resource Type 972 (rt=) registry established with [RFC6690] and appends to the 973 definition of one CoAP Response Code in the CoRE Parameters Registry. 975 9.1. Resource Type value 'core.ps' 977 o Attribute Value: core.ps 979 o Description: Section 4 of [[This document]] 981 o Reference: [[This document]] 983 o Notes: None 985 9.2. Resource Type value 'core.ps.discover' 987 o Attribute Value: core.ps.discover 989 o Description: Section 4 of [[This document]] 991 o Reference: [[This document]] 993 o Notes: None 995 9.3. Response Code value '2.07' 997 o Response Code: 2.07 999 o Description: No Content 1001 o Reference: [[This document]] 1003 o Notes: The server sends this code to the client to indicate that 1004 the request was valid and accepted, but the response may contain 1005 an empty payload. It is comparable to and may be proxied with the 1006 HTTP 204 No Content status code. 1008 10. Acknowledgements 1010 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 1011 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 1012 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 1013 and reviews. 1015 11. References 1017 11.1. Normative References 1019 [I-D.keranen-core-too-many-reqs] 1020 Keranen, A., "Too Many Requests Response Code for the 1021 Constrained Application Protocol", draft-keranen-core-too- 1022 many-reqs-01 (work in progress), March 2018. 1024 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1025 Requirement Levels", BCP 14, RFC 2119, 1026 DOI 10.17487/RFC2119, March 1997, . 1029 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1030 Resource Identifier (URI): Generic Syntax", STD 66, 1031 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1032 . 1034 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1035 and D. Orchard, "URI Template", RFC 6570, 1036 DOI 10.17487/RFC6570, March 2012, . 1039 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1040 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1041 . 1043 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1044 Application Protocol (CoAP)", RFC 7252, 1045 DOI 10.17487/RFC7252, June 2014, . 1048 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1049 Application Protocol (CoAP)", RFC 7641, 1050 DOI 10.17487/RFC7641, September 2015, . 1053 11.2. Informative References 1055 [I-D.ietf-core-object-security] 1056 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1057 "Object Security for Constrained RESTful Environments 1058 (OSCORE)", draft-ietf-core-object-security-13 (work in 1059 progress), June 2018. 1061 [I-D.ietf-core-resource-directory] 1062 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1063 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1064 resource-directory-14 (work in progress), July 2018. 1066 [I-D.palombini-ace-coap-pubsub-profile] 1067 Palombini, F., "CoAP Pub-Sub Profile for Authentication 1068 and Authorization for Constrained Environments (ACE)", 1069 draft-palombini-ace-coap-pubsub-profile-03 (work in 1070 progress), June 2018. 1072 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1073 DOI 10.17487/RFC5988, October 2010, . 1076 Authors' Addresses 1078 Michael Koster 1079 SmartThings 1081 Email: Michael.Koster@smartthings.com 1083 Ari Keranen 1084 Ericsson 1086 Email: ari.keranen@ericsson.com 1088 Jaime Jimenez 1089 Ericsson 1091 Email: jaime.jimenez@ericsson.com