idnits 2.17.1 draft-koster-core-coap-pubsub-04.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 : ---------------------------------------------------------------------------- No issues found here. 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 (November 5, 2015) is 3093 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-05 == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-03 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 4 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 ARM Limited 4 Intended status: Standards Track A. Keranen 5 Expires: May 8, 2016 J. Jimenez 6 Ericsson 7 November 5, 2015 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-koster-core-coap-pubsub-04 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 May 8, 2016. 38 Copyright Notice 40 Copyright (c) 2015 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 4. CoAP pub/sub Function Set . . . . . . . . . . . . . . . . . . 5 63 4.1. DISCOVER . . . . . . . . . . . . . . . . . . . . . . . . 5 64 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 14 69 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 15 70 5. CoAP pub/sub Operation with Resource Directory . . . . . . . 16 71 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 17 72 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 17 73 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 74 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 75 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 19 76 9.2. Response Code value '2.04' . . . . . . . . . . . . . . . 19 77 9.3. Response Code value '4.29' . . . . . . . . . . . . . . . 19 78 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 79 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 80 11.1. Normative References . . . . . . . . . . . . . . . . . . 20 81 11.2. Informative References . . . . . . . . . . . . . . . . . 20 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 84 1. Introduction 86 The Constrained Application Protocol (CoAP) [RFC7252] supports 87 machine-to-machine communication across networks of constrained 88 devices. CoAP uses a request/response model where clients make 89 requests to servers in order to request actions on resources. 90 Depending on the situation the same device may act either as a server 91 or a client. 93 One important class of constrained devices includes devices that are 94 intended to run for years from a small battery, or by scavenging 95 energy from their environment. These devices have limited 96 reachability because they spend most of their time in a sleeping 97 state with no network connectivity. Devices may also have limited 98 reachability due to certain middle-boxes, such as Network Address 99 Translators (NATs) or firewalls. Such middle-boxes often prevent 100 connecting to a device from the Internet unless the connection was 101 initiated by the device. 103 This document specifies the means for nodes with limited reachability 104 to communicate using simple extensions to CoAP. The extensions 105 enable publish-subscribe communication using a broker node that 106 enables store-and-forward messaging between two or more nodes. 107 Furthermore the extensions facilitate many-to-many communication 108 using CoAP. 110 2. Terminology 112 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 113 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 114 specification are to be interpreted as described in [RFC2119]. 116 This specification requires readers to be familiar with all the terms 117 and concepts that are discussed in [RFC5988] and [RFC6690]. Readers 118 should also be familiar with the terms and concepts discussed in 119 [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template 120 format [RFC6570] is used to describe the REST interfaces defined in 121 this specification. 123 This specification makes use of the following additional terminology: 125 Publish-Subscribe (pub/sub): A messaging paradigm where messages are 126 published to a broker and potential receivers can subscribe to the 127 broker to receive messages. The publishers do not (need to) know 128 where the message will be eventually sent: the publications and 129 subscriptions are matched by a broker and publications are 130 delivered by the broker to subscribed receivers. 132 CoAP pub/sub function set: A group of well-known REST resources that 133 together provide the CoAP pub/sub service. 135 CoAP pub/sub Broker: A server node capable of receiving messages 136 (publications) from and sending messages to other nodes, and able 137 to match subscriptions and publications in order to route messages 138 to the right destinations. The broker can also temporarily store 139 publications to satisfy future subscriptions. 141 CoAP pub/sub Client: A CoAP client that implements the CoAP pub/sub 142 function set. 144 Topic: A unique identifier for a particular item being published 145 and/or subscribed to. A broker uses the topics to match 146 subscriptions to publications. 148 3. Architecture 150 3.1. CoAP pub/sub Architecture 152 Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ 153 sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ 154 sub interface which is hosted by the Broker. State information is 155 updated between the Clients and the Broker. The CoAP pub/sub Broker 156 performs a store-and-forward function of state updates between 157 certain CoAP pub/sub Clients. Clients Subscribe to state updates 158 which are Published by other Clients, and which are forwarded by the 159 Broker to the subscribing clients. The CoAP pub/sub Broker also acts 160 as a REST proxy, retaining the last state update provided by clients 161 to supply in response to Read requests from Clients. 163 Clients pub/sub Broker 164 +-------+ | 165 | CoAP | | 166 |pub/sub|---------|------+ 167 |Client | | | +-------+ 168 +-------+ | +----| CoAP | 169 | |pub/sub| 170 +-------+ | +----|Broker | 171 | CoAP | | | +-------+ 172 |pub/sub|---------|------+ 173 |Client | | 174 +-------+ | 176 Figure 1: CoAP pub/sub Architecture 178 3.2. CoAP pub/sub Broker 180 A CoAP pub/sub Broker is a CoAP Server that exposes an interface for 181 clients to use to initiate publish-subscribe interactions. Unlike 182 clients, the broker needs to be reachable by all clients. The broker 183 also needs to have sufficient resources (storage, bandwidth, etc.) to 184 host CoAP resources, and potentially buffer messages, on behalf of 185 the clients. 187 3.3. CoAP pub/sub Client 189 A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the 190 CoAP pub/sub interface. Clients initiate all interactions with the 191 CoAP pub/sub broker. A data source (e.g., sensor clients) can 192 publish state updates to the broker and data sinks (e.g., actuator 193 clients) can read from or subscribe to state updates from the broker. 194 Application clients can make use of both publish and subscribe in 195 order to exchange state updates with data sources and sinks. 197 3.4. CoAP pub/sub Topic 199 The clients and broker use topics to identify a particular resource 200 or object in a publish-subscribe system. Topics are conventionally 201 formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or 202 "EP-33543/sen/3303/0/5700". The topics are hosted at the broker and 203 all the clients using the broker share the same namespace for topics. 204 A CoAP pub/sub topic has a reference path using URI path [RFC3986] 205 construction, link attributes [RFC6690], and a representation of a 206 value with specified content-formats. A CoAP pub/sub topic value may 207 alternatively be a collection of one or more sub-topics, consisting 208 of links to the sub-topic URIs and indicated by a link-format 209 content-format. 211 4. CoAP pub/sub Function Set 213 This section defines the interfaces between a CoAP pub/sub Broker and 214 pub/sub Clients, which is called the CoAP pub/sub Function Set. The 215 examples throughout this section assume the use of CoAP [RFC7252]. A 216 CoAP pub/sub Broker implementing this specification MUST support the 217 DISCOVER, CREATE, PUBLISH, SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE 218 operations defined in this section. 220 4.1. DISCOVER 222 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 223 Simple Discovery or through a Resource Directory (RD) 224 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 225 indicate its presence and availability on a network by exposing a 226 link to its pub/sub function set at its .well-known/core location 227 [RFC6690]. A CoAP pub/sub broker MAY register its pub/sub function 228 set location with a Resource Directory. Figure 2 shows an example of 229 a client discovering a local pub/sub Function Set using CoAP Simple 230 Discovery. A broker wishing to advertise the CoAP pub/sub Function 231 Set for Simple Discovery or through a Resource Directory MUST use the 232 link relation rt="core.ps". A broker MAY advertise it's supported 233 content formats and other attributes in the link to it's pub/sub 234 function set. 236 A CoAP pub/sub Broker MAY offer the Discover interface to enable 237 Clients to find topics of interest, either by topic name or by link 238 attributes which may be registered when the topic is created. 239 Figure 3 shows an example of a client looking for a topic with a 240 resource type (rt) of "temperature" in the pub/sub function set /ps 241 using the Discover interface. The client then receives the URI of 242 the resource and its content-format. 244 The DISCOVER interface is specified as follows: 246 Interaction: Client -> Broker 248 Method: GET 250 URI Template: /.well-known/core 252 URI Template: /{+ps/}{topic}{/topic*}{?q*} 254 URI Template Variables: 256 /.well-known/core := for discovering the pub/sub function set 257 (optional) 259 ps := pub/sub Function Set path (optional). The path of the 260 pub/sub Function Set, as obtained from discovery, used to 261 discover topics. 263 topic := The desired topic to return links for (optional). 265 q := Query Filter (optional). MAY contain a query filter list 266 as per [RFC6690] Section 4.1. 268 Content-Format: application/link-format 270 The following response codes are defined for this interface: 272 Success: 2.05 "Content" with an application/link-format payload 273 containing one or more matching entries for the broker resource. 274 A pub/sub broker SHOULD use the value "/ps/" for the function set 275 URI wherever possible. 277 Failure: 4.04 "Not Found" is returned in case no matching entry is 278 found for a unicast request. 280 Failure: 4.00 "Bad Request" is returned in case of a malformed 281 request for a unicast request. 283 Failure: No error response to a multicast request. 285 Client Broker 286 | | 287 | ------ GET /.well-known/core?rt=core.ps ----->| 288 | ---Content-Format: application/link-format----| 289 | | 290 | <--2.05 Content ";rt="core.ps";ct=40----| 291 | | 293 Figure 2: Example of DISCOVER pub/sub function 295 Client Broker 296 | | 297 | ---------- GET /ps/?rt="temperature" -------->| 298 | Content-Format: application/link-format | 299 | | 300 | <---2.05 Content | 301 | ;rt="temperature";ct=50 ---| 302 | | 304 Figure 3: Example of DISCOVER topic 306 4.2. CREATE 308 Clients create topics on the broker using the CREATE interface. A 309 client wishing to create a topic MUST use CoAP POST to the pub/sub 310 function set location with a payload indicating the desired topic. 311 The topic specification sent in the payload MUST use a supported 312 serialization of the CoRE link format [RFC6690]. The target of the 313 link MUST be a URI formatted string. The client MUST indicate the 314 desired content format for publishes to the topic by using the ct 315 (Content Format) link attribute in the link-format payload. The 316 client MAY indicate the lifetime of the topic by including the Max- 317 Age option in the CREATE request. Broker MUST return a response code 318 of "2.01 Created" if the topic is created and return the created 319 relative URI path via Location-Path options. The broker MUST return 320 the appropriate 4.xx response code indicating the reason for failure 321 if a new topic can not be created. Broker SHOULD remove topics if 322 the Max-Age of the topic is exceeded without any publishes to the 323 topic. Broker SHOULD retain a topic indefinitely if the Max-Age 324 option is elided or is set to zero upon topic creation. The lifetime 325 of a topic MUST be refreshed upon create operations with a target of 326 an existing topic. 328 Topics may be created as sub-topics of other topics. A client MAY 329 create a topic with a ct (Content Format) link attribute value which 330 describes a supported serialization of the CoRE link format [RFC6690] 331 such as application/link-format (ct=40) or its JSON or CBOR 332 serializations. If a topic is created which describes a link 333 serialization, that topic may then have sub-topics created under it 334 as shown in Figure 5. 336 The CREATE interface is specified as follows: 338 Interaction: Client -> Broker 340 Method: POST 342 URI Template: /{+ps/}{topic}{/topic*} 344 URI Template Variables: 346 ps := pub/sub Function Set path (mandatory). The path of the 347 pub/sub Function Set, as obtained from discovery. A pub/sub 348 broker SHOULD use the value "ps" for this variable whenever 349 possible. 351 Content-Format: application/link-format 353 Payload: The desired topic to CREATE 355 The following response codes are defined for this interface: 357 Success: 2.01 "Created". Successful Creation of the topic 359 Failure: 4.00 "Bad Request". Malformed request. 361 Failure: 4.01 "Unauthorized". Authorization failure. 363 Failure: 4.03 "Forbidden". Topic already exists. 365 Failure: 4.06 "Not Acceptable". Unsupported content format for 366 topic. 368 Figure 4 shows an example of a topic called "topic1" being 369 successfully created. 371 Client Broker 372 | | 373 | ---------- POST /ps ";ct=50" -------->| 374 | | 375 | <---------------- 2.01 Created ---------------| 376 | Location: /ps/topic1 | 377 | | 379 Figure 4: Example of CREATE topic 381 Client Broker 382 | | 383 | ------- POST /ps/ ";ct=40" ------->| 384 | | 385 | <---------------- 2.01 Created ---------------| 386 | Location: /ps/mainTopic/ | 387 | | 388 | --- POST /ps/mainTopic/ ";ct=50" -->| 389 | | 390 | <---------------- 2.01 Created ---------------| 391 | Location: /ps/mainTopic/subTopic | 392 | | 393 | | 395 Figure 5: Example of CREATE sub-topic 397 4.3. PUBLISH 399 A CoAP pub/sub Client uses the PUBLISH interface for updating topics 400 on the broker. The client MUST use the PUT method to publish state 401 updates to the CoAP pub/sub Broker. A client MUST use the content 402 format specified upon creation of a given topic to publish updates to 403 that topic. The broker MUST reject publish operations which do not 404 use the specified content format. A CoAP client publishing on a 405 topic MAY indicate the maximum lifetime of the value by including the 406 Max-Age option in the publish request. The broker MUST return a 407 response code of "2.04 Changed" if the publish is accepted or "4.04 408 Not Found" if the topic does not exist. A broker MAY return "4.29 409 Too Many Requests" if simple flow control as described in Section 7 410 is implemented. 412 The Broker MUST notify all clients subscribed on a particular topic 413 each time it receives a publish on that topic. An example is shown 414 in Figure 7. If a client publishes to a broker with the Max-Age 415 option, the broker MUST include the same value for the Max-Age option 416 in all notifications. A broker MUST use CoAP Notification as 417 described in [RFC7641] to notify subscribed clients. 419 The PUBLISH interface is specified as follows: 421 Interaction: Client -> Broker 423 Method: PUT 425 URI Template: /{+ps/}{topic}{/topic*} 427 URI Template Variables: 429 ps := pub/sub Function Set path (mandatory). The path of the 430 pub/sub Function Set, as obtained from discovery. 432 topic := The desired topic to publish on. 434 Content-Format: Any valid CoAP content format 436 Payload: Representation of the topic value (CoAP resource state 437 representation) in the indicated content format 439 The following response codes are defined for this interface: 441 Success: 2.04 "Changed". Successful publish, topic is updated 443 Failure: 4.00 "Bad Request". Malformed request. 445 Failure: 4.01 "Unauthorized". Authorization failure. 447 Failure: 4.04 "Not Found". Topic does not exist. 449 Failure: 4.29 "Too Many Requests". The client should slow down the 450 rate of publish messages for this topic (see Section 7). 452 Figure 6 shows an example of a new value being successfully published 453 to the topic "topic1". See Figure 7 for an example of a broker 454 forwarding a message from a publishing client to a subscribed client. 456 Client Broker 457 | | 458 | ---------- PUT /ps/topic1 "1033.3" --------> | 459 | | 460 | | 461 | <--------------- 2.04 Changed---------------- | 462 | | 464 Figure 6: Example of PUBLISH 466 4.4. SUBSCRIBE 468 CoAP pub/sub Clients subscribe to topics on the Broker using CoAP 469 Observe as described in [RFC7641]. A CoAP pub/sub Client wishing to 470 Subscribe to a topic on a broker MUST use a CoAP GET with Observe 471 registration. The Broker MAY add the client to a list of observers. 472 The Broker MUST return a response code of "2.05 Content" along with 473 the most recently published value if the topic contains a valid value 474 and the broker can supply the requested content format. The broker 475 MUST accept Subscribe requests on a topic if the content format of 476 the request matches the content format the topic was created with. 477 The broker MAY accept Subscribe requests which specify content 478 formats that the broker can supply as alternate content formats to 479 the content format the topic was registered with. If the topic was 480 published with the Max-Age option, the broker MUST set the Max-Age 481 option in the valid response to the amount of time remaining for the 482 value to be valid since the last publish operation on that topic. 483 The Broker MUST return a response code of "2.04 No Content" if the 484 Max-Age of the previously stored value has expired. The Broker MUST 485 return a response code "4.04 Not Found" if the topic does not exist 486 or has been removed. The Broker MUST return a response code "4.15 487 Unsupported Content Format" if it can not return the requested 488 content format. If a Broker is unable to accept a new Subscription 489 on a topic, it SHOULD return the appropriate response code without 490 the Observe option as per as per [RFC7641] Section 4.1. There is no 491 explicit maximum lifetime of a Subscription, thus a Broker may remove 492 subscribers at any time. The Broker, upon removing a Subscriber, 493 will transmit the appropriate response code without the Observe 494 option, as per [RFC7641] Section 4.2, to the removed Subscriber. 496 The SUBSCRIBE interface is specified as follows: 498 Interaction: Client -> Broker 500 Method: GET 502 Options: Observe:0 503 URI Template: /{+ps/}{topic}{/topic*} 505 URI Template Variables: 507 ps := pub/sub Function Set path (mandatory). The path of the 508 pub/sub Function Set, as obtained from discovery. 510 topic := The desired topic to subscribe to. 512 The following response codes are defined for this interface: 514 Success: 2.05 "Content". Successful subscribe, current value 515 included 517 Success: 2.04 "No Content". Successful subscribe, value not 518 included 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.15 "Unsupported Content Format". Unsupported content 527 format. 529 Figure 7 shows an example of Client2 subscribing to "topic1" and 530 receiving a response from the broker, with a subsequent notification. 531 The subscribe response from the broker uses the last stored value 532 associated with the topic1. The notification from the broker is sent 533 in response to the publish received from Client1. 535 Client1 Client2 Broker 536 | | Subscribe | 537 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 538 | | | 539 | | <---------- 2.05 Content Observe:10---------- | 540 | | | 541 | | | 542 | | Publish | 543 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 544 | | Notify | 545 | | <---------- 2.05 Content Observe:11---------- | 546 | | | 548 Figure 7: Example of SUBSCRIBE 550 4.5. UNSUBSCRIBE 552 CoAP pub/sub Clients unsubscribe from topics on the Broker using the 553 CoAP Cancel Observation operation. A CoAP pub/sub Client wishing to 554 unsubscribe to a topic on a Broker MUST either use CoAP GET with 555 Observe using an Observe parameter of 1 or send a CoAP Reset message 556 in response to a publish, as per [RFC7641]. 558 The UNSUBSCRIBE interface is specified as follows: 560 Interaction: Client -> Broker 562 Method: GET 564 Options: Observe:1 566 URI Template: /{+ps/}{topic}{/topic*} 568 URI Template Variables: 570 ps := pub/sub Function Set path (mandatory). The path of the 571 pub/sub Function Set, as obtained from discovery. 573 topic := The desired topic to unsubscribe from. 575 The following response codes are defined for this interface: 577 Success: 2.05 "Content". Successful unsubscribe, current value 578 included 580 Success: 2.04 "No Content". Successful unsubscribe, value not 581 included 583 Failure: 4.00 "Bad Request". Malformed request. 585 Failure: 4.01 "Unauthorized". Authorization failure. 587 Failure: 4.04 "Not Found". Topic does not exist. 589 Figure 8 shows an example of a client unsubscribe using the Observe=1 590 cancellation method. 592 Client Broker 593 | | 594 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 595 | | 596 | <------------- 2.05 Content ----------------- | 597 | | 599 Figure 8: Example of UNSUBSCRIBE 601 4.6. READ 603 A CoAP pub/sub client wishing to obtain only the most recent 604 published value on a topic MAY use the READ interface. For reading, 605 the client uses the CoAP GET method. The broker MUST accept Read 606 requests on a topic if the content format of the request matches the 607 content format the topic was created with. The broker MAY accept 608 Read requests which specify content formats that the broker can 609 supply as alternate content formats to the content format the topic 610 was registered with. The Broker MUST return a response code of "2.05 611 Content" along with the most recently published value if the topic 612 contains a valid value and the broker can supply the requested 613 content format. If the topic was published with the Max-Age option, 614 the broker MUST set the Max-Age option in the valid response to the 615 amount of time remaining for the topic to be valid since the last 616 publish. The Broker MUST return a response code of "2.04 No Content" 617 if the Max-Age of the previously stored value has expired. The 618 Broker MUST return a response code "4.04 Not Found" if the topic does 619 not exist or has been removed. The Broker MUST return a response 620 code "4.15 Unsupported Content Format" if the broker can not return 621 the requested content format. 623 The READ interface is specified as follows: 625 Interaction: Client -> Broker 627 Method: GET 629 URI Template: /{+ps/}{topic}{/topic*} 631 URI Template Variables: 633 ps := pub/sub Function Set path (mandatory). The path of the 634 pub/sub Function Set, as obtained from discovery. 636 topic := The desired topic to READ. 638 The following response codes are defined for this interface: 640 Success: 2.05 "Content". Successful READ, current value included 642 Success: 2.04 "No Content". Topic exists, value not included 644 Failure: 4.00 "Bad Request". Malformed request. 646 Failure: 4.01 "Unauthorized". Authorization failure. 648 Failure: 4.04 "Not Found". Topic does not exist. 650 Failure: 4.15 "Unsupported Content Format". Unsupported content- 651 format. 653 Figure 9 shows an example of a successful READ from topic1, followed 654 by a Publish on the topic, followed at some time later by a read of 655 the updated value from the recent Publish. 657 Client1 Client2 Broker 658 | | Read | 659 | | --------------- GET /ps/topic1 -------------> | 660 | | | 661 | | <---------- 2.05 Content "1007.1"------------ | 662 | | | 663 | | | 664 | | Publish | 665 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 666 | | | 667 | | | 668 | | Read | 669 | | --------------- GET /ps/topic1 -------------> | 670 | | | 671 | | <----------- 2.05 Content "1033.3"----------- | 672 | | | 674 Figure 9: Example of READ 676 4.7. REMOVE 678 A CoAP pub/sub Client wishing to remove a topic MAY use the CoAP 679 Delete operation on the URI of the topic. The CoAP pub/sub Broker 680 MUST return "2.02 Deleted" if the remove operation is successful. 681 The broker MUST return the appropriate 4.xx response code indicating 682 the reason for failure if the topic can not be removed. When a topic 683 is removed for any reason, the Broker SHOULD return the response code 684 4.04 Not Found and remove all of the observers from the list of 685 observers as per as per [RFC7641] Section 3.2. 687 The REMOVE interface is specified as follows: 689 Interaction: Client -> Broker 691 Method: DELETE 693 URI Template: /{+ps/}{topic}{/topic*} 695 URI Template Variables: 697 ps := pub/sub Function Set path (mandatory). The path of the 698 pub/sub Function Set, as obtained from discovery. 700 topic := The desired topic to REMOVE. 702 Content-Format: None 704 Response Payload: None 706 The following response codes are defined for this interface: 708 Success: 2.02 "Deleted". Successful remove 710 Failure: 4.00 "Bad Request". Malformed request. 712 Failure: 4.01 "Unauthorized". Authorization failure. 714 Failure: 4.04 "Not Found". Topic does not exist. 716 Figure 10 shows a successful remove of topic1. 718 Client Broker 719 | | 720 | ------------- DELETE /ps/topic1 ------------> | 721 | | 722 | | 723 | <-------------- 2.02 Deleted ---------------- | 724 | | 726 Figure 10: Example of REMOVE 728 5. CoAP pub/sub Operation with Resource Directory 730 A CoAP pub/sub Broker may register a pub/sub Function Set with a 731 Resource Directory. A pub/sub Client may use an RD to discover a 732 pub/sub Broker. 734 A CoAP pub/sub Client may register CoRE Links [RFC6690] to created 735 pub/sub Topics with an RD. A pub/sub Client may use an RD to 736 discover pub/sub Topics. A client which registers pub/sub Topics 737 with an RD MUST use the context relation (con) 738 [I-D.ietf-core-resource-directory] to indicate that the context of 739 the registered links is the pub/sub Broker. 741 6. Sleep-Wake Operation 743 CoAP pub/sub provides a way for client nodes to sleep between 744 operations, conserving energy during idle periods. This is made 745 possible by shifting the server role to the broker, allowing the 746 broker to be always-on and respond to requests from other clients 747 while a particular client is sleeping. 749 For example, the broker will retain the last state update received 750 from a sleeping client, in order to supply the most recent state 751 update to other clients in response to read and subscribe operations. 753 Likewise, the broker will retain the last state update received on 754 the topic such that a sleeping client, upon waking, can perform a 755 read operation to the broker to update its own state from the most 756 recent system state update. 758 7. Simple Flow Control 760 Since the broker node has to potentially send a large amount of 761 notification messages for each publish message and it may be serving 762 a large amount of subscribers and publishers simultaneously, the 763 broker may become overwhelmed if it receives many publish messages to 764 popular topics in a short period of time. 766 If the broker is unable to serve a certain client that is sending 767 publish messages too fast, the broker MUST respond with Response Code 768 4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too 769 Many Requests" but uses the Max-Age Option in place of the "Retry- 770 After" header field to indicate the number of seconds after which to 771 retry. The broker MAY stop creating notifications from the publish 772 messages from this client and to this topic for the indicated time. 774 If a client receives the 4.29 Response Code from the broker for a 775 publish message to a topic, it MUST NOT send new publish messages to 776 the broker on the same topic before the time indicated in Max-Age has 777 passed. 779 8. Security Considerations 781 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 782 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 783 therefore the security considerations of those documents also apply 784 to this specification. Additionally, a CoAP pub/sub broker and the 785 clients SHOULD authenticate each other and enforce access control 786 policies. A malicious client could subscribe to data it is not 787 authorized to or mount a denial of service attack against the broker 788 by publishing a large number of resources. The authentication can be 789 performed using the already standardized DTLS offered mechanisms, 790 such as certificates. DTLS also allows communication security to be 791 established to ensure integrity and confidentiality protection of the 792 data exchanged between these relevant parties. Provisioning the 793 necessary credentials, trust anchors and authorization policies is 794 non-trivial and subject of ongoing work. 796 The use of a CoAP pub/sub broker introduces challenges for the use of 797 end-to-end security between for example a client device on a sensor 798 network and a client application running in a cloud-based server 799 infrastructure since brokers terminate the exchange. While running 800 separate DTLS sessions from the client device to the broker and from 801 broker to client application protects confidentially on those paths, 802 the client device does not know whether the commands coming from the 803 broker are actually coming from the client application. Similarly, a 804 client application requesting data does not know whether the data 805 originated on the client device. For scenarios where end-to-end 806 security is desirable the use of application layer security is 807 unavoidable. Application layer security would then provide a 808 guarantee to the client device that any request originated at the 809 client application. Similarly, integrity protected sensor data from 810 a client device will also provide guarantee to the client application 811 that the data originated on the client device itself. The protected 812 data can also be verified by the intermediate broker ensuring that it 813 stores/caches correct request/response and no malicious messages/ 814 requests are accepted. The broker would still be able to perform 815 aggregation of data/requests collected. 817 Depending on the level of trust users and system designers place in 818 the CoAP pub/sub broker, the use of end-to-end object security is 819 RECOMMENDED [I-D.selander-ace-object-security]. 821 When only end-to-end encryption is necessary and the CoAP Broker is 822 trusted, Payload Only Protection (Mode:PAYL) could be used. The 823 Publisher would wrap only the payload before sending it to the broker 824 and set the option Content-Format to application/smpayl. Upon 825 receival, the Broker can read the unencrypted CoAP header to forward 826 it to the subscribers. 828 9. IANA Considerations 830 This document registers one attribute value in the Resource Type 831 (rt=) registry established with [RFC6690] and appends to the 832 definition of one CoAP Response Code in the CoRE Parameters Registry. 834 9.1. Resource Type value 'core.ps' 836 o Attribute Value: core.ps 838 o Description: Section 4 of [[This document]] 840 o Reference: [[This document]] 842 o Notes: None 844 9.2. Response Code value '2.04' 846 o Response Code: 2.04 848 o Description: Add No Content response to GET to the existing 849 definition of the 2.04 response code. 851 o Reference: [[This document]] 853 o Notes: None 855 9.3. Response Code value '4.29' 857 o Response Code: 4.29 859 o Description: This error code is used by a server to indicate that 860 a client is making too many requests on a resource. 862 o Reference: [[This document]] 864 o Notes: None 866 10. Acknowledgements 868 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 869 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran 870 Selander, Mikko Majanen, and Olaf Bergmann for their contributions 871 and reviews. 873 11. References 875 11.1. Normative References 877 [I-D.ietf-core-resource-directory] 878 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 879 Resource Directory", draft-ietf-core-resource-directory-05 880 (work in progress), October 2015. 882 [I-D.selander-ace-object-security] 883 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 884 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 885 object-security-03 (work in progress), October 2015. 887 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 888 Requirement Levels", BCP 14, RFC 2119, 889 DOI 10.17487/RFC2119, March 1997, 890 . 892 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 893 Resource Identifier (URI): Generic Syntax", STD 66, 894 RFC 3986, DOI 10.17487/RFC3986, January 2005, 895 . 897 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 898 and D. Orchard, "URI Template", RFC 6570, 899 DOI 10.17487/RFC6570, March 2012, 900 . 902 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 903 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 904 . 906 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 907 Application Protocol (CoAP)", RFC 7252, 908 DOI 10.17487/RFC7252, June 2014, 909 . 911 [RFC7641] Hartke, K., "Observing Resources in the Constrained 912 Application Protocol (CoAP)", RFC 7641, 913 DOI 10.17487/RFC7641, September 2015, 914 . 916 11.2. Informative References 918 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 919 DOI 10.17487/RFC5988, October 2010, 920 . 922 Authors' Addresses 924 Michael Koster 925 ARM Limited 927 Email: Michael.Koster@arm.com 929 Ari Keranen 930 Ericsson 932 Email: ari.keranen@ericsson.com 934 Jaime Jimenez 935 Ericsson 937 Email: jaime.jimenez@ericsson.com