Internet DRAFT - draft-koster-core-coap-pubsub
draft-koster-core-coap-pubsub
Network Working Group M. Koster
Internet-Draft ARM Limited
Intended status: Standards Track A. Keranen
Expires: May 8, 2016 J. Jimenez
Ericsson
November 5, 2015
Publish-Subscribe Broker for the Constrained Application Protocol (CoAP)
draft-koster-core-coap-pubsub-04
Abstract
The Constrained Application Protocol (CoAP), and related extensions
are intended to support machine-to-machine communication in systems
where one or more nodes are resource constrained, in particular for
low power wireless sensor networks. This document defines a publish-
subscribe broker for CoAP that extends the capabilities of CoAP for
supporting nodes with long breaks in connectivity and/or up-time.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 8, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Koster, et al. Expires May 8, 2016 [Page 1]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. CoAP pub/sub Architecture . . . . . . . . . . . . . . . . 4
3.2. CoAP pub/sub Broker . . . . . . . . . . . . . . . . . . . 4
3.3. CoAP pub/sub Client . . . . . . . . . . . . . . . . . . . 5
3.4. CoAP pub/sub Topic . . . . . . . . . . . . . . . . . . . 5
4. CoAP pub/sub Function Set . . . . . . . . . . . . . . . . . . 5
4.1. DISCOVER . . . . . . . . . . . . . . . . . . . . . . . . 5
4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 13
4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 15
5. CoAP pub/sub Operation with Resource Directory . . . . . . . 16
6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 17
7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 17
8. Security Considerations . . . . . . . . . . . . . . . . . . . 18
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 19
9.2. Response Code value '2.04' . . . . . . . . . . . . . . . 19
9.3. Response Code value '4.29' . . . . . . . . . . . . . . . 19
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1. Normative References . . . . . . . . . . . . . . . . . . 20
11.2. Informative References . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] supports
machine-to-machine communication across networks of constrained
devices. CoAP uses a request/response model where clients make
requests to servers in order to request actions on resources.
Depending on the situation the same device may act either as a server
or a client.
One important class of constrained devices includes devices that are
intended to run for years from a small battery, or by scavenging
energy from their environment. These devices have limited
reachability because they spend most of their time in a sleeping
Koster, et al. Expires May 8, 2016 [Page 2]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
state with no network connectivity. Devices may also have limited
reachability due to certain middle-boxes, such as Network Address
Translators (NATs) or firewalls. Such middle-boxes often prevent
connecting to a device from the Internet unless the connection was
initiated by the device.
This document specifies the means for nodes with limited reachability
to communicate using simple extensions to CoAP. The extensions
enable publish-subscribe communication using a broker node that
enables store-and-forward messaging between two or more nodes.
Furthermore the extensions facilitate many-to-many communication
using CoAP.
2. Terminology
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
specification are to be interpreted as described in [RFC2119].
This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC5988] and [RFC6690]. Readers
should also be familiar with the terms and concepts discussed in
[RFC7252] and [I-D.ietf-core-resource-directory]. The URI template
format [RFC6570] is used to describe the REST interfaces defined in
this specification.
This specification makes use of the following additional terminology:
Publish-Subscribe (pub/sub): A messaging paradigm where messages are
published to a broker and potential receivers can subscribe to the
broker to receive messages. The publishers do not (need to) know
where the message will be eventually sent: the publications and
subscriptions are matched by a broker and publications are
delivered by the broker to subscribed receivers.
CoAP pub/sub function set: A group of well-known REST resources that
together provide the CoAP pub/sub service.
CoAP pub/sub Broker: A server node capable of receiving messages
(publications) from and sending messages to other nodes, and able
to match subscriptions and publications in order to route messages
to the right destinations. The broker can also temporarily store
publications to satisfy future subscriptions.
CoAP pub/sub Client: A CoAP client that implements the CoAP pub/sub
function set.
Koster, et al. Expires May 8, 2016 [Page 3]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Topic: A unique identifier for a particular item being published
and/or subscribed to. A broker uses the topics to match
subscriptions to publications.
3. Architecture
3.1. CoAP pub/sub Architecture
Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/
sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/
sub interface which is hosted by the Broker. State information is
updated between the Clients and the Broker. The CoAP pub/sub Broker
performs a store-and-forward function of state updates between
certain CoAP pub/sub Clients. Clients Subscribe to state updates
which are Published by other Clients, and which are forwarded by the
Broker to the subscribing clients. The CoAP pub/sub Broker also acts
as a REST proxy, retaining the last state update provided by clients
to supply in response to Read requests from Clients.
Clients pub/sub Broker
+-------+ |
| CoAP | |
|pub/sub|---------|------+
|Client | | | +-------+
+-------+ | +----| CoAP |
| |pub/sub|
+-------+ | +----|Broker |
| CoAP | | | +-------+
|pub/sub|---------|------+
|Client | |
+-------+ |
Figure 1: CoAP pub/sub Architecture
3.2. CoAP pub/sub Broker
A CoAP pub/sub Broker is a CoAP Server that exposes an interface for
clients to use to initiate publish-subscribe interactions. Unlike
clients, the broker needs to be reachable by all clients. The broker
also needs to have sufficient resources (storage, bandwidth, etc.) to
host CoAP resources, and potentially buffer messages, on behalf of
the clients.
Koster, et al. Expires May 8, 2016 [Page 4]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
3.3. CoAP pub/sub Client
A CoAP pub/sub Client interacts with a CoAP pub/sub Broker using the
CoAP pub/sub interface. Clients initiate all interactions with the
CoAP pub/sub broker. A data source (e.g., sensor clients) can
publish state updates to the broker and data sinks (e.g., actuator
clients) can read from or subscribe to state updates from the broker.
Application clients can make use of both publish and subscribe in
order to exchange state updates with data sources and sinks.
3.4. CoAP pub/sub Topic
The clients and broker use topics to identify a particular resource
or object in a publish-subscribe system. Topics are conventionally
formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or
"EP-33543/sen/3303/0/5700". The topics are hosted at the broker and
all the clients using the broker share the same namespace for topics.
A CoAP pub/sub topic has a reference path using URI path [RFC3986]
construction, link attributes [RFC6690], and a representation of a
value with specified content-formats. A CoAP pub/sub topic value may
alternatively be a collection of one or more sub-topics, consisting
of links to the sub-topic URIs and indicated by a link-format
content-format.
4. CoAP pub/sub Function Set
This section defines the interfaces between a CoAP pub/sub Broker and
pub/sub Clients, which is called the CoAP pub/sub Function Set. The
examples throughout this section assume the use of CoAP [RFC7252]. A
CoAP pub/sub Broker implementing this specification MUST support the
DISCOVER, CREATE, PUBLISH, SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE
operations defined in this section.
4.1. DISCOVER
CoAP pub/sub Clients discover CoAP pub/sub Brokers by using CoAP
Simple Discovery or through a Resource Directory (RD)
[I-D.ietf-core-resource-directory]. A CoAP pub/sub Broker SHOULD
indicate its presence and availability on a network by exposing a
link to its pub/sub function set at its .well-known/core location
[RFC6690]. A CoAP pub/sub broker MAY register its pub/sub function
set location with a Resource Directory. Figure 2 shows an example of
a client discovering a local pub/sub Function Set using CoAP Simple
Discovery. A broker wishing to advertise the CoAP pub/sub Function
Set for Simple Discovery or through a Resource Directory MUST use the
link relation rt="core.ps". A broker MAY advertise it's supported
content formats and other attributes in the link to it's pub/sub
function set.
Koster, et al. Expires May 8, 2016 [Page 5]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
A CoAP pub/sub Broker MAY offer the Discover interface to enable
Clients to find topics of interest, either by topic name or by link
attributes which may be registered when the topic is created.
Figure 3 shows an example of a client looking for a topic with a
resource type (rt) of "temperature" in the pub/sub function set /ps
using the Discover interface. The client then receives the URI of
the resource and its content-format.
The DISCOVER interface is specified as follows:
Interaction: Client -> Broker
Method: GET
URI Template: /.well-known/core
URI Template: /{+ps/}{topic}{/topic*}{?q*}
URI Template Variables:
/.well-known/core := for discovering the pub/sub function set
(optional)
ps := pub/sub Function Set path (optional). The path of the
pub/sub Function Set, as obtained from discovery, used to
discover topics.
topic := The desired topic to return links for (optional).
q := Query Filter (optional). MAY contain a query filter list
as per [RFC6690] Section 4.1.
Content-Format: application/link-format
The following response codes are defined for this interface:
Success: 2.05 "Content" with an application/link-format payload
containing one or more matching entries for the broker resource.
A pub/sub broker SHOULD use the value "/ps/" for the function set
URI wherever possible.
Failure: 4.04 "Not Found" is returned in case no matching entry is
found for a unicast request.
Failure: 4.00 "Bad Request" is returned in case of a malformed
request for a unicast request.
Failure: No error response to a multicast request.
Koster, et al. Expires May 8, 2016 [Page 6]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Client Broker
| |
| ------ GET /.well-known/core?rt=core.ps ----->|
| ---Content-Format: application/link-format----|
| |
| <--2.05 Content "</ps/>;rt="core.ps";ct=40----|
| |
Figure 2: Example of DISCOVER pub/sub function
Client Broker
| |
| ---------- GET /ps/?rt="temperature" -------->|
| Content-Format: application/link-format |
| |
| <---2.05 Content |
| </ps/currentTemp>;rt="temperature";ct=50 ---|
| |
Figure 3: Example of DISCOVER topic
4.2. CREATE
Clients create topics on the broker using the CREATE interface. A
client wishing to create a topic MUST use CoAP POST to the pub/sub
function set location with a payload indicating the desired topic.
The topic specification sent in the payload MUST use a supported
serialization of the CoRE link format [RFC6690]. The target of the
link MUST be a URI formatted string. The client MUST indicate the
desired content format for publishes to the topic by using the ct
(Content Format) link attribute in the link-format payload. The
client MAY indicate the lifetime of the topic by including the Max-
Age option in the CREATE request. Broker MUST return a response code
of "2.01 Created" if the topic is created and return the created
relative URI path via Location-Path options. The broker MUST return
the appropriate 4.xx response code indicating the reason for failure
if a new topic can not be created. Broker SHOULD remove topics if
the Max-Age of the topic is exceeded without any publishes to the
topic. Broker SHOULD retain a topic indefinitely if the Max-Age
option is elided or is set to zero upon topic creation. The lifetime
of a topic MUST be refreshed upon create operations with a target of
an existing topic.
Topics may be created as sub-topics of other topics. A client MAY
create a topic with a ct (Content Format) link attribute value which
Koster, et al. Expires May 8, 2016 [Page 7]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
describes a supported serialization of the CoRE link format [RFC6690]
such as application/link-format (ct=40) or its JSON or CBOR
serializations. If a topic is created which describes a link
serialization, that topic may then have sub-topics created under it
as shown in Figure 5.
The CREATE interface is specified as follows:
Interaction: Client -> Broker
Method: POST
URI Template: /{+ps/}{topic}{/topic*}
URI Template Variables:
ps := pub/sub Function Set path (mandatory). The path of the
pub/sub Function Set, as obtained from discovery. A pub/sub
broker SHOULD use the value "ps" for this variable whenever
possible.
Content-Format: application/link-format
Payload: The desired topic to CREATE
The following response codes are defined for this interface:
Success: 2.01 "Created". Successful Creation of the topic
Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.03 "Forbidden". Topic already exists.
Failure: 4.06 "Not Acceptable". Unsupported content format for
topic.
Figure 4 shows an example of a topic called "topic1" being
successfully created.
Koster, et al. Expires May 8, 2016 [Page 8]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Client Broker
| |
| ---------- POST /ps "<topic1>;ct=50" -------->|
| |
| <---------------- 2.01 Created ---------------|
| Location: /ps/topic1 |
| |
Figure 4: Example of CREATE topic
Client Broker
| |
| ------- POST /ps/ "<mainTopic>;ct=40" ------->|
| |
| <---------------- 2.01 Created ---------------|
| Location: /ps/mainTopic/ |
| |
| --- POST /ps/mainTopic/ "<subTopic>;ct=50" -->|
| |
| <---------------- 2.01 Created ---------------|
| Location: /ps/mainTopic/subTopic |
| |
| |
Figure 5: Example of CREATE sub-topic
4.3. PUBLISH
A CoAP pub/sub Client uses the PUBLISH interface for updating topics
on the broker. The client MUST use the PUT method to publish state
updates to the CoAP pub/sub Broker. A client MUST use the content
format specified upon creation of a given topic to publish updates to
that topic. The broker MUST reject publish operations which do not
use the specified content format. A CoAP client publishing on a
topic MAY indicate the maximum lifetime of the value by including the
Max-Age option in the publish request. The broker MUST return a
response code of "2.04 Changed" if the publish is accepted or "4.04
Not Found" if the topic does not exist. A broker MAY return "4.29
Too Many Requests" if simple flow control as described in Section 7
is implemented.
The Broker MUST notify all clients subscribed on a particular topic
each time it receives a publish on that topic. An example is shown
in Figure 7. If a client publishes to a broker with the Max-Age
option, the broker MUST include the same value for the Max-Age option
Koster, et al. Expires May 8, 2016 [Page 9]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
in all notifications. A broker MUST use CoAP Notification as
described in [RFC7641] to notify subscribed clients.
The PUBLISH interface is specified as follows:
Interaction: Client -> Broker
Method: PUT
URI Template: /{+ps/}{topic}{/topic*}
URI Template Variables:
ps := pub/sub Function Set path (mandatory). The path of the
pub/sub Function Set, as obtained from discovery.
topic := The desired topic to publish on.
Content-Format: Any valid CoAP content format
Payload: Representation of the topic value (CoAP resource state
representation) in the indicated content format
The following response codes are defined for this interface:
Success: 2.04 "Changed". Successful publish, topic is updated
Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist.
Failure: 4.29 "Too Many Requests". The client should slow down the
rate of publish messages for this topic (see Section 7).
Figure 6 shows an example of a new value being successfully published
to the topic "topic1". See Figure 7 for an example of a broker
forwarding a message from a publishing client to a subscribed client.
Koster, et al. Expires May 8, 2016 [Page 10]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Client Broker
| |
| ---------- PUT /ps/topic1 "1033.3" --------> |
| |
| |
| <--------------- 2.04 Changed---------------- |
| |
Figure 6: Example of PUBLISH
4.4. SUBSCRIBE
CoAP pub/sub Clients subscribe to topics on the Broker using CoAP
Observe as described in [RFC7641]. A CoAP pub/sub Client wishing to
Subscribe to a topic on a broker MUST use a CoAP GET with Observe
registration. The Broker MAY add the client to a list of observers.
The Broker MUST return a response code of "2.05 Content" along with
the most recently published value if the topic contains a valid value
and the broker can supply the requested content format. The broker
MUST accept Subscribe requests on a topic if the content format of
the request matches the content format the topic was created with.
The broker MAY accept Subscribe requests which specify content
formats that the broker can supply as alternate content formats to
the content format the topic was registered with. If the topic was
published with the Max-Age option, the broker MUST set the Max-Age
option in the valid response to the amount of time remaining for the
value to be valid since the last publish operation on that topic.
The Broker MUST return a response code of "2.04 No Content" if the
Max-Age of the previously stored value has expired. The Broker MUST
return a response code "4.04 Not Found" if the topic does not exist
or has been removed. The Broker MUST return a response code "4.15
Unsupported Content Format" if it can not return the requested
content format. If a Broker is unable to accept a new Subscription
on a topic, it SHOULD return the appropriate response code without
the Observe option as per as per [RFC7641] Section 4.1. There is no
explicit maximum lifetime of a Subscription, thus a Broker may remove
subscribers at any time. The Broker, upon removing a Subscriber,
will transmit the appropriate response code without the Observe
option, as per [RFC7641] Section 4.2, to the removed Subscriber.
The SUBSCRIBE interface is specified as follows:
Interaction: Client -> Broker
Method: GET
Options: Observe:0
Koster, et al. Expires May 8, 2016 [Page 11]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
URI Template: /{+ps/}{topic}{/topic*}
URI Template Variables:
ps := pub/sub Function Set path (mandatory). The path of the
pub/sub Function Set, as obtained from discovery.
topic := The desired topic to subscribe to.
The following response codes are defined for this interface:
Success: 2.05 "Content". Successful subscribe, current value
included
Success: 2.04 "No Content". Successful subscribe, value not
included
Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist.
Failure: 4.15 "Unsupported Content Format". Unsupported content
format.
Figure 7 shows an example of Client2 subscribing to "topic1" and
receiving a response from the broker, with a subsequent notification.
The subscribe response from the broker uses the last stored value
associated with the topic1. The notification from the broker is sent
in response to the publish received from Client1.
Client1 Client2 Broker
| | Subscribe |
| | ----- GET /ps/topic1 Observe:0 Token:XX ----> |
| | |
| | <---------- 2.05 Content Observe:10---------- |
| | |
| | |
| | Publish |
| ---------|----------- PUT /ps/topic1 "1033.3" --------> |
| | Notify |
| | <---------- 2.05 Content Observe:11---------- |
| | |
Figure 7: Example of SUBSCRIBE
Koster, et al. Expires May 8, 2016 [Page 12]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
4.5. UNSUBSCRIBE
CoAP pub/sub Clients unsubscribe from topics on the Broker using the
CoAP Cancel Observation operation. A CoAP pub/sub Client wishing to
unsubscribe to a topic on a Broker MUST either use CoAP GET with
Observe using an Observe parameter of 1 or send a CoAP Reset message
in response to a publish, as per [RFC7641].
The UNSUBSCRIBE interface is specified as follows:
Interaction: Client -> Broker
Method: GET
Options: Observe:1
URI Template: /{+ps/}{topic}{/topic*}
URI Template Variables:
ps := pub/sub Function Set path (mandatory). The path of the
pub/sub Function Set, as obtained from discovery.
topic := The desired topic to unsubscribe from.
The following response codes are defined for this interface:
Success: 2.05 "Content". Successful unsubscribe, current value
included
Success: 2.04 "No Content". Successful unsubscribe, value not
included
Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist.
Figure 8 shows an example of a client unsubscribe using the Observe=1
cancellation method.
Koster, et al. Expires May 8, 2016 [Page 13]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Client Broker
| |
| ----- GET /ps/topic1 Observe:1 Token:XX ----> |
| |
| <------------- 2.05 Content ----------------- |
| |
Figure 8: Example of UNSUBSCRIBE
4.6. READ
A CoAP pub/sub client wishing to obtain only the most recent
published value on a topic MAY use the READ interface. For reading,
the client uses the CoAP GET method. The broker MUST accept Read
requests on a topic if the content format of the request matches the
content format the topic was created with. The broker MAY accept
Read requests which specify content formats that the broker can
supply as alternate content formats to the content format the topic
was registered with. The Broker MUST return a response code of "2.05
Content" along with the most recently published value if the topic
contains a valid value and the broker can supply the requested
content format. If the topic was published with the Max-Age option,
the broker MUST set the Max-Age option in the valid response to the
amount of time remaining for the topic to be valid since the last
publish. The Broker MUST return a response code of "2.04 No Content"
if the Max-Age of the previously stored value has expired. The
Broker MUST return a response code "4.04 Not Found" if the topic does
not exist or has been removed. The Broker MUST return a response
code "4.15 Unsupported Content Format" if the broker can not return
the requested content format.
The READ interface is specified as follows:
Interaction: Client -> Broker
Method: GET
URI Template: /{+ps/}{topic}{/topic*}
URI Template Variables:
ps := pub/sub Function Set path (mandatory). The path of the
pub/sub Function Set, as obtained from discovery.
topic := The desired topic to READ.
The following response codes are defined for this interface:
Koster, et al. Expires May 8, 2016 [Page 14]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Success: 2.05 "Content". Successful READ, current value included
Success: 2.04 "No Content". Topic exists, value not included
Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist.
Failure: 4.15 "Unsupported Content Format". Unsupported content-
format.
Figure 9 shows an example of a successful READ from topic1, followed
by a Publish on the topic, followed at some time later by a read of
the updated value from the recent Publish.
Client1 Client2 Broker
| | Read |
| | --------------- GET /ps/topic1 -------------> |
| | |
| | <---------- 2.05 Content "1007.1"------------ |
| | |
| | |
| | Publish |
| ---------|----------- PUT /ps/topic1 "1033.3" --------> |
| | |
| | |
| | Read |
| | --------------- GET /ps/topic1 -------------> |
| | |
| | <----------- 2.05 Content "1033.3"----------- |
| | |
Figure 9: Example of READ
4.7. REMOVE
A CoAP pub/sub Client wishing to remove a topic MAY use the CoAP
Delete operation on the URI of the topic. The CoAP pub/sub Broker
MUST return "2.02 Deleted" if the remove operation is successful.
The broker MUST return the appropriate 4.xx response code indicating
the reason for failure if the topic can not be removed. When a topic
is removed for any reason, the Broker SHOULD return the response code
4.04 Not Found and remove all of the observers from the list of
observers as per as per [RFC7641] Section 3.2.
Koster, et al. Expires May 8, 2016 [Page 15]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
The REMOVE interface is specified as follows:
Interaction: Client -> Broker
Method: DELETE
URI Template: /{+ps/}{topic}{/topic*}
URI Template Variables:
ps := pub/sub Function Set path (mandatory). The path of the
pub/sub Function Set, as obtained from discovery.
topic := The desired topic to REMOVE.
Content-Format: None
Response Payload: None
The following response codes are defined for this interface:
Success: 2.02 "Deleted". Successful remove
Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist.
Figure 10 shows a successful remove of topic1.
Client Broker
| |
| ------------- DELETE /ps/topic1 ------------> |
| |
| |
| <-------------- 2.02 Deleted ---------------- |
| |
Figure 10: Example of REMOVE
5. CoAP pub/sub Operation with Resource Directory
A CoAP pub/sub Broker may register a pub/sub Function Set with a
Resource Directory. A pub/sub Client may use an RD to discover a
pub/sub Broker.
Koster, et al. Expires May 8, 2016 [Page 16]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
A CoAP pub/sub Client may register CoRE Links [RFC6690] to created
pub/sub Topics with an RD. A pub/sub Client may use an RD to
discover pub/sub Topics. A client which registers pub/sub Topics
with an RD MUST use the context relation (con)
[I-D.ietf-core-resource-directory] to indicate that the context of
the registered links is the pub/sub Broker.
6. Sleep-Wake Operation
CoAP pub/sub provides a way for client nodes to sleep between
operations, conserving energy during idle periods. This is made
possible by shifting the server role to the broker, allowing the
broker to be always-on and respond to requests from other clients
while a particular client is sleeping.
For example, the broker will retain the last state update received
from a sleeping client, in order to supply the most recent state
update to other clients in response to read and subscribe operations.
Likewise, the broker will retain the last state update received on
the topic such that a sleeping client, upon waking, can perform a
read operation to the broker to update its own state from the most
recent system state update.
7. Simple Flow Control
Since the broker node has to potentially send a large amount of
notification messages for each publish message and it may be serving
a large amount of subscribers and publishers simultaneously, the
broker may become overwhelmed if it receives many publish messages to
popular topics in a short period of time.
If the broker is unable to serve a certain client that is sending
publish messages too fast, the broker MUST respond with Response Code
4.29, "Too Many Requests". This Response Code is like HTTP 429 "Too
Many Requests" but uses the Max-Age Option in place of the "Retry-
After" header field to indicate the number of seconds after which to
retry. The broker MAY stop creating notifications from the publish
messages from this client and to this topic for the indicated time.
If a client receives the 4.29 Response Code from the broker for a
publish message to a topic, it MUST NOT send new publish messages to
the broker on the same topic before the time indicated in Max-Age has
passed.
Koster, et al. Expires May 8, 2016 [Page 17]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
8. Security Considerations
CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory
[I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and
therefore the security considerations of those documents also apply
to this specification. Additionally, a CoAP pub/sub broker and the
clients SHOULD authenticate each other and enforce access control
policies. A malicious client could subscribe to data it is not
authorized to or mount a denial of service attack against the broker
by publishing a large number of resources. The authentication can be
performed using the already standardized DTLS offered mechanisms,
such as certificates. DTLS also allows communication security to be
established to ensure integrity and confidentiality protection of the
data exchanged between these relevant parties. Provisioning the
necessary credentials, trust anchors and authorization policies is
non-trivial and subject of ongoing work.
The use of a CoAP pub/sub broker introduces challenges for the use of
end-to-end security between for example a client device on a sensor
network and a client application running in a cloud-based server
infrastructure since brokers terminate the exchange. While running
separate DTLS sessions from the client device to the broker and from
broker to client application protects confidentially on those paths,
the client device does not know whether the commands coming from the
broker are actually coming from the client application. Similarly, a
client application requesting data does not know whether the data
originated on the client device. For scenarios where end-to-end
security is desirable the use of application layer security is
unavoidable. Application layer security would then provide a
guarantee to the client device that any request originated at the
client application. Similarly, integrity protected sensor data from
a client device will also provide guarantee to the client application
that the data originated on the client device itself. The protected
data can also be verified by the intermediate broker ensuring that it
stores/caches correct request/response and no malicious messages/
requests are accepted. The broker would still be able to perform
aggregation of data/requests collected.
Depending on the level of trust users and system designers place in
the CoAP pub/sub broker, the use of end-to-end object security is
RECOMMENDED [I-D.selander-ace-object-security].
When only end-to-end encryption is necessary and the CoAP Broker is
trusted, Payload Only Protection (Mode:PAYL) could be used. The
Publisher would wrap only the payload before sending it to the broker
and set the option Content-Format to application/smpayl. Upon
receival, the Broker can read the unencrypted CoAP header to forward
it to the subscribers.
Koster, et al. Expires May 8, 2016 [Page 18]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
9. IANA Considerations
This document registers one attribute value in the Resource Type
(rt=) registry established with [RFC6690] and appends to the
definition of one CoAP Response Code in the CoRE Parameters Registry.
9.1. Resource Type value 'core.ps'
o Attribute Value: core.ps
o Description: Section 4 of [[This document]]
o Reference: [[This document]]
o Notes: None
9.2. Response Code value '2.04'
o Response Code: 2.04
o Description: Add No Content response to GET to the existing
definition of the 2.04 response code.
o Reference: [[This document]]
o Notes: None
9.3. Response Code value '4.29'
o Response Code: 4.29
o Description: This error code is used by a server to indicate that
a client is making too many requests on a resource.
o Reference: [[This document]]
o Notes: None
10. Acknowledgements
The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit
Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran
Selander, Mikko Majanen, and Olaf Bergmann for their contributions
and reviews.
Koster, et al. Expires May 8, 2016 [Page 19]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
11. References
11.1. Normative References
[I-D.ietf-core-resource-directory]
Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE
Resource Directory", draft-ietf-core-resource-directory-05
(work in progress), October 2015.
[I-D.selander-ace-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security of CoAP (OSCOAP)", draft-selander-ace-
object-security-03 (work in progress), October 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
<http://www.rfc-editor.org/info/rfc6570>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>.
11.2. Informative References
[RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>.
Koster, et al. Expires May 8, 2016 [Page 20]
Internet-Draft Publish-Subscribe Broker for CoAP November 2015
Authors' Addresses
Michael Koster
ARM Limited
Email: Michael.Koster@arm.com
Ari Keranen
Ericsson
Email: ari.keranen@ericsson.com
Jaime Jimenez
Ericsson
Email: jaime.jimenez@ericsson.com
Koster, et al. Expires May 8, 2016 [Page 21]
