idnits 2.17.1 draft-koster-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 : ---------------------------------------------------------------------------- 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 (October 19, 2015) is 3084 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: 'RFC3986' is defined on line 820, but no explicit reference was found in the text == 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 (~~), 5 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: April 21, 2016 J. Jimenez 6 Ericsson 7 October 19, 2015 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-koster-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 April 21, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 9 67 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 11 68 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 14 70 5. CoAP pub/sub Operation with Resource Directory . . . . . . . 15 71 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 15 72 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 16 73 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 74 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 75 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 17 76 9.2. Response Code value '2.04' . . . . . . . . . . . . . . . 17 77 9.3. Response Code value '4.29' . . . . . . . . . . . . . . . 18 78 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 79 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 80 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 81 11.2. Informative References . . . . . . . . . . . . . . . . . 19 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 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. 205 4. CoAP pub/sub Function Set 207 This section defines the interfaces between a CoAP pub/sub Broker and 208 pub/sub Clients, which is called the CoAP pub/sub Function Set. The 209 examples throughout this section assume the use of CoAP [RFC7252]. A 210 CoAP pub/sub Broker implementing this specification MUST support the 211 DISCOVER, CREATE, PUBLISH, SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE 212 operations defined in this section. With the exception of PUBLISH, 213 all operations in the CoAP pub/sub Function Set MUST use confirmable 214 (CON) CoAP messages. 216 4.1. DISCOVER 218 CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP 219 Simple Discovery or through a Resource Directory (RD) 220 [I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD 221 indicate its presence and availability on a network by exposing a 222 link to its pub/sub function set at its .well-known/core location 223 [RFC6690]. A CoAP pub/sub broker MAY register its pub/sub function 224 set location with a Resource Directory. Figure 2 shows an example of 225 a client discovering a local pub/sub Function Set using CoAP Simple 226 Discovery. A broker wishing to advertise the CoAP pub/sub Function 227 Set for Simple Discovery or through a Resource Directory MUST use the 228 link relation rt="core.ps". 230 The DISCOVER interface is specified as follows: 232 Interaction: Client -> Broker 234 Method: GET 235 URI Template: /.well-known/core{?rt} 237 URI Template Variables: 239 rt := Resource Type (optional). MAY contain the value "core.ps" 241 Content-Format: application/link-format (if any) 243 The following response codes are defined for this interface: 245 Success: 2.05 "Content" with an application/link-format payload 246 containing one or more matching entries for the broker resource. 247 A pub/sub broker SHOULD use the value "ps" for the link subject 248 variable whenever possible. 250 Failure: 4.04 "Not Found" is returned in case no matching entry is 251 found for a unicast request. 253 Failure: 4.00 "Bad Request" is returned in case of a malformed 254 request for a unicast request. 256 Failure: No error response to a multicast request. 258 Client Broker 259 | | 260 | ------ GET /.well-known/core?rt=core.ps ----->| 261 | | 262 | <------2.05 Content ";rt=core.ps"--------| 263 | | 265 Figure 2: Example of DISCOVER 267 4.2. CREATE 269 Clients create topics on the broker using the CREATE interface. A 270 client wishing to create a topic MUST use CoAP POST to the pub/sub 271 function set location with a payload indicating the desired topic. 272 The topic MUST use the CoRE link format [RFC6690]. The client MUST 273 indicate the desired content format for publishes to the topic by 274 using the ct (Content Type) relation in the link-format payload. The 275 client MAY indicate the lifetime of the topic by including the Max- 276 Age option in the CREATE request. Broker MUST return a response code 277 of "2.01 Created" if the topic is created and return the created 278 relative URI path via Location-Path options. The broker MUST return 279 the appropriate 4.xx response code indicating the reason for failure 280 if a new topic can not be created. Broker SHOULD remove topics if 281 the Max-Age of the topic is exceeded without any publishes to the 282 topic. 284 The CREATE interface is specified as follows: 286 Interaction: Client -> Broker 288 Method: POST 290 URI Template: /{+ps} 292 URI Template Variables: 294 ps := pub/sub Function Set path (mandatory). The path of the 295 pub/sub Function Set, as obtained from discovery. A pub/sub 296 broker SHOULD use the value "ps" for this variable whenever 297 possible. 299 Content-Format: application/link-format 301 Payload: The desired topic to CREATE 303 The following response codes are defined for this interface: 305 Success: 2.01 "Created". Successful Creation of the topic 307 Failure: 4.00 "Bad Request". Malformed request. 309 Failure: 4.01 "Unauthorized". Authorization failure. 311 Failure: 4.03 "Forbidden". Topic already exists. 313 Failure: 4.06 "Not Acceptable". Unsupported content format for 314 topic. 316 Figure 3 shows an example of a topic called "topic1" being 317 successfully created. 319 Client Broker 320 | | 321 | ---------- POST /ps ";ct=50" -------->| 322 | | 323 | <---------------- 2.01 Created ---------------| 324 | Location: /topics/topic1 | 325 | | 327 Figure 3: Example of CREATE 329 4.3. PUBLISH 331 A CoAP pub/sub Client uses the PUBLISH interface for updating topics 332 on the broker. The client MUST use the PUT method to publish state 333 updates to the CoAP pub/sub Broker. A client MUST use the content 334 format specified upon creation of a given topic to publish updates to 335 that topic. The broker MUST reject publish operations which do not 336 use the specified content format. A CoAP client publishing on a 337 topic MAY indicate the maximum lifetime of the value by including the 338 Max-Age option in the publish request. A client MAY use confirmable 339 (CON) or non-confirmable (NON) messages to publish updates to a 340 broker. The broker MUST return a response code of "2.04 Changed" if 341 the publish is accepted or "4.04 Not Found" if the topic does not 342 exist. A broker MAY return "4.29 Too Many Requests" if simple flow 343 control as described in Section 7 is implemented. 345 The Broker MUST notify all clients subscribed on a particular topic 346 each time it receives a publish on that topic. An example is shown 347 in Figure 5. If a client publishes to a broker using non-confirmable 348 messages, the broker MAY notify subscribed clients using non- 349 confirmable messages. If a client publishes to a broker using 350 confirmable messages, the broker MAY also notify all subscribed 351 clients using confirmable messages. If a client publishes to a 352 broker with the Max-Age option, the broker MUST include the same 353 value for the Max-Age option in all notifications. A broker MUST use 354 CoAP Notification as described in [RFC7641] to notify subscribed 355 clients. 357 The PUBLISH interface is specified as follows: 359 Interaction: Client -> Broker 361 Method: PUT 363 URI Template: /{+ps}/{topic} 365 URI Template Variables: 367 ps := pub/sub Function Set path (mandatory). The path of the 368 pub/sub Function Set, as obtained from discovery. 370 topic := The desired topic to publish on. 372 Content-Format: Any valid CoAP content format 374 Payload: Representation of the topic value (CoAP resource state 375 representation) in the indicated content format 377 The following response codes are defined for this interface: 379 Success: 2.04 "Changed". Successful publish, topic is updated 381 Failure: 4.00 "Bad Request". Malformed request. 383 Failure: 4.01 "Unauthorized". Authorization failure. 385 Failure: 4.04 "Not Found". Topic does not exist. 387 Failure: 4.29 "Too Many Requests". The client should slow down the 388 rate of publish messages for this topic (see Section 7). 390 Figure 4 shows an example of a new value being successfully published 391 to the topic "topic1". See Figure 5 for an example of a broker 392 forwarding a message from a publishing client to a subscribed client. 394 Client Broker 395 | | 396 | ---------- PUT /ps/topic1 "1033.3" --------> | 397 | | 398 | | 399 | <--------------- 2.04 Changed---------------- | 400 | | 402 Figure 4: Example of PUBLISH 404 4.4. SUBSCRIBE 406 CoAP pub/sub Clients subscribe to topics on the Broker using CoAP 407 Observe as described in [RFC7641]. A CoAP pub/sub Client wishing to 408 Subscribe to a topic on a broker MUST use a CoAP GET with Observe 409 registration. The Broker MAY add the client to a list of observers. 410 The Broker MUST return a response code of "2.05 Content" along with 411 the most recently published value if the topic contains a valid value 412 and the broker can supply the requested content format. The broker 413 MUST accept Subscribe requests on a topic if the content format of 414 the request matches the content format the topic was created with. 415 The broker MAY accept Subscribe requests which specify content 416 formats that the broker can supply as alternate content formats to 417 the content format the topic was registered with. If the topic was 418 published with the Max-Age option, the broker MUST set the Max-Age 419 option in the valid response to the amount of time remaining for the 420 value to be valid since the last publish operation on that topic. 421 The Broker MUST return a response code of "2.04 No Content" if the 422 Max-Age of the previously stored value has expired. The Broker MUST 423 return a response code "4.04 Not Found" if the topic does not exist 424 or has been removed. The Broker MUST return a response code "4.15 425 Unsupported Content Format" if it can not return the requested 426 content format. 428 The SUBSCRIBE interface is specified as follows: 430 Interaction: Client -> Broker 432 Method: GET 434 Options: Observe:0 436 URI Template: /{+ps}/{topic} 438 URI Template Variables: 440 ps := pub/sub Function Set path (mandatory). The path of the 441 pub/sub Function Set, as obtained from discovery. 443 topic := The desired topic to subscribe to. 445 The following response codes are defined for this interface: 447 Success: 2.05 "Content". Successful subscribe, current value 448 included 450 Success: 2.04 "No Content". Successful subscribe, value not 451 included 453 Failure: 4.00 "Bad Request". Malformed request. 455 Failure: 4.01 "Unauthorized". Authorization failure. 457 Failure: 4.04 "Not Found". Topic does not exist. 459 Failure: 4.15 "Unsupported Content Format". Unsupported content 460 format. 462 Figure 5 shows an example of Client2 subscribing to "topic1" and 463 receiving a response from the broker, with a subsequent notification. 464 The subscribe response from the broker uses the last stored value 465 associated with the topic1. The notification from the broker is sent 466 in response to the publish received from Client1. 468 Client1 Client2 Broker 469 | | Subscribe | 470 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 471 | | | 472 | | <---------- 2.05 Content Observe:10---------- | 473 | | | 474 | | | 475 | | Publish | 476 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 477 | | Notify | 478 | | <---------- 2.05 Content Observe:11---------- | 479 | | | 481 Figure 5: Example of SUBSCRIBE 483 4.5. UNSUBSCRIBE 485 CoAP pub/sub Clients unsubscribe from topics on the Broker using the 486 CoAP Cancel Observation operation. A CoAP pub/sub Client wishing to 487 unsubscribe to a topic on a Broker MUST either use CoAP GET with 488 Observe using an Observe parameter of 1 or send a CoAP Reset message 489 in response to a publish [RFC7641]. 491 The UNSUBSCRIBE interface is specified as follows: 493 Interaction: Client -> Broker 495 Method: GET 497 Options: Observe:1 499 URI Template: /{+ps}/{topic} 501 URI Template Variables: 503 ps := pub/sub Function Set path (mandatory). The path of the 504 pub/sub Function Set, as obtained from discovery. 506 topic := The desired topic to unsubscribe from. 508 The following response codes are defined for this interface: 510 Success: 2.05 "Content". Successful unsubscribe, current value 511 included 513 Success: 2.04 "No Content". Successful unsubscribe, value not 514 included 516 Failure: 4.00 "Bad Request". Malformed request. 518 Failure: 4.01 "Unauthorized". Authorization failure. 520 Failure: 4.04 "Not Found". Topic does not exist. 522 Figure 6 shows an example of a client unsubscribe using the Observe=1 523 cancellation method. 525 Client Broker 526 | | 527 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 528 | | 529 | <------------- 2.05 Content ----------------- | 530 | | 532 Figure 6: Example of UNSUBSCRIBE 534 4.6. READ 536 A CoAP pub/sub client wishing to obtain only the most recent 537 published value on a topic MAY use the READ interface. For reading, 538 the client uses the CoAP GET method. The broker MUST accept Read 539 requests on a topic if the content format of the request matches the 540 content format the topic was created with. The broker MAY accept 541 Read requests which specify content formats that the broker can 542 supply as alternate content formats to the content format the topic 543 was registered with. The Broker MUST return a response code of "2.05 544 Content" along with the most recently published value if the topic 545 contains a valid value and the broker can supply the requested 546 content format. If the topic was published with the Max-Age option, 547 the broker MUST set the Max-Age option in the valid response to the 548 amount of time remaining for the topic to be valid since the last 549 publish. The Broker MUST return a response code of "2.04 No Content" 550 if the Max-Age of the previously stored value has expired. The 551 Broker MUST return a response code "4.04 Not Found" if the topic does 552 not exist or has been removed. The Broker MUST return a response 553 code "4.15 Unsupported Content Format" if the broker can not return 554 the requested content format. 556 The READ interface is specified as follows: 558 Interaction: Client -> Broker 560 Method: GET 562 URI Template: /{+ps}/{topic} 564 URI Template Variables: 566 ps := pub/sub Function Set path (mandatory). The path of the 567 pub/sub Function Set, as obtained from discovery. 569 topic := The desired topic to READ. 571 The following response codes are defined for this interface: 573 Success: 2.05 "Content". Successful READ, current value included 575 Success: 2.04 "No Content". Topic exists, value not included 577 Failure: 4.00 "Bad Request". Malformed request. 579 Failure: 4.01 "Unauthorized". Authorization failure. 581 Failure: 4.04 "Not Found". Topic does not exist. 583 Failure: 4.15 "Unsupported Content Format". Unsupported content- 584 format. 586 Figure 7 shows an example of a successful READ from topic1, followed 587 by a Publish on the topic, followed at some time later by a read of 588 the updated value from the recent Publish. 590 Client1 Client2 Broker 591 | | Read | 592 | | --------------- GET /ps/topic1 -------------> | 593 | | | 594 | | <---------- 2.05 Content "1007.1"------------ | 595 | | | 596 | | | 597 | | Publish | 598 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 599 | | | 600 | | | 601 | | Read | 602 | | --------------- GET /ps/topic1 -------------> | 603 | | | 604 | | <----------- 2.05 Content "1033.3"----------- | 605 | | | 607 Figure 7: Example of READ 609 4.7. REMOVE 611 A CoAP pub/sub Client wishing to remove a topic MAY use the CoAP 612 Delete operation on the URI of the topic. The CoAP pub/sub Broker 613 MUST return "2.02 Deleted" if the remove operation is successful. 614 The broker MUST return the appropriate 4.xx response code indicating 615 the reason for failure if the topic can not be removed. 617 The REMOVE interface is specified as follows: 619 Interaction: Client -> Broker 621 Method: DELETE 623 URI Template: /{+ps}/{topic} 625 URI Template Variables: 627 ps := pub/sub Function Set path (mandatory). The path of the 628 pub/sub Function Set, as obtained from discovery. 630 topic := The desired topic to REMOVE. 632 Content-Format: None 634 Response Payload: None 636 The following response codes are defined for this interface: 638 Success: 2.02 "Deleted". Successful remove 640 Failure: 4.00 "Bad Request". Malformed request. 642 Failure: 4.01 "Unauthorized". Authorization failure. 644 Failure: 4.04 "Not Found". Topic does not exist. 646 Figure 8 shows a successful remove of topic1. 648 Client Broker 649 | | 650 | ------------- DELETE /ps/topic1 ------------> | 651 | | 652 | | 653 | <-------------- 2.02 Deleted ---------------- | 654 | | 656 Figure 8: Example of REMOVE 658 5. CoAP pub/sub Operation with Resource Directory 660 A CoAP pub/sub Broker may register a pub/sub Function Set with a 661 Resource Directory. A pub/sub Client may use an RD to discover a 662 pub/sub Broker. 664 A CoAP pub/sub Client may register CoRE Links [RFC6690] to created 665 pub/sub Topics with an RD. A pub/sub Client may use an RD to 666 discover pub/sub Topics. A client which registers pub/sub Topics 667 with an RD MUST use the context relation (con) 668 [I-D.ietf-core-resource-directory] to indicate that the context of 669 the registered links is the pub/sub Broker. 671 6. Sleep-Wake Operation 673 CoAP pub/sub provides a way for client nodes to sleep between 674 operations, conserving energy during idle periods. This is made 675 possible by shifting the server role to the broker, allowing the 676 broker to be always-on and respond to requests from other clients 677 while a particular client is sleeping. 679 For example, the broker will retain the last state update received 680 from a sleeping client, in order to supply the most recent state 681 update to other clients in response to read and subscribe operations. 683 Likewise, the broker will retain the last state update received on 684 the topic such that a sleeping client, upon waking, can perform a 685 read operation to the broker to update its own state from the most 686 recent system state update. 688 7. Simple Flow Control 690 Since the broker node has to potentially send a large amount of 691 notification messages for each publish message and it may be serving 692 a large amount of subscribers and publishers simultaneously, the 693 broker may become overwhelmed if it receives many publish messages to 694 popular topics in a short period of time. 696 If the broker is unable to serve a certain client that is sending 697 publish messages too fast, the broker MUST respond with Response Code 698 4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too 699 Many Requests" but uses the Max-Age Option in place of the "Retry- 700 After" header field to indicate the number of seconds after which to 701 retry. The broker MAY stop creating notifications from the publish 702 messages from this client and to this topic for the indicated time. 704 If a client receives the 4.29 Response Code from the broker for a 705 publish message to a topic, it MUST NOT send new publish messages to 706 the broker on the same topic before the time indicated in Max-Age has 707 passed. 709 8. Security Considerations 711 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 712 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 713 therefore the security considerations of those documents also apply 714 to this specification. Additionally, a CoAP pub/sub broker and the 715 clients SHOULD authenticate each other and enforce access control 716 policies. A malicious client could subscribe to data it is not 717 authorized to or mount a denial of service attack against the broker 718 by publishing a large number of resources. The authentication can be 719 performed using the already standardized DTLS offered mechanisms, 720 such as certificates. DTLS also allows communication security to be 721 established to ensure integrity and confidentiality protection of the 722 data exchanged between these relevant parties. Provisioning the 723 necessary credentials, trust anchors and authorization policies is 724 non-trivial and subject of ongoing work. 726 The use of a CoAP pub/sub broker introduces challenges for the use of 727 end-to-end security between for example a client device on a sensor 728 network and a client application running in a cloud-based server 729 infrastructure since brokers terminate the exchange. While running 730 separate DTLS sessions from the client device to the broker and from 731 broker to client application protects confidentially on those paths, 732 the client device does not know whether the commands coming from the 733 broker are actually coming from the client application. Similarly, a 734 client application requesting data does not know whether the data 735 originated on the client device. For scenarios where end-to-end 736 security is desirable the use of application layer security is 737 unavoidable. Application layer security would then provide a 738 guarantee to the client device that any request originated at the 739 client application. Similarly, integrity protected sensor data from 740 a client device will also provide guarantee to the client application 741 that the data originated on the client device itself. The protected 742 data can also be verified by the intermediate broker ensuring that it 743 stores/caches correct request/response and no malicious messages/ 744 requests are accepted. The broker would still be able to perform 745 aggregation of data/requests collected. 747 Depending on the level of trust users and system designers place in 748 the CoAP pub/sub broker, the use of end-to-end object security is 749 RECOMMENDED [I-D.selander-ace-object-security]. 751 When only end-to-end encryption is necessary and the CoAP Broker is 752 trusted, Payload Only Protection (Mode:PAYL) could be used. The 753 Publisher would wrap only the payload before sending it to the broker 754 and set the option Content-Format to application/smpayl. Upon 755 receival, the Broker can read the unencrypted CoAP header to forward 756 it to the subscribers. 758 9. IANA Considerations 760 This document registers one attribute value in the Resource Type 761 (rt=) registry established with [RFC6690] and appends to the 762 definition of one CoAP Response Code in the CoRE Parameters Registry. 764 9.1. Resource Type value 'core.ps' 766 o Attribute Value: core.ps 768 o Description: Section 4 of [[This document]] 770 o Reference: [[This document]] 772 o Notes: None 774 9.2. Response Code value '2.04' 776 o Response Code: 2.04 777 o Description: Add No Content response to GET to the existing 778 definition of the 2.04 response code. 780 o Reference: [[This document]] 782 o Notes: None 784 9.3. Response Code value '4.29' 786 o Response Code: 4.29 788 o Description: This error code is used by a server to indicate that 789 a client is making too many requests on a resource. 791 o Reference: [[This document]] 793 o Notes: None 795 10. Acknowledgements 797 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 798 Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, and Goran 799 Selander for their contributions and reviews. 801 11. References 803 11.1. Normative References 805 [I-D.ietf-core-resource-directory] 806 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 807 Resource Directory", draft-ietf-core-resource-directory-05 808 (work in progress), October 2015. 810 [I-D.selander-ace-object-security] 811 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 812 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 813 object-security-03 (work in progress), October 2015. 815 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 816 Requirement Levels", BCP 14, RFC 2119, 817 DOI 10.17487/RFC2119, March 1997, 818 . 820 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 821 Resource Identifier (URI): Generic Syntax", STD 66, 822 RFC 3986, DOI 10.17487/RFC3986, January 2005, 823 . 825 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 826 and D. Orchard, "URI Template", RFC 6570, 827 DOI 10.17487/RFC6570, March 2012, 828 . 830 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 831 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 832 . 834 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 835 Application Protocol (CoAP)", RFC 7252, 836 DOI 10.17487/RFC7252, June 2014, 837 . 839 [RFC7641] Hartke, K., "Observing Resources in the Constrained 840 Application Protocol (CoAP)", RFC 7641, 841 DOI 10.17487/RFC7641, September 2015, 842 . 844 11.2. Informative References 846 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 847 DOI 10.17487/RFC5988, October 2010, 848 . 850 Authors' Addresses 852 Michael Koster 853 ARM Limited 855 Email: Michael.Koster@arm.com 857 Ari Keranen 858 Ericsson 860 Email: ari.keranen@ericsson.com 862 Jaime Jimenez 863 Ericsson 865 Email: jaime.jimenez@ericsson.com