idnits 2.17.1 draft-ietf-core-coap-pubsub-03.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 (February 12, 2018) is 2258 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.selander-ace-object-security' is defined on line 1041, but no explicit reference was found in the text == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-12 == Outdated reference: A later version (-06) exists of draft-palombini-ace-coap-pubsub-profile-01 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 6 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: August 16, 2018 J. Jimenez 6 Ericsson 7 February 12, 2018 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-pubsub-03 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 August 16, 2018. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 14 69 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 17 71 5. CoAP Pub/sub Operation with Resource Directory . . . . . . . 18 72 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 19 73 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 19 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 75 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 76 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 21 77 9.2. Resource Type value 'core.ps.discover' . . . . . . . . . 21 78 9.3. Response Code value '2.07' . . . . . . . . . . . . . . . 21 79 9.4. Response Code value '4.29' . . . . . . . . . . . . . . . 21 80 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 81 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 82 11.1. Normative References . . . . . . . . . . . . . . . . . . 22 83 11.2. Informative References . . . . . . . . . . . . . . . . . 23 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 86 1. Introduction 88 The Constrained Application Protocol (CoAP) [RFC7252] supports 89 machine-to-machine communication across networks of constrained 90 devices. CoAP uses a request/response model where clients make 91 requests to servers in order to request actions on resources. 92 Depending on the situation the same device may act either as a server 93 or a client. 95 One important class of constrained devices includes devices that are 96 intended to run for years from a small battery, or by scavenging 97 energy from their environment. These devices have limited 98 reachability because they spend most of their time in a sleeping 99 state with no network connectivity. Devices may also have limited 100 reachability due to certain middle-boxes, such as Network Address 101 Translators (NATs) or firewalls. Such middle-boxes often prevent 102 connecting to a device from the Internet unless the connection was 103 initiated by the device. 105 This document specifies the means for nodes with limited reachability 106 to communicate using simple extensions to CoAP. The extensions 107 enable publish-subscribe communication using a broker node that 108 enables store-and-forward messaging between two or more nodes. 109 Furthermore the extensions facilitate many-to-many communication 110 using CoAP. 112 2. Terminology 114 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 115 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 116 specification are to be interpreted as described in [RFC2119]. 118 This specification requires readers to be familiar with all the terms 119 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 120 should also be familiar with the terms and concepts discussed in 121 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 122 format [RFC6570] is used to describe the REST interfaces defined in 123 this specification. 125 This specification makes use of the following additional terminology: 127 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 128 published to a broker and potential receivers can subscribe to the 129 broker to receive messages. The publishers do not (need to) know 130 where the message will be eventually sent: the publications and 131 subscriptions are matched by a broker and publications are 132 delivered by the broker to subscribed receivers. 134 CoAP pub/sub service: A group of REST resources, as defined in this 135 document, which together implement the required features of this 136 specification. 138 CoAP pub/sub Broker: A server node capable of receiving messages 139 (publications) from and sending messages to other nodes, and able 140 to match subscriptions and publications in order to route messages 141 to the right destinations. The broker can also temporarily store 142 publications to satisfy future subscriptions and pending 143 notifications. 145 CoAP pub/sub Client: A CoAP client which is capable of publish or 146 subscribe operations as defined in this specification. 148 Topic: A unique identifier for a particular item being published 149 and/or subscribed to. A broker uses the topics to match 150 subscriptions to publications. A topic is a valid CoAP URI as 151 defined in [RFC7252] 153 3. Architecture 155 3.1. CoAP Pub/sub Architecture 157 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 158 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 159 sub REST API which is hosted by the Broker. State information is 160 updated between the Clients and the Broker. The CoAP pub/sub Broker 161 performs a store-and-forward of state update representations between 162 certain CoAP pub/sub Clients. Clients Subscribe to topics upon which 163 representations are Published by other Clients, which are forwarded 164 by the Broker to the subscribing clients. A CoAP pub/sub Broker may 165 be used as a REST resource proxy, retaining the last published 166 representation to supply in response to Read requests from Clients. 168 Clients pub/sub Broker 169 +-------+ | 170 | CoAP | | 171 |pub/sub|---------|------+ 172 |Client | | | +-------+ 173 +-------+ | +----| CoAP | 174 | |pub/sub| 175 +-------+ | +----|Broker | 176 | CoAP | | | +-------+ 177 |pub/sub|---------|------+ 178 |Client | | 179 +-------+ | 181 Figure 1: CoAP pub/sub Architecture 183 3.2. CoAP Pub/sub Broker 185 A CoAP pub/sub Broker is a CoAP Server that exposes a REST API for 186 clients to use to initiate publish-subscribe interactions. Avoiding 187 the need for direct reachability between clients, the broker only 188 needs to be reachable from all clients. The broker also needs to 189 have sufficient resources (storage, bandwidth, etc.) to host CoAP 190 resource services, and potentially buffer messages, on behalf of the 191 clients. 193 3.3. CoAP Pub/sub Client 195 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 196 CoAP pub/sub REST API defined in this document. Clients initiate 197 interactions with a CoAP pub/sub broker. A data source (e.g., sensor 198 clients) can publish state updates to the broker and data sinks 199 (e.g., actuator clients) can read from or subscribe to state updates 200 from the broker. Application clients can make use of both publish 201 and subscribe in order to exchange state updates with data sources 202 and data sinks. 204 3.4. CoAP Pub/sub Topic 206 The clients and broker use topics to identify a particular resource 207 or object in a publish-subscribe system. Topics are conventionally 208 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 209 "EP-33543/sen/3303/0/5700". The topics are hosted at the broker and 210 all the clients using the broker share the same namespace for topics. 211 Every CoAP pub/sub topic has a link, consisting of a reference path 212 on the broker using URI path [RFC3986] construction and link 213 attributes [RFC6690]. Every topic is associated with zero or more 214 stored representations with a content-format specified in the link. 215 A CoAP pub/sub topic value may alternatively be a collection of one 216 or more sub-topics, consisting of links to the sub-topic URIs and 217 indicated by a link-format content-format. 219 3.5. Brokerless Pub/sub 221 Figure 2 shows an arrangement for using CoAP pub/sub in a 222 "brokerless" configuration between peer nodes. Nodes in a brokerless 223 system may act as both broker and client. The Broker interface in a 224 brokerless node may be pre-configured with topics that expose 225 services and resources. Brokerless peer nodes can be mixed with 226 client and broker nodes in a system with full interoperability. 228 Peer pub/sub Peer 229 +-------+ | +-------+ 230 | CoAP | | | CoAP | 231 |pub/sub|---------|---------|pub/sub| 232 |Client | | |Broker | 233 +-------+ | +-------+ 234 | CoAP | | | CoAP | 235 |pub/sub|---------|---------|pub/sub| 236 |Broker | | |Client | 237 +-------+ | +-------+ 239 Figure 2: Brokerless pub/sub 241 4. CoAP Pub/sub REST API 243 This section defines the REST API exposed by a CoAP pub/sub Broker to 244 pub/sub Clients. The examples throughout this section assume the use 245 of CoAP [RFC7252]. A CoAP pub/sub Broker implementing this 246 specification SHOULD support the DISCOVERY, CREATE, PUBLISH, 247 SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this 248 section. Optimized implementations MAY support a subset of the 249 operations as required by particular constrained use cases. 251 4.1. DISCOVERY 253 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 254 Simple Discovery or through a Resource Directory (RD) 255 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 256 indicate its presence and availability on a network by exposing a 257 link to the entry point of its pub/sub API at its .well-known/core 258 location [RFC6690]. A CoAP pub/sub broker MAY register its pub/sub 259 REST API entry point with a Resource Directory. Figure 3 shows an 260 example of a client discovering a local pub/sub API using CoAP Simple 261 Discovery. A broker wishing to advertise the CoAP pub/sub API for 262 Simple Discovery or through a Resource Directory MUST use the link 263 relation rt=core.ps. A broker MAY advertise its supported content 264 formats and other attributes in the link to its pub/sub API. 266 A CoAP pub/sub Broker MAY offer a topic discovery entry point to 267 enable Clients to find topics of interest, either by topic name or by 268 link attributes which may be registered when the topic is created. 269 Figure 4 shows an example of a client looking for a topic with a 270 resource type (rt) of "temperature" using Discover. The client then 271 receives the URI of the resource and its content-format. A pub/sub 272 broker wishing to advertize topic discovery MUST use the relation 273 rt=core.ps.discover in the link. 275 A CoAP pub/sub Broker MAY expose the Discover interface through the 276 .well-known/core resource. Links to topics may be exposed at .well- 277 known/core in addition to links to the pub/sub API. Figure 5 shows 278 an example of topic discovery through .well-known/core. 280 The DISCOVER interface is specified as follows: 282 Interaction: Client -> Broker 284 Method: GET 286 URI Template: {+ps}/{+topic}{?q*} 287 URI Template Variables: ps := Pub/sub REST API entry point 288 (optional). The entry point of the pub/sub REST API, as obtained 289 from discovery, used to discover topics. 291 topic := The desired topic to return links for (optional). 293 q := Query Filter (optional). MAY contain a query filter list as 294 per [RFC6690] Section 4.1. 296 Content-Format: application/link-format 298 The following response codes are defined for this interface: 300 Success: 2.05 "Content" with an application/link-format payload 301 containing one or more matching entries for the broker resource. 302 A pub/sub broker SHOULD use the value "/ps/" for the base URI of 303 the pub/sub API wherever possible. 305 Failure: 4.04 "Not Found" is returned in case no matching entry is 306 found for a unicast request. 308 Failure: 4.00 "Bad Request" is returned in case of a malformed 309 request for a unicast request. 311 Failure: No error response to a multicast request. 313 Client Broker 314 | | 315 | ------ GET /.well-known/core?rt=core.ps ---->>| 316 | -- Content-Format: application/link-format ---| 317 | | 318 | <<--- 2.05 Content | 319 | ;rt=core.ps;rt=core.ps.discover;ct=40 --| 320 | | 322 Figure 3: Example of DISCOVER pub/sub function 324 Client Broker 325 | | 326 | ---------- GET /ps/?rt="temperature" ------->>| 327 | Content-Format: application/link-format | 328 | | 329 | <<-- 2.05 Content | 330 | ;rt="temperature";ct=50 ---| 331 | | 333 Figure 4: Example of DISCOVER topic 335 Client Broker 336 | | 337 | -------- GET /.well-known/core?ct=50 ------->>| 338 | Content-Format: application/link-format | 339 | | 340 | <<-- 2.05 Content | 341 | ;rt="temperature";ct=50 ---| 342 | | 344 Figure 5: Example of DISCOVER topic 346 4.2. CREATE 348 A CoAP pubsub broker SHOULD allow Clients to create new topics on the 349 broker using CREATE. Some exceptions are for fixed brokerless 350 devices and pre-configured brokers in dedicated installations. A 351 client wishing to create a topic MUST use CoAP POST to the pubsub API 352 with a payload indicating the desired topic. The topic specification 353 sent in the payload MUST use a supported serialization of the CoRE 354 link format [RFC6690]. The target of the link MUST be a URI 355 formatted string. The client MUST indicate the desired content 356 format for publishes to the topic by using the ct (Content Format) 357 link attribute in the link-format payload. The client MAY indicate 358 the lifetime of the topic by including the Max-Age option in the 359 CREATE request. 361 A Broker MUST return a response code of "2.01 Created" if the topic 362 is created and return the URI path of the created topic via Location- 363 Path options. The broker MUST return the appropriate 4.xx response 364 code indicating the reason for failure if a new topic can not be 365 created. Broker SHOULD remove topics if the Max-Age of the topic is 366 exceeded without any publishes to the topic. Broker SHOULD retain a 367 topic indefinitely if the Max-Age option is elided or is set to zero 368 upon topic creation. The lifetime of a topic MUST be refreshed upon 369 create operations with a target of an existing topic. 371 Topics may be created as sub-topics of other topics. A client MAY 372 create a topic with a ct (Content Format) link attribute value which 373 describes a supported serialization of the CoRE link format [RFC6690] 374 such as application/link-format (ct=40) or its JSON or CBOR 375 serializations. If a topic is created which describes a link 376 serialization, that topic may then have sub-topics created under it 377 as shown in Figure 7. 379 The CREATE interface is specified as follows: 381 Interaction: Client -> Broker 383 Method: POST 385 URI Template: {+ps}/{+topic}{?q*} 387 URI Template Variables: ps := Pub/sub REST API entry point 388 (optional). The entry point of the pub/sub REST API, as obtained 389 from discovery, used to discover topics. 391 topic := The desired topic to return links for (optional). 393 q := Query Filter (optional). MAY contain a query filter list as 394 per [RFC6690] Section 4.1. 396 Content-Format: application/link-format 398 Payload: The desired topic to CREATE 400 The following response codes are defined for this interface: 402 Success: 2.01 "Created". Successful Creation of the topic 404 Failure: 4.00 "Bad Request". Malformed request. 406 Failure: 4.01 "Unauthorized". Authorization failure. 408 Failure: 4.03 "Forbidden". Topic already exists. 410 Failure: 4.06 "Not Acceptable". Unsupported content format for 411 topic. 413 Figure 6 shows an example of a topic called "topic1" being 414 successfully created. 416 Client Broker 417 | | 418 | ---------- POST /ps/ ";ct=50" -------->| 419 | | 420 | <---------------- 2.01 Created ---------------| 421 | Location: /ps/topic1 | 422 | | 424 Figure 6: Example of CREATE topic 426 Client Broker 427 | | 428 | ------- POST /ps/ ";ct=40" ------->| 429 | | 430 | <---------------- 2.01 Created ---------------| 431 | Location: /ps/mainTopic/ | 432 | | 433 | --- POST /ps/mainTopic/ ";ct=50" -->| 434 | | 435 | <---------------- 2.01 Created ---------------| 436 | Location: /ps/mainTopic/subTopic | 437 | | 438 | | 440 Figure 7: Example of CREATE sub-topic 442 4.3. PUBLISH 444 A CoAP pub/sub broker MAY allow clients to PUBLISH to topics on the 445 broker. A client MAY use the PUT or the POST method to publish state 446 updates to the CoAP pub/sub Broker. A client MUST use the content 447 format specified upon creation of a given topic to publish updates to 448 that topic. The broker MUST reject publish operations which do not 449 use the specified content format. A CoAP client publishing on a 450 topic MAY indicate the maximum lifetime of the value by including the 451 Max-Age option in the publish request. The broker MUST return a 452 response code of "2.04 Changed" if the publish is accepted. A Broker 453 MAY return a "4.04 Not Found" if the topic does not exist. A broker 454 MAY return "4.29 Too Many Requests" if simple flow control as 455 described in Section 7 is implemented. 457 A Broker MUST accept PUBLISH operations using the PUT method. 458 PUBLISH operations using the PUT method replace any stored 459 representation associated with the topic, with the supplied 460 representation. A Broker MAY reject, or delay responses to, PUT 461 requests to a topic while pending resolution of notifications to 462 subscribers from previous PUT requests. 464 Create on PUBLISH: A Broker MAY accept PUBLISH operations to new 465 topics using the PUT method. If a Broker accepts a PUBLISH using PUT 466 to a topic that does not exist, the Broker MUST create the topic 467 using the information in the PUT operation. The Broker MUST create a 468 topic with the URI-Path of the request, including all of the sub- 469 topics necessary, and create a topic link with the ct attribute set 470 to the content-format of the payload of the PUT request. If topic is 471 created, the Broker MUST return the response "2.01 Created" with the 472 URI of the created topic, including all of the created path segments, 473 returned via the Location-Path option. 475 A Broker MAY accept PUBLISH operations using the POST method. If a 476 broker accepts PUBLISH using POST it shall respond with the 2.04 477 Changed status code. 479 A Broker MAY perform garbage collection of stored representations 480 which have been delivered to all subscribers or which have timed out. 481 A Broker MAY retain at least one most recently published 482 representation to return in response to SUBSRCIBE and READ requests. 484 A Broker MUST make a best-effort attempt to notify all clients 485 subscribed on a particular topic each time it receives a publish on 486 that topic. An example is shown in Figure 10. If a client publishes 487 to a broker with the Max-Age option, the broker MUST include the same 488 value for the Max-Age option in all notifications. A broker MUST use 489 CoAP Notification as described in [RFC7641] to notify subscribed 490 clients. 492 The PUBLISH interface is specified as follows: 494 Interaction: Client -> Broker 496 Method: PUT, POST 498 URI Template: {+ps}/{+topic}{?q*} 500 URI Template Variables: ps := Pub/sub REST API entry point 501 (optional). The entry point of the pub/sub REST API, as obtained 502 from discovery, used to discover topics. 504 topic := The desired topic to return links for (optional). 506 q := Query Filter (optional). MAY contain a query filter list as 507 per [RFC6690] Section 4.1. 509 Content-Format: Any valid CoAP content format 511 Payload: Representation of the topic value (CoAP resource state 512 representation) in the indicated content format 514 The following response codes are defined for this interface: 516 Success: 2.01 "Created". Successful publish, topic is created 518 Success: 2.04 "Changed". Successful publish, topic is updated 520 Failure: 4.00 "Bad Request". Malformed request. 522 Failure: 4.01 "Unauthorized". Authorization failure. 524 Failure: 4.04 "Not Found". Topic does not exist. 526 Failure: 4.29 "Too Many Requests". The client should slow down the 527 rate of publish messages for this topic (see Section 7). 529 Figure 8 shows an example of a new value being successfully published 530 to the topic "topic1". See Figure 10 for an example of a broker 531 forwarding a message from a publishing client to a subscribed client. 533 Client Broker 534 | | 535 | ---------- PUT /ps/topic1 "1033.3" --------> | 536 | | 537 | | 538 | <--------------- 2.04 Changed---------------- | 539 | | 541 Figure 8: Example of PUBLISH 543 Client Broker 544 | | 545 | -------- PUT /ps/exa/mpl/e "1033.3" -------> | 546 | | 547 | | 548 | <--------------- 2.01 Created---------------- | 549 | Location: /ps/exa/mpl/e | 550 | | 552 Figure 9: Example of CREATE on PUBLISH 554 4.4. SUBSCRIBE 556 A CoAP pub/sub broker MAY allow Clients to subscribe to topics on the 557 Broker using CoAP Observe as described in [RFC7641]. A CoAP pub/sub 558 Client wishing to Subscribe to a topic on a broker MUST use a CoAP 559 GET with the Observe option set to 0 (zero). The Broker MAY add the 560 client to a list of observers. The Broker MUST return a response 561 code of "2.05 Content" along with the most recently published value 562 if the topic contains a valid value and the broker can supply the 563 requested content format. The broker MUST reject Subscribe requests 564 on a topic if the content format of the request is not supported by 565 the content format the topic was created with. The broker MAY accept 566 Subscribe requests which specify content formats that the broker can 567 supply as alternate content formats to the content format the topic 568 was registered with. If the topic was published with the Max-Age 569 option, the broker MUST set the Max-Age option in the valid response 570 to the amount of time remaining for the value to be valid since the 571 last publish operation on that topic. The Broker MUST return a 572 response code of "2.07 No Content" if the Max-Age of the previously 573 stored value has expired. The Broker MUST return a response code 574 "4.04 Not Found" if the topic does not exist or has been removed. 575 The Broker MUST return a response code "4.15 Unsupported Content 576 Format" if it can not return the requested content format. If a 577 Broker is unable to accept a new Subscription on a topic, it SHOULD 578 return the appropriate response code without the Observe option as 579 per as per [RFC7641] Section 4.1. There is no explicit maximum 580 lifetime of a Subscription, thus a Broker may remove subscribers at 581 any time. The Broker, upon removing a Subscriber, will transmit the 582 appropriate response code without the Observe option, as per 583 [RFC7641] Section 4.2, to the removed Subscriber. 585 The SUBSCRIBE interface is specified as follows: 587 Interaction: Client -> Broker 589 Method: GET 591 Options: Observe:0 593 URI Template: {+ps}/{+topic}{?q*} 595 URI Template Variables: ps := Pub/sub REST API entry point 596 (optional). The entry point of the pub/sub REST API, as obtained 597 from discovery, used to discover topics. 599 topic := The desired topic to return links for (optional). 601 q := Query Filter (optional). MAY contain a query filter list as 602 per [RFC6690] Section 4.1. 604 The following response codes are defined for this interface: 606 Success: 2.05 "Content". Successful subscribe, current value 607 included 609 Success: 2.07 "No Content". Successful subscribe, value not 610 included 612 Failure: 4.00 "Bad Request". Malformed request. 614 Failure: 4.01 "Unauthorized". Authorization failure. 616 Failure: 4.04 "Not Found". Topic does not exist. 618 Failure: 4.15 "Unsupported Content Format". Unsupported content 619 format. 621 Figure 10 shows an example of Client2 subscribing to "topic1" and 622 receiving a response from the broker, with a subsequent notification. 623 The subscribe response from the broker uses the last stored value 624 associated with the topic1. The notification from the broker is sent 625 in response to the publish received from Client1. 627 Client1 Client2 Broker 628 | | Subscribe | 629 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 630 | | | 631 | | <---------- 2.05 Content Observe:10---------- | 632 | | | 633 | | | 634 | | Publish | 635 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 636 | | Notify | 637 | | <---------- 2.05 Content Observe:11 --------- | 638 | | | 640 Figure 10: Example of SUBSCRIBE 642 4.5. UNSUBSCRIBE 644 If a CoAP pub/sub broker allows clients to SUBSCRIBE to topics on the 645 broker, it MUST allow Clients to unsubscribe from topics on the 646 Broker using the CoAP Cancel Observation operation. A CoAP pub/sub 647 Client wishing to unsubscribe to a topic on a Broker MUST either use 648 CoAP GET with Observe using an Observe parameter of 1 or send a CoAP 649 Reset message in response to a publish, as per [RFC7641]. 651 The UNSUBSCRIBE interface is specified as follows: 653 Interaction: Client -> Broker 655 Method: GET 657 Options: Observe:1 659 URI Template: {+ps}/{+topic}{?q*} 661 URI Template Variables: ps := Pub/sub REST API entry point 662 (optional). The entry point of the pub/sub REST API, as obtained 663 from discovery, used to discover topics. 665 topic := The desired topic to return links for (optional). 667 q := Query Filter (optional). MAY contain a query filter list as 668 per [RFC6690] Section 4.1. 670 The following response codes are defined for this interface: 672 Success: 2.05 "Content". Successful unsubscribe, current value 673 included 675 Success: 2.07 "No Content". Successful unsubscribe, value not 676 included 678 Failure: 4.00 "Bad Request". Malformed request. 680 Failure: 4.01 "Unauthorized". Authorization failure. 682 Failure: 4.04 "Not Found". Topic does not exist. 684 Figure 11 shows an example of a client unsubscribe using the 685 Observe=1 cancellation method. 687 Client Broker 688 | | 689 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 690 | | 691 | <------------- 2.05 Content ----------------- | 692 | | 694 Figure 11: Example of UNSUBSCRIBE 696 4.6. READ 698 A CoAP pub/sub broker MAY accept Read requests on a topic using the 699 the CoAP GET method if the content format of the request matches the 700 content format the topic was created with. The broker MAY accept 701 Read requests which specify content formats that the broker can 702 supply as alternate content formats to the content format the topic 703 was registered with. The Broker MUST return a response code of "2.05 704 Content" along with the most recently published value if the topic 705 contains a valid value and the broker can supply the requested 706 content format. If the topic was published with the Max-Age option, 707 the broker MUST set the Max-Age option in the valid response to the 708 amount of time remaining for the topic to be valid since the last 709 publish. The Broker MUST return a response code of "2.07 No Content" 710 if the Max-Age of the previously stored value has expired. The 711 Broker MUST return a response code "4.04 Not Found" if the topic does 712 not exist or has been removed. The Broker MUST return a response 713 code "4.15 Unsupported Content Format" if the broker can not return 714 the requested content format. 716 The READ interface is specified as follows: 718 Interaction: Client -> Broker 720 Method: GET 722 URI Template: {+ps}/{+topic}{?q*} 724 URI Template Variables: ps := Pub/sub REST API entry point 725 (optional). The entry point of the pub/sub REST API, as obtained 726 from discovery, used to discover topics. 728 topic := The desired topic to return links for (optional). 730 q := Query Filter (optional). MAY contain a query filter list as 731 per [RFC6690] Section 4.1. 733 The following response codes are defined for this interface: 735 Success: 2.05 "Content". Successful READ, current value included 737 Success: 2.07 "No Content". Topic exists, value not included 739 Failure: 4.00 "Bad Request". Malformed request. 741 Failure: 4.01 "Unauthorized". Authorization failure. 743 Failure: 4.04 "Not Found". Topic does not exist. 745 Failure: 4.15 "Unsupported Content Format". Unsupported content- 746 format. 748 Figure 12 shows an example of a successful READ from topic1, followed 749 by a Publish on the topic, followed at some time later by a read of 750 the updated value from the recent Publish. 752 Client1 Client2 Broker 753 | | Read | 754 | | --------------- GET /ps/topic1 -------------> | 755 | | | 756 | | <---------- 2.05 Content "1007.1"------------ | 757 | | | 758 | | | 759 | | Publish | 760 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 761 | | | 762 | | | 763 | | Read | 764 | | --------------- GET /ps/topic1 -------------> | 765 | | | 766 | | <----------- 2.05 Content "1033.3" ---------- | 767 | | | 769 Figure 12: Example of READ 771 4.7. REMOVE 773 A CoAP pub/sub broker MAY allow clientsremove a topics from the 774 broker using the CoAP Delete method on the URI of the topic. The 775 CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is 776 successful. The broker MUST return the appropriate 4.xx response 777 code indicating the reason for failure if the topic can not be 778 removed. When a topic is removed for any reason, the Broker SHOULD 779 return the response code 4.04 Not Found and remove all of the 780 observers from the list of observers as per as per [RFC7641] 781 Section 3.2. If a topic which has sub-topics is removed, then all of 782 its sub-topics MUST be recursively removed. 784 The REMOVE interface is specified as follows: 786 Interaction: Client -> Broker 788 Method: DELETE 790 URI Template: {+ps}/{+topic}{?q*} 791 URI Template Variables: ps := Pub/sub REST API entry point 792 (optional). The entry point of the pub/sub REST API, as obtained 793 from discovery, used to discover topics. 795 topic := The desired topic to return links for (optional). 797 q := Query Filter (optional). MAY contain a query filter list as 798 per [RFC6690] Section 4.1. 800 Content-Format: None 802 Response Payload: None 804 The following response codes are defined for this interface: 806 Success: 2.02 "Deleted". Successful remove 808 Failure: 4.00 "Bad Request". Malformed request. 810 Failure: 4.01 "Unauthorized". Authorization failure. 812 Failure: 4.04 "Not Found". Topic does not exist. 814 Figure 13 shows a successful remove of topic1. 816 Client Broker 817 | | 818 | ------------- DELETE /ps/topic1 ------------> | 819 | | 820 | | 821 | <-------------- 2.02 Deleted ---------------- | 822 | | 824 Figure 13: Example of REMOVE 826 5. CoAP Pub/sub Operation with Resource Directory 828 A CoAP pub/sub Broker may register the base URI, which is the REST 829 API entry point for a pub/sub service, with a Resource Directory. A 830 pub/sub Client may use an RD to discover a pub/sub Broker. 832 A CoAP pub/sub Client may register links [RFC6690] with a Resource 833 Directory to enable discovery of created pub/sub topics. A pub/sub 834 Client may use an RD to discover pub/sub Topics. A client which 835 registers pub/sub Topics with an RD MUST use the context relation 836 (con) [I-D.ietf-core-resource-directory] to indicate that the context 837 of the registered links is the pub/sub Broker. 839 A CoAP pub/sub Broker may alternatively register links to its topics 840 to a Resource Directory by triggering the RD to retrieve it's links 841 from .well-known/core. In order to use this method, the links must 842 first be exposed in the .well-known/core of the pub/sub broker. See 843 Section 4.1 in this document. 845 The pub/sub broker triggers the RD to retrieve its links by sending a 846 POST with an empty payload to the .well-known/core of the Resource 847 Directory. The RD server will then retrieve the links from the 848 .well-known/core of the pub/sub broker and incorporate them into the 849 Resource Directory. See [I-D.ietf-core-resource-directory] for 850 further details. 852 6. Sleep-Wake Operation 854 CoAP pub/sub provides a way for client nodes to sleep between 855 operations, conserving energy during idle periods. This is made 856 possible by shifting the server role to the broker, allowing the 857 broker to be always-on and respond to requests from other clients 858 while a particular client is sleeping. 860 For example, the broker will retain the last state update received 861 from a sleeping client, in order to supply the most recent state 862 update to other clients in response to read and subscribe operations. 864 Likewise, the broker will retain the last state update received on 865 the topic such that a sleeping client, upon waking, can perform a 866 read operation to the broker to update its own state from the most 867 recent system state update. 869 7. Simple Flow Control 871 Since the broker node has to potentially send a large amount of 872 notification messages for each publish message and it may be serving 873 a large amount of subscribers and publishers simultaneously, the 874 broker may become overwhelmed if it receives many publish messages to 875 popular topics in a short period of time. 877 If the broker is unable to serve a certain client that is sending 878 publish messages too fast, the broker MUST respond with Response Code 879 4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too 880 Many Requests" but uses the Max-Age Option in place of the "Retry- 881 After" header field to indicate the number of seconds after which to 882 retry. The broker MAY stop creating notifications from the publish 883 messages from this client and to this topic for the indicated time. 885 If a client receives the 4.29 Response Code from the broker for a 886 publish message to a topic, it MUST NOT send new publish messages to 887 the broker on the same topic before the time indicated in Max-Age has 888 passed. 890 8. Security Considerations 892 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 893 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 894 therefore the security considerations of those documents also apply 895 to this specification. Additionally, a CoAP pub/sub broker and the 896 clients SHOULD authenticate each other and enforce access control 897 policies. A malicious client could subscribe to data it is not 898 authorized to or mount a denial of service attack against the broker 899 by publishing a large number of resources. The authentication can be 900 performed using the already standardized DTLS offered mechanisms, 901 such as certificates. DTLS also allows communication security to be 902 established to ensure integrity and confidentiality protection of the 903 data exchanged between these relevant parties. Provisioning the 904 necessary credentials, trust anchors and authorization policies is 905 non-trivial and subject of ongoing work. 907 The use of a CoAP pub/sub broker introduces challenges for the use of 908 end-to-end security between for example a client device on a sensor 909 network and a client application running in a cloud-based server 910 infrastructure since brokers terminate the exchange. While running 911 separate DTLS sessions from the client device to the broker and from 912 broker to client application protects confidentially on those paths, 913 the client device does not know whether the commands coming from the 914 broker are actually coming from the client application. Similarly, a 915 client application requesting data does not know whether the data 916 originated on the client device. For scenarios where end-to-end 917 security is desirable the use of application layer security is 918 unavoidable. Application layer security would then provide a 919 guarantee to the client device that any request originated at the 920 client application. Similarly, integrity protected sensor data from 921 a client device will also provide guarantee to the client application 922 that the data originated on the client device itself. The protected 923 data can also be verified by the intermediate broker ensuring that it 924 stores/caches correct request/response and no malicious messages/ 925 requests are accepted. The broker would still be able to perform 926 aggregation of data/requests collected. 928 Depending on the level of trust users and system designers place in 929 the CoAP pub/sub broker, the use of end-to-end object security is 930 RECOMMENDED as described in [I-D.palombini-ace-coap-pubsub-profile]. 931 When only end-to-end encryption is necessary and the CoAP Broker is 932 trusted, Payload Only Protection (Mode:PAYL) could be used. The 933 Publisher would wrap only the payload before sending it to the broker 934 and set the option Content-Format to application/smpayl. Upon 935 receival, the Broker can read the unencrypted CoAP header to forward 936 it to the subscribers. 938 9. IANA Considerations 940 This document registers one attribute value in the Resource Type 941 (rt=) registry established with [RFC6690] and appends to the 942 definition of one CoAP Response Code in the CoRE Parameters Registry. 944 9.1. Resource Type value 'core.ps' 946 o Attribute Value: core.ps 948 o Description: Section 4 of [[This document]] 950 o Reference: [[This document]] 952 o Notes: None 954 9.2. Resource Type value 'core.ps.discover' 956 o Attribute Value: core.ps.discover 958 o Description: Section 4 of [[This document]] 960 o Reference: [[This document]] 962 o Notes: None 964 9.3. Response Code value '2.07' 966 o Response Code: 2.07 968 o Description: Add No Content response to GET to the existing 969 definition of the 2.07 response code. 971 o Reference: [[This document]] 973 o Notes: The server sends this code to the client to indicate that 974 the request was valid and accepted, but the responce may contain 975 an empty payload. It is comparable to and may be proxied with the 976 http 204 No Content status code. 978 9.4. Response Code value '4.29' 980 o Response Code: 4.29 981 o Description: This error code is used by a server to indicate that 982 a client is making too many requests on a resource. 984 o Reference: [[This document]] 986 o Notes: None 988 10. Acknowledgements 990 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 991 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 992 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 993 and reviews. 995 11. References 997 11.1. Normative References 999 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1000 Requirement Levels", BCP 14, RFC 2119, 1001 DOI 10.17487/RFC2119, March 1997, . 1004 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1005 Resource Identifier (URI): Generic Syntax", STD 66, 1006 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1007 . 1009 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1010 and D. Orchard, "URI Template", RFC 6570, 1011 DOI 10.17487/RFC6570, March 2012, . 1014 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1015 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1016 . 1018 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1019 Application Protocol (CoAP)", RFC 7252, 1020 DOI 10.17487/RFC7252, June 2014, . 1023 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1024 Application Protocol (CoAP)", RFC 7641, 1025 DOI 10.17487/RFC7641, September 2015, . 1028 11.2. Informative References 1030 [I-D.ietf-core-resource-directory] 1031 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1032 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1033 resource-directory-12 (work in progress), October 2017. 1035 [I-D.palombini-ace-coap-pubsub-profile] 1036 Palombini, F., "CoAP Pub-Sub Profile for Authentication 1037 and Authorization for Constrained Environments (ACE)", 1038 draft-palombini-ace-coap-pubsub-profile-01 (work in 1039 progress), September 2017. 1041 [I-D.selander-ace-object-security] 1042 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1043 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 1044 object-security-06 (work in progress), October 2016. 1046 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1047 DOI 10.17487/RFC5988, October 2010, . 1050 Authors' Addresses 1052 Michael Koster 1053 SmartThings 1055 Email: Michael.Koster@smartthings.com 1057 Ari Keranen 1058 Ericsson 1060 Email: ari.keranen@ericsson.com 1062 Jaime Jimenez 1063 Ericsson 1065 Email: jaime.jimenez@ericsson.com