idnits 2.17.1 draft-koster-core-coap-pubsub-02.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 (July 6, 2015) is 3210 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 814, but no explicit reference was found in the text == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-03 == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-02 -- 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: January 7, 2016 J. Jimenez 6 Ericsson 7 July 6, 2015 9 Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) 10 draft-koster-core-coap-pubsub-02 12 Abstract 14 The Constrained Application Protocol (CoAP), and related extensions 15 are intended to support machine-to-machine communication in systems 16 where one or more nodes are resource constrained, in particular for 17 low power wireless sensor networks. This document defines a publish- 18 subscribe broker for CoAP that extends the capabilities of CoAP for 19 supporting nodes with long breaks in connectivity and/or up-time. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 7, 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 . . . . . . . . . . . . . . . . . . . . . 15 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' . . . . . . . . . . . . . . . 17 78 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 79 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 80 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 81 11.2. Informative References . . . . . . . . . . . . . . . . . 18 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. The broker MUST return 278 the appropriate 4.xx response code indicating the reason for failure 279 if a new topic can not be created. Broker SHOULD remove topics if 280 the Max-Age of the topic is exceeded without any publishes to the 281 topic. 283 The CREATE interface is specified as follows: 285 Interaction: Client -> Broker 287 Method: POST 289 URI Template: /{+ps} 291 URI Template Variables: 293 ps := pub/sub Function Set path (mandatory). The path of the 294 pub/sub Function Set, as obtained from discovery. A pub/sub 295 broker SHOULD use the value "ps" for this variable whenever 296 possible. 298 Content-Format: application/link-format 300 Payload: The desired topic to CREATE 302 The following response codes are defined for this interface: 304 Success: 2.01 "Created". Successful Creation of the topic 306 Failure: 4.00 "Bad Request". Malformed request. 308 Failure: 4.01 "Unauthorized". Authorization failure. 310 Failure: 4.03 "Forbidden". Topic already exists. 312 Failure: 4.06 "Not Acceptable". Unsupported content format for 313 topic. 315 Figure 3 shows an example of a topic called "topic1" being 316 successfully created. 318 Client Broker 319 | | 320 | ---------- POST /ps ";ct=50" -------->| 321 | | 322 | <---------------- 2.01 Created ---------------| 323 | | 325 Figure 3: Example of CREATE 327 4.3. PUBLISH 329 A CoAP pub/sub Client uses the PUBLISH interface for updating topics 330 on the broker. The client MUST use the PUT method to publish state 331 updates to the CoAP pub/sub Broker. A client MUST use the content 332 format specified upon creation of a given topic to publish updates to 333 that topic. The broker MUST reject publish operations which do not 334 use the specified content format. A CoAP client publishing on a 335 topic MAY indicate the maximum lifetime of the value by including the 336 Max-Age option in the publish request. A client MAY use confirmable 337 (CON) or non-confirmable (NON) messages to publish updates to a 338 broker. The broker MUST return a response code of "2.04 Changed" if 339 the publish is accepted or "4.04 Not Found" if the topic does not 340 exist. A broker MAY return "4.29 Too Many Requests" if simple flow 341 control as described in Section 7 is implemented. 343 The Broker MUST notify all clients subscribed on a particular topic 344 each time it receives a publish on that topic. An example is shown 345 in Figure 5. If a client publishes to a broker using non-confirmable 346 messages, the broker MAY notify subscribed clients using non- 347 confirmable messages. If a client publishes to a broker using 348 confirmable messages, the broker MUST also notify all subscribed 349 clients using confirmable messages. If a client publishes to a 350 broker with the Max-Age option, the broker MUST include the same 351 value for the Max-Age option in all notifications. A broker MUST use 352 CoAP Notification as described in [I-D.ietf-core-observe] to notify 353 subscribed clients. 355 The PUBLISH interface is specified as follows: 357 Interaction: Client -> Broker 359 Method: PUT 361 URI Template: /{+ps}/{topic} 363 URI Template Variables: 365 ps := pub/sub Function Set path (mandatory). The path of the 366 pub/sub Function Set, as obtained from discovery. 368 topic := The desired topic to publish on. 370 Content-Format: Any valid CoAP content format 372 Payload: Representation of the topic value (CoAP resource state 373 representation) in the indicated content format 375 The following response codes are defined for this interface: 377 Success: 2.04 "Changed". Successful publish, topic is updated 379 Failure: 4.00 "Bad Request". Malformed request. 381 Failure: 4.01 "Unauthorized". Authorization failure. 383 Failure: 4.04 "Not Found". Topic does not exist. 385 Failure: 4.29 "Too Many Requests". The client should slow down the 386 rate of publish messages for this topic (see Section 7). 388 Figure 4 shows an example of a new value being successfully published 389 to the topic "topic1". See Figure 5 for an example of a broker 390 forwarding a message from a publishing client to a subscribed client. 392 Client Broker 393 | | 394 | ---------- PUT /ps/topic1 "1033.3" --------> | 395 | | 396 | | 397 | <--------------- 2.04 Changed---------------- | 398 | | 400 Figure 4: Example of PUBLISH 402 4.4. SUBSCRIBE 404 CoAP pub/sub Clients subscribe to topics on the Broker using CoAP 405 Observe as described in [I-D.ietf-core-observe]. A CoAP pub/sub 406 Client wishing to Subscribe to a topic on a broker MUST use a CoAP 407 GET with Observe registration. The Broker MAY add the client to a 408 list of observers. The Broker MUST return a response code of "2.05 409 Content" along with the most recently published value if the topic 410 contains a valid value and the broker can supply the requested 411 content format. The broker MUST accept Subscribe requests on a topic 412 if the content format of the request matches the content format the 413 topic was created with. The broker MAY accept Subscribe requests 414 which specify content formats that the broker can supply as alternate 415 content formats to the content format the topic was registered with. 416 If the topic was published with the Max-Age option, the broker MUST 417 set the Max-Age option in the valid response to the amount of time 418 remaining for the value to be valid since the last publish operation 419 on that topic. The Broker MUST return a response code of "2.04 No 420 Content" if the Max-Age of the previously stored value has expired. 422 The Broker MUST return a response code "4.04 Not Found" if the topic 423 does not exist or has been removed. The Broker MUST return a 424 response code "4.15 Unsupported Content Format" if it can not return 425 the requested content format. 427 The SUBSCRIBE interface is specified as follows: 429 Interaction: Client -> Broker 431 Method: GET 433 Options: Observe:0 435 URI Template: /{+ps}/{topic} 437 URI Template Variables: 439 ps := pub/sub Function Set path (mandatory). The path of the 440 pub/sub Function Set, as obtained from discovery. 442 topic := The desired topic to subscribe to. 444 The following response codes are defined for this interface: 446 Success: 2.05 "Content". Successful subscribe, current value 447 included 449 Success: 2.04 "No Content". Successful subscribe, value not 450 included 452 Failure: 4.00 "Bad Request". Malformed request. 454 Failure: 4.01 "Unauthorized". Authorization failure. 456 Failure: 4.04 "Not Found". Topic does not exist. 458 Failure: 4.15 "Unsupported Content Format". Unsupported content 459 format. 461 Figure 5 shows an example of Client2 subscribing to "topic1" and 462 receiving a response from the broker, with a subsequent notification. 463 The subscribe response from the broker uses the last stored value 464 associated with the topic1. The notification from the broker is sent 465 in response to the publish received from Client1. 467 Client1 Client2 Broker 468 | | Subscribe | 469 | | ----- GET /ps/topic1 Observe:0 Token:XX ----> | 470 | | | 471 | | <---------- 2.05 Content Observe:10---------- | 472 | | | 473 | | | 474 | | Publish | 475 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 476 | | Notify | 477 | | <---------- 2.05 Content Observe:11---------- | 478 | | | 480 Figure 5: Example of SUBSCRIBE 482 4.5. UNSUBSCRIBE 484 CoAP pub/sub Clients unsubscribe from topics on the Broker using the 485 CoAP Cancel Observation operation. A CoAP pub/sub Client wishing to 486 unsubscribe to a topic on a Broker MUST either use CoAP GET with 487 Observe using an Observe parameter of 1 or send a CoAP Reset message 488 in response to a publish [I-D.ietf-core-observe]. 490 The UNSUBSCRIBE interface is specified as follows: 492 Interaction: Client -> Broker 494 Method: GET 496 Options: Observe:1 498 URI Template: /{+ps}/{topic} 500 URI Template Variables: 502 ps := pub/sub Function Set path (mandatory). The path of the 503 pub/sub Function Set, as obtained from discovery. 505 topic := The desired topic to unsubscribe from. 507 The following response codes are defined for this interface: 509 Success: 2.05 "Content". Successful unsubscribe, current value 510 included 512 Success: 2.04 "No Content". Successful unsubscribe, value not 513 included 515 Failure: 4.00 "Bad Request". Malformed request. 517 Failure: 4.01 "Unauthorized". Authorization failure. 519 Failure: 4.04 "Not Found". Topic does not exist. 521 Figure 6 shows an example of a client unsubscribe using the Observe=1 522 cancellation method. 524 Client Broker 525 | | 526 | ----- GET /ps/topic1 Observe:1 Token:XX ----> | 527 | | 528 | <------------- 2.05 Content ----------------- | 529 | | 531 Figure 6: Example of UNSUBSCRIBE 533 4.6. READ 535 A CoAP pub/sub client wishing to obtain only the most recent 536 published value on a topic MAY use the READ interface. For reading, 537 the client uses the CoAP GET method. The broker MUST accept Read 538 requests on a topic if the content format of the request matches the 539 content format the topic was created with. The broker MAY accept 540 Read requests which specify content formats that the broker can 541 supply as alternate content formats to the content format the topic 542 was registered with. The Broker MUST return a response code of "2.05 543 Content" along with the most recently published value if the topic 544 contains a valid value and the broker can supply the requested 545 content format. If the topic was published with the Max-Age option, 546 the broker MUST set the Max-Age option in the valid response to the 547 amount of time remaining for the topic to be valid since the last 548 publish. The Broker MUST return a response code of "2.04 No Content" 549 if the Max-Age of the previously stored value has expired. The 550 Broker MUST return a response code "4.04 Not Found" if the topic does 551 not exist or has been removed. The Broker MUST return a response 552 code "4.15 Unsupported Content Format" if the broker can not return 553 the requested content format. 555 The READ interface is specified as follows: 557 Interaction: Client -> Broker 559 Method: GET 560 URI Template: /{+ps}/{topic} 562 URI Template Variables: 564 ps := pub/sub Function Set path (mandatory). The path of the 565 pub/sub Function Set, as obtained from discovery. 567 topic := The desired topic to READ. 569 The following response codes are defined for this interface: 571 Success: 2.05 "Content". Successful READ, current value included 573 Success: 2.04 "No Content". Topic exists, value not included 575 Failure: 4.00 "Bad Request". Malformed request. 577 Failure: 4.01 "Unauthorized". Authorization failure. 579 Failure: 4.04 "Not Found". Topic does not exist. 581 Failure: 4.15 "Unsupported Content Format". Unsupported content- 582 format. 584 Figure 7 shows an example of a successful READ from topic1, followed 585 by a Publish on the topic, followed at some time later by a read of 586 the updated value from the recent Publish. 588 Client1 Client2 Broker 589 | | Read | 590 | | --------------- GET /ps/topic1 -------------> | 591 | | | 592 | | <---------- 2.05 Content "1007.1"------------ | 593 | | | 594 | | | 595 | | Publish | 596 | ---------|----------- PUT /ps/topic1 "1033.3" --------> | 597 | | | 598 | | | 599 | | Read | 600 | | --------------- GET /ps/topic1 -------------> | 601 | | | 602 | | <----------- 2.05 Content "1033.3"----------- | 603 | | | 605 Figure 7: Example of READ 607 4.7. REMOVE 609 A CoAP pub/sub Client wishing to remove a topic can use the CoAP 610 Delete operation on the URI of the topic. The CoAP pub/sub Broker 611 MUST return "2.02 Deleted" if the remove operation is successful. 612 The broker MUST return the appropriate 4.xx response code indicating 613 the reason for failure if the topic can not be removed. 615 The REMOVE interface is specified as follows: 617 Interaction: Client -> Broker 619 Method: DELETE 621 URI Template: /{+ps}/{topic} 623 URI Template Variables: 625 ps := pub/sub Function Set path (mandatory). The path of the 626 pub/sub Function Set, as obtained from discovery. 628 topic := The desired topic to REMOVE. 630 Content-Format: None 632 Response Payload: None 634 The following response codes are defined for this interface: 636 Success: 2.02 "Deleted". Successful remove 638 Failure: 4.00 "Bad Request". Malformed request. 640 Failure: 4.01 "Unauthorized". Authorization failure. 642 Failure: 4.04 "Not Found". Topic does not exist. 644 Figure 8 shows a successful remove of topic1. 646 Client Broker 647 | | 648 | ------------- DELETE /ps/topic1 ------------> | 649 | | 650 | | 651 | <-------------- 2.02 Deleted ---------------- | 652 | | 654 Figure 8: Example of REMOVE 656 5. CoAP pub/sub Operation with Resource Directory 658 A CoAP pub/sub Broker may register a pub/sub Function Set with a 659 Resource Directory. A pub/sub Client may use an RD to discover a 660 pub/sub Broker. 662 A CoAP pub/sub Client may register CoRE Links [RFC6690] to created 663 pub/sub Topics with an RD. A pub/sub Client may use an RD to 664 discover pub/sub Topics. A client which registers pub/sub Topics 665 with an RD MUST use the context relation (con) 666 [I-D.ietf-core-resource-directory] to indicate that the context of 667 the registered links is the pub/sub Broker. 669 6. Sleep-Wake Operation 671 CoAP pub/sub provides a way for client nodes to sleep between 672 operations, conserving energy during idle periods. This is made 673 possible by shifting the server role to the broker, allowing the 674 broker to be always-on and respond to requests from other clients 675 while a particular client is sleeping. 677 For example, the broker will retain the last state update received 678 from a sleeping client, in order to supply the most recent state 679 update to other clients in response to read and subscribe operations. 681 Likewise, the broker will retain the last state update received on 682 the topic such that a sleeping client, upon waking, can perform a 683 read operation to the broker to update its own state from the most 684 recent system state update. 686 7. Simple Flow Control 688 Since the broker node has to potentially send a large amount of 689 notification messages for each publish message and it may be serving 690 a large amount of subscribers and publishers simultaneously, the 691 broker may become overwhelmed if it receives many publish messages to 692 popular topics in a short period of time. 694 If the broker is unable to serve a certain client that is sending 695 publish messages too fast, the broker MUST respond with Response Code 696 4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too 697 Many Requests" but uses the Max-Age Option in place of the "Retry- 698 After" header field to indicate the number of seconds after which to 699 retry. The broker MAY stop creating notifications from the publish 700 messages from this client and to this topic for the indicated time. 702 If a client receives the 4.29 Response Code from the broker for a 703 publish message to a topic, it MUST NOT send new publish messages to 704 the broker on the same topic before the time indicated in Max-Age has 705 passed. 707 8. Security Considerations 709 CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory 710 [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and 711 therefore the security considerations of those documents also apply 712 to this specification. Additionally, a CoAP pub/sub broker and the 713 clients SHOULD authenticate each other and enforce access control 714 policies. A malicious client could subscribe to data it is not 715 authorized to or mount a denial of service attack against the broker 716 by publishing a large number of resources. The authentication can be 717 performed using the already standardized DTLS offered mechanisms, 718 such as certificates. DTLS also allows communication security to be 719 established to ensure integrity and confidentiality protection of the 720 data exchanged between these relevant parties. Provisioning the 721 necessary credentials, trust anchors and authorization policies is 722 non-trivial and subject of ongoing work. 724 The use of a CoAP pub/sub broker introduces challenges for the use of 725 end-to-end security between for example a client device on a sensor 726 network and a client application running in a cloud-based server 727 infrastructure since brokers terminate the exchange. While running 728 separate DTLS sessions from the client device to the broker and from 729 broker to client application protects confidentially on those paths, 730 the client device does not know whether the commands coming from the 731 broker are actually coming from the client application. Similarly, a 732 client application requesting data does not know whether the data 733 originated on the client device. For scenarios where end-to-end 734 security is desirable the use of application layer security is 735 unavoidable. Application layer security would then provide a 736 guarantee to the client device that any request originated at the 737 client application. Similarly, integrity protected sensor data from 738 a client device will also provide guarantee to the client application 739 that the data originated on the client device itself. The protected 740 data can also be verified by the intermediate broker ensuring that it 741 stores/caches correct request/response and no malicious messages/ 742 requests are accepted. The broker would still be able to perform 743 aggregation of data/requests collected. 745 Depending on the level of trust users and system designers place in 746 the CoAP pub/sub broker, the use of end-to-end object security is 747 RECOMMENDED [I-D.selander-ace-object-security]. 749 9. IANA Considerations 751 This document registers one attribute value in the Resource Type 752 (rt=) registry established with [RFC6690] and appends to the 753 definition of one CoAP Response Code in the CoRE Parameters Registry. 755 9.1. Resource Type value 'core.ps' 757 o Attribute Value: core.ps 759 o Description: Section 4 of [[This document]] 761 o Reference: [[This document]] 763 o Notes: None 765 9.2. Response Code value '2.04' 767 o Response Code: 2.04 769 o Description: Add No Content response to GET to the existing 770 definition of the 2.04 response code. 772 o Reference: [[This document]] 774 o Notes: None 776 9.3. Response Code value '4.29' 778 o Response Code: 4.29 780 o Description: This error code is used by a server to indicate that 781 a client is making too many requests on a resource. 783 o Reference: [[This document]] 785 o Notes: None 787 10. Acknowledgements 789 The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit 790 Sethi, Peter Van der Stok, Tim Kellogg, Anders Eriksson, and Goran 791 Selander for their contributions and reviews. 793 11. References 795 11.1. Normative References 797 [I-D.ietf-core-observe] 798 Hartke, K., "Observing Resources in CoAP", draft-ietf- 799 core-observe-16 (work in progress), December 2014. 801 [I-D.ietf-core-resource-directory] 802 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 803 Resource Directory", draft-ietf-core-resource-directory-03 804 (work in progress), June 2015. 806 [I-D.selander-ace-object-security] 807 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 808 "June 29, 2015", draft-selander-ace-object-security-02 809 (work in progress), June 2015. 811 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 812 Requirement Levels", BCP 14, RFC 2119, March 1997. 814 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 815 Resource Identifier (URI): Generic Syntax", STD 66, RFC 816 3986, January 2005. 818 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 819 and D. Orchard, "URI Template", RFC 6570, March 2012. 821 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 822 Format", RFC 6690, August 2012. 824 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 825 Application Protocol (CoAP)", RFC 7252, June 2014. 827 11.2. Informative References 829 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 831 Authors' Addresses 833 Michael Koster 834 ARM Limited 836 Email: Michael.Koster@arm.com 838 Ari Keranen 839 Ericsson 841 Email: ari.keranen@ericsson.com 843 Jaime Jimenez 844 Ericsson 846 Email: jaime.jimenez@ericsson.com