From 5462ab078d6ae71c1dfe8b509c07bf6c86f61274 Mon Sep 17 00:00:00 2001 From: Jaime Jimenez Date: Sun, 20 Oct 2024 15:29:14 +0300 Subject: [PATCH] trigger cli --- draft-ietf-core-coap-pubsub.md | 7 +- draft-ietf-core-coap-pubsub.v2v3.xml | 2071 ---------------- reference/draft-ietf-core-coap-pubsub-14.xml | 2228 ++++++++++++++++++ 3 files changed, 2229 insertions(+), 2077 deletions(-) delete mode 100644 draft-ietf-core-coap-pubsub.v2v3.xml create mode 100644 reference/draft-ietf-core-coap-pubsub-14.xml diff --git a/draft-ietf-core-coap-pubsub.md b/draft-ietf-core-coap-pubsub.md index 1d16b58..1e1c5db 100644 --- a/draft-ietf-core-coap-pubsub.md +++ b/draft-ietf-core-coap-pubsub.md @@ -87,12 +87,7 @@ This document applies the idea of broker-based publish-subscribe to Constrained {::boilerplate bcp14} -This specification requires readers to be familiar with all the terms and -concepts that are discussed in {{?RFC8288}} and {{!RFC6690}}. Readers -should also be familiar with the terms and concepts discussed in -{{!RFC7252}}, {{!RFC9176}} and {{!RFC7641}}. The URI template -format {{!RFC6570}} is used to describe the REST API defined in -this specification. +This specification requires readers to be familiar with all the terms and concepts that are discussed in {{?RFC8288}} and {{!RFC6690}}. Readers should also be familiar with the terms and concepts discussed in {{!RFC7252}}, {{!RFC9176}} and {{!RFC7641}}. The URI template format {{!RFC6570}} is used to describe the REST API defined in this specification. This specification makes use of the following terminology: diff --git a/draft-ietf-core-coap-pubsub.v2v3.xml b/draft-ietf-core-coap-pubsub.v2v3.xml deleted file mode 100644 index e3ca605..0000000 --- a/draft-ietf-core-coap-pubsub.v2v3.xml +++ /dev/null @@ -1,2071 +0,0 @@ - - - - - -]> - - - - - - A publish-subscribe architecture for the Constrained Application Protocol (CoAP) - - - Ericsson -
- jaime@iki.fi -
- - - Dogtiger Labs -
- michaeljohnkoster@gmail.com -
- - - Ericsson -
- ari.keranen@ericsson.com -
- - - Applications - CoRE Working Group - - - -This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker. - - - About This Document - - Status information for this document may be found at . - - - Discussion of this document takes place on the - core Working Group mailing list (), - which is archived at . - Subscribe at . - - Source for this draft and an issue tracker can be found at - . - - - - - -
- Introduction - The Constrained Application Protocol (CoAP) supports -machine-to-machine communication across networks of constrained -devices and constrained networks. 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, a client, or both. - 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 up-time because they spend most of their time in a sleeping state with no network connectivity. Another important class of nodes are devices with limited reachability due to middle-boxes like Network Address Translators (NATs) and firewalls. - For these nodes, the client/server-oriented architecture of REST can be challenging when interactions are not initiated by the devices themselves. A publish/subscribe-oriented architecture where nodes exchange data via topics through a broker entity might fit these nodes better. - This document applies the idea of broker-based publish-subscribe to Constrained RESTful Environments using CoAP. It defines a broker that allows to create, discover subscribe and publish on topics. -
- Terminology - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", -"MAY", and "OPTIONAL" in this document are to be interpreted as -described in BCP 14 when, and only when, they -appear in all capitals, as shown here. - - - This specification requires readers to be familiar with all the terms and -concepts that are discussed in and . Readers -should also be familiar with the terms and concepts discussed in -, and . The URI template -format is used to describe the REST API defined in -this specification. - This specification makes use of the following terminology: -
-
publish-subscribe (pub/sub):
-
- A message communication model where messages associated with specific topics are sent to a broker. Interested parties, i.e. subscribers, receive these topic-based messages from the broker without the original sender knowing the recipients. The broker handles matching and delivering these messages to the appropriate subscribers. -
-
publishers and subscribers:
-
- CoAP clients can act as publishers or as subscribers. Publishers send CoAP messages (publications) to the broker on specific topics. Subscribers have an ongoing observation relation (subscription) to a topic. Both roles operate without any mutual knowledge, guided by their respective topic interests. -
-
topic collection:
-
- A set of topic configurations. A topic collection is hosted as one collection resource at the broker, and its representation is the list of links to the topic resources corresponding to each topic configuration. -
-
topic-configuration:
-
- A set of information concerning a topic, including its configuration and other metadata. A topic configuration is hosted as one topic resource at the broker, and its representation is the set of configuration information concerning the topic. All the topic resources associated with the same topic collection share a common base URI, i.e., the URI of the collection resource. Throughout this document the word "topic" and "topic-configuration" can be used interchangeably. -
-
topic-data resource:
-
- A resource where clients can publish data and/or subscribe to data for a specific topic. The representation of the topic resource corresponding to such a topic also specifies the URI to the present topic-data resource. -
-
broker:
-
- A CoAP server that hosts one or more topic collections with their topic-configurations, and also topic-data resources. The broker is responsible for the store-and-forward of state update representations, for the topics for which it hosts the corresponding topic-data resources. The broker is also responsible of handling the topic lifecycle as defined in . The creation, configuration, and discovery of topics at a broker is specified in . -
-
-
-
- CoAP Publish-Subscribe Architecture - shows a simple Publish/Subscribe architecture over CoAP. - Topics are created by the broker, but the initial configuration can be proposed by a client (e.g., a publisher or a dedicated administrator) over the RESTful interface of a corresponding topic resource hosted by the broker. - Publishers submit their data over the RESTful interface of a topic-data resource corresponding to the topic, which may be hosted by the broker. Subscribers to a topic are notified of new publications by using Observe on the corresponding topic-data resource. - The broker is responsible for the store-and-forward of state update representations between CoAP clients. Subscribers observing a resource will receive notifications, the delivery of which is done on a best-effort basis. -
- Publish-subscribe architecture over CoAP - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CoAP - CoAP - CoAP - clients - server - clients - observe - publish - publisher - subscriber - ... - broker - ... - ... - ... - observe - publish - publisher - subscriber - - - - + +---------->| subscriber | - | | | +---------->| | - '-----------' | | '------------' - ... | broker | ... - ... | | ... - .-----------. | | observe .------------. - | | publish | |<----------+ | - | publisher +--------->| +---------->| subscriber | - | | | +---------->| | - '-----------' '----------' '------------' -]]> - -
- This document describes two sets of interactions, interactions to configure topics and their lifecycle (see ) and interactions about the topic-data (see ). - Topic-configuration interactions are discovery, create, read configuration, update configuration, and delete configuration. These operations handle the management of the topics. - Topic-data interactions are publish, subscribe, unsubscribe, read, and delete. These operations are oriented on how data is transferred from a publisher to a subscriber. - - -
-
- Managing Topics - shows the resources related to a Topic Collection that can be managed at the Broker. -
- Resources of a Broker - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - topic - collection - resource - ... - topic - resources - - - - - -
- The Broker exports one or more topic-collection resources, with resource type "core.ps.coll" defined in of this document. The interfaces for the topic-collection resource is defined in . - A topic-collection resource can have topic resources as its child resources, with resource type "core.ps.conf". -
-
-
- Pub-Sub Topics - The configuration side of a "publish/subscribe broker" consists of a collection of topics. These topics as well as the collection itself are exposed by a CoAP server as resources (see ). Each topic is associated with a topic configuration resource and a topic-data resource. The topic configuration resource is used by a client creating or administering a topic. The topic-data resource is used by the publishers and the subscribers to a topic. -
- Topic and topic-data resources of a topic - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - topic - collection - resource - ...... - ...... - ...... - topic - : - : - : - : - : - : - configuration - : - : - : - : - : - : - resource - : - _ - _ - : - : - _ - _ - : - : - _ - _ - : - .... - .... - .... - .... - .... - .... - .... - .... - .... - .... - .... - .... - : - _ - _ - : - : - _ - _ - : - ... - : - _ - _ - : - topic-data - : - : - : - : - : - : - resource - : - : - : - : - : - : - :.......: - :.......: - :.......: - \ - / - ... - \ - / - topic - 1 - topic - 2 - topic - n - - - - - -
-
- Collection Representation - Each topic configuration is represented as a link, where the link target is the URI of the corresponding topic resource. - Publication and subscription to a topic occur at a link, where the link target is the URI of the corresponding topic-data resource. Such a link is specified by the topic-data entry within the topic resource (see ). - A topic resource with a topic-data link can also be simply called "topic". - The list of links to the topic resources can be retrieved from the associated topic collection resource, and represented as a Link Format document where each such link specifies the link target attribute 'rt' (Resource Type), with value "core.ps.conf" defined in this document. -
-
- Topic-Configuration Representation - A CoAP client can create a new topic by submitting an initial configuration for the topic (see ). It can also read and update the configuration of existing topics and delete them when they are no longer needed (see ). - The configuration of a topic itself consists of a set of properties that can be set by a client or by the broker. The topic-configuration is represented as a CBOR map containing the configuration properties of the topic as top-level elements. - Unless specified otherwise, these are defined in this document and their CBOR abbreviations are defined in . -
- Topic Properties - The CBOR map includes the following configuration parameters, whose CBOR abbreviations are defined in of this document. -
    -
  • - 'topic-name': A required field used as an application identifier. It encodes the topic name as a CBOR text string. Examples of topic names include human-readable strings (e.g., "room2"), UUIDs, or other values. -
    • -
  • - 'topic-data': A required field (optional during creation) containing the URI of the topic-data resource for publishing/subscribing to this topic. It encodes the URI as a CBOR text string. -
    • -
  • - 'resource-type': A required field used to indicate the resource type of the topic-data resource for the topic. It encodes the resource type as a CBOR text string. The value should be "core.ps.conf". -
    • -
- - -
    -
  • - 'media-type': An optional field used to indicate the media type of the topic-data resource for the topic. It encodes the media type as a this information as the integer identifier of the CoAP content-format (e.g., value is "50" for "application/json"). -
    • -
  • - 'topic-type': An optional field used to indicate the attribute or property of the topic-data resource for the topic. It encodes the attribute as a CBOR text string. Example attributes include "temperature". -
    • -
  • - 'expiration-date': An optional field used to indicate the expiration date of the topic. It encodes the expiration date as a CBOR text string. The value should be a date string in ISO 8601 format (e.g., "2023-03-31T23:59:59Z"). The broker can use this field to automatically remove topics that are no longer valid. If this field is not present, the topic will not expire automatically. -
    • -
  • - 'max-subscribers': An optional field used to indicate the maximum number of simultaneous subscribers allowed for the topic. It encodes the maximum number as an unsigned CBOR integer. If this field is not present, there is no limit to the number of simultaneous subscribers allowed. The broker can use this field to limit the number of subscribers for the topic. The default value for this field has been set to 100 subscribers. -
    • -
  • - 'observer-check': An optional field that controls the maximum number of seconds between two consecutive Observe notifications sent as Confirmable messages to each topic subscriber. Encoded as a CBOR unsigned integer greater than 0, it ensures subscribers who have lost interest and silently forgotten the observation do not remain indefinitely on the server's observer list. If another CoAP server hosts the topic-data resource, that server is responsible for applying the observer-check value. The default value for this field is 86400, as defined in , which corresponds to 24 hours. -
    • -
-
-
-
- Discovery - A client can perform a discovery of: the broker; the topic collection resources and topic resources hosted by the broker; and the topic-data resources associated with those topic resources. -
- Broker Discovery - CoAP clients MAY discover brokers by using CoAP Simple Discovery, via multicast, through a Resource Directory (RD) or by other means specified in extensions to . Brokers MAY register with a RD by following the steps on Section 5 of with the resource type set to "core.ps" as defined in of this document. - The following example shows an endpoint discovering a broker using the "core.ps" resource type over a multicast network. Brokers within the multicast scope will answer the query. - 0.01 GET - Uri-Path: coap://[ff0x::fe]/.well-known/core - Resource-Type: core.ps - -<= 2.05 Content - Payload: - Content-Format: 40 (application/link-format) - ; rt=core.ps -]]> -
-
- Topic Collection Discovery - A Broker SHOULD offer a topic discovery entry point to enable clients to find topics of interest. The resource entry point is the topic collection resource collecting the topic configurations for those topics (see Section 1.2.2 of ) and is identified by the resource type "core.ps.coll". - The specific resource path is left for implementations, examples in this document use the "/ps" path. The interactions with a topic collection are further defined in . - Since the representation of the topic collection resource includes the links to the associated topic resources, it is not required to locate those links under "/.well-known/core", also in order to limit the size of the Link Format document returned as result of the discovery. - Example: - 0.01 GET - Uri-Path: .well-known/core - Resource-Type: core.ps.coll - - <= 2.05 Content - Content-Format: 40 (application/link-format) - ;rt="core.ps.coll";ct=40, - ;rt="core.ps.coll";ct=40 -]]> -
-
- Topic-Configuration Discovery - Each topic collection is associated with a group of topic resources, each detailing the configuration of its respective topic (refer to ). Each topic resource is identified by the resource type "core.ps.conf". - Below is an example of discovery via /.well-known/core with rt=core.ps.conf that returns a list of topics, as the list of links to the corresponding topic resources. - - - 0.01 GET - Uri-Path: .well-known/core - Resource-Type: core.ps.conf - -<= 2.05 Content - Content-Format: 40 (application/link-format) - ;rt="core.ps.conf";ct=TBD, - ;rt=core.ps.conf;ct=TBD -]]> -
-
- Topic-Data Discovery - - -Within a topic, there is the topic-data property containing the URI of the topic-data resource that a CoAP client can subscribe and publish to. Resources exposing resources of the topic-data type are expected to use the resource type 'core.ps.data'. - The topic-data contains the URI of the topic-data resource for publishing and subscribing. So retrieving the topic configuration will also provide the URL of the topic-data (see ). - It is also possible to discover a list of topic-data resources by sending a request to the collection with with rt=core.ps.data resources as shown below. - 0.01 GET - Uri-Path: /ps - Resource-Type: core.ps.data - -<= 2.05 Content - Content-Format: 40 (application/link-format) - ; rt=core.ps.data; obs -]]> -
-
-
- Topic Collection Interactions - These are the interactions that can happen directly with a specific topic collection. -
- Retrieving all topic-configurations - A client can request a collection of the topics present in the broker by making a GET request to the collection URI. - On success, the server returns a 2.05 (Content) response, specifying the list of links to topic resources associated with this topic collection (see ). - Depending on its granted permissions, a client MAY retrieve a different list of links, corresponding to the topics that the client is authorized to access. - Example: - 0.01 GET - Uri-Path: ps - -<= 2.05 Content - Content-Format: 40 (application/link-format) - ;rt="core.ps.conf", - ; rt="core.ps.conf" -]]> -
-
- Getting topic-configurations by Properties - - -A client can filter a collection of topics by submitting the -representation of a topic filter (see ) in a FETCH request to the topic collection URI. - On success, the server returns a 2.05 (Content) response with a -representation of a list of topics in the collection (see - ) that match the filter in CoRE link format . - Upon success, the server responds with a 2.05 (Content), providing a list of links to topic resources associated with this topic collection that match the request's filter criteria (refer to ). A positive match happens only when each request parameter is present with the indicated value in the topic resource representation. - Example: - 0.05 FETCH - Uri-Path: ps - Content-Format: TBD (application/pubsub+cbor) - - { - "resource-type": "core.ps.conf", - "topic-type": "temperature" - } - -<= 2.05 Content - Content-Format: 40 (application/link-format) - ;rt="core.ps.conf" -]]> -
-
- Creating a Topic - - -A client can add a new topic-configurations to a collection of topics by submitting an initial representation of the initial topic resource (see ) in a POST request to the topic collection URI. The request MUST specify at least a subset of the properties in , namely: topic-name and resource-type. - - -Please note that the topic will NOT be fully created until a publisher has published some data to it (See ). - On success, the server returns a 2.01 (Created) response, indicating the Location-Path of the new topic and the current representation of the topic resource. The response payload includes a CBOR map with key-value pairs. The response must include the required topic properties (see ), namely: "topic-name", "resource-type" and "topic-data". It may also include a number of optional properties too. - If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor". - The broker MUST issue a 4.00 (Bad Request) error if a received parameter is invalid, unrecognized, or if the topic-name is already in use or otherwise invalid. - - - 0.02 POST - Uri-Path: ps - Content-Format: TBD2 (application/core-pubsub+cbor) - TBD (this should be a CBOR map with the mandatory parameters) - { - "topic-name": "living-room-sensor", - "resource-type": "core.ps.conf" - } - -<= 2.01 Created - Location-Path: ps/h9392 - Content-Format: TBD2 (application/core-pubsub+cbor) - - TBD (this should be a CBOR map) - { - "topic-name": "living-room-sensor", - "topic-data": "ps/data/1bd0d6d", - "resource-type": "core.ps.conf" - } -]]> -
-
-
- Topic-Configuration Interactions - These are the interactions that can happen at the topic resource level. -
- Getting a topic-configuration - - -A client can read the configuration of a topic by making a GET request to the topic resource URI. - On success, the server returns a 2.05 (Content) response with a partial representation of the topic resource, as specified in . The partial representation includes only the configuration parameters such that they are present and have the same value in both the current topic configuration as well as in the FETCH request. - If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. - The response payload is a CBOR map, whose possible entries are specified in and use the same abbreviations defined in . - For example, below is a request on the topic "ps/h9392": - 0.01 GET - Uri-Path: ps - Uri-Path: h9392 - -<= 2.05 Content - Content-Format: TBD2 (application/core-pubsub+cbor) - { - "topic-name" : "living-room-sensor", - "topic-data" : "ps/data/1bd0d6d", - "resource-type": "core.ps.conf", - "media-type": "application/senml-cbor", - "topic-type": "temperature", - "expiration-date": "2023-04-00T23:59:59Z", - "max-subscribers": 100 - } - -]]> -
-
- Getting part of a topic-configuration - - -A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific parameters. This is done in order to retrieve part of the current topic resource. - The request contains a CBOR map with a configuration filter or 'conf-filter', a CBOR array with CBOR abbreviation. Each element of the array specifies one requested configuration parameter of the current topic resource (see ). - On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the partial representation of the topic resource as specified in . - If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. - The response payload is a CBOR map, whose possible entries are specified in and use the same abbreviations defined in . - Both request and response MUST have Content-Format set to "application/core-pubsub+cbor". - Example: - 0.05 FETCH - Uri-Path: ps - Uri-Path: h9392 - Content-Format: TBD2 (application/core-pubsub+cbor) - { - "conf-filter": ["topic-data", "media-type"] - } - -<= 2.05 Content - Content-Format: TBD2 (application/core-pubsub+cbor) - { - "topic-data": "ps/data/1bd0d6d", - "media-type": "application/senml-cbor" - } - -]]> -
-
- Updating the topic-configuration - - -A client can update a topic's configuration by submitting the updated topic representation in a PUT request to the topic URI. However, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker. - On success, the topic configuration is overwritten and server returns a 2.04 (Changed) response and the current full resource representation. The broker may chose not to overwrite parameters that are not explicitly modified in the request. - Note that updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Updating the "topic-data" may happen also after it being deleted, as described on {delete-topic-data}, this will in turn create a new "topic-data" path for that topic configuration. - Similarly, decreasing max-subscribers will also cause that some subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per Section 3.2. - Please note that when using PUT the topic configuration is being overwritten, thus some of the optional parameters (e.g., "max-subscribers", "observer-check") not included in the PUT message will be reset to their default values. - Example: - 0.03 PUT - Uri-Path: ps - Uri-Path: h9392 - Content-Format: TBD2 (application/core-pubsub+cbor) - - { - "topic-name": "living-room-sensor", - "topic-data": "ps/data/1bd0d6d", - "resource-type": "core.ps.conf", - "media-type": "application/senml-cbor", - "topic-type": "temperature", - "expiration-date": "2023-04-28T23:59:59Z", - } - -<= 2.04 Changed - Content-Format: TBD2 (application/core-pubsub+cbor) - - TBD (this should be a CBOR map) - { - "topic-name": "living-room-sensor", - "topic-data": "ps/data/1bd0d6d", - "resource-type": "core.ps.conf", - "media-type": "application/senml-cbor", - "topic-type": "temperature", - "expiration-date": "2023-04-28T23:59:59Z", - "max-subscribers": 100, - "observer-check": 86400 - } -]]> - Note that when a topic configuration changes, it may result in disruptions for the subscribers. Some potential issues that may arise include: -
    -
  • - Limiting the number of subscribers will cause to cancel ongoing subscriptions until max-subscribers has been reached. -
    • -
  • - Changing the topic-data value will cancel all ongoing subscriptions. -
    • -
  • - Changing of the expiration-date may cause to cancel ongoing subscriptions if the topic expires at an earlier data. -
    • -
-
-
- Updating the topic-configuration with iPATCH - A client can partially update a topic's configuration by submitting a partial topic representation in an iPATCH request to the topic URI. The iPATCH request allows for updating only specific fields of the topic configuration while leaving the others unchanged. As with the PUT method, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker. - On success, the server returns a 2.04 (Changed) response and the current full resource representation. The broker only updates parameters that are explicitly mentioned in the request. - As with the PUT method, updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Decreasing max-subscribers will also cause some subscribers to get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per Section 3.2. - Contrary to PUT, iPATCH operations will explicitly update some parameters, leaving others unmodified. - 0.07 iPATCH - Uri-Path: ps - Uri-Path: h9392 - Content-Format: TBD2 (application/core-pubsub+cbor) - - { - "topic-type": "humidity", - "max-subscribers": 5 - } - -<= 2.04 Changed - Content-Format: TBD2 (application/core-pubsub+cbor) - - TBD (this should be a CBOR map) - { - "topic-name" : "living-room-sensor", - "topic-data" : "ps/data/1bd0d6d", - "resource-type": "core.ps.conf", - "media-type": "application/senml-cbor", - "topic-type": "humidity", - "expiration-date": "2023-05-28T23:59:59Z", - "max-subscribers": 5 - } -]]> - Note that when a topic configuration changes through an iPATCH request, it may result in disruptions for the subscribers. For example, limiting the number of subscribers will cause to cancel ongoing subscriptions until max-subscribers has been reached. -
-
- Deleting a topic-configuration - A client can delete a topic by making a CoAP DELETE request on the topic resource URI. - On success, the server returns a 2.02 (Deleted) response. - When a topic-configuration resource is deleted, the broker MUST also delete the topic-data resource, unsubscribe all subscribers by removing them from the list of observers and returning a final 4.04 (Not Found) response as per section 3.2 of . - Example: - 0.04 DELETE - Uri-Path: ps - Uri-Path: h9392 - -<= 2.02 Deleted -]]> -
-
-
-
- Publish and Subscribe - The overview of the publish/subscribe mechanism over CoAP is as follows: a publisher publishes to a topic by submitting the data in a PUT request to a topic-data resource and subscribers subscribe to a topic by submitting a GET request with Observe option set to 0 (register) to a topic-data resource. When resource state changes, subscribers observing the resource at that time will receive a notification. - A topic-data resource does not exist until some initial data has been published to it. Before initial data publication, a GET request to the topic-data resource URI results in a 4.04 (Not Found) response. If such a "half created" topic is undesired, the creator of the topic can simply immediately publish some initial placeholder data to make the topic "fully created" (see ). - - -URIs for topic resources are broker-generated (see ). There is no necessary URI pattern dependence between the URI where the topic-data exists and the URI of the topic-configuration resource. -
- Topic Lifecycle - When a topic is newly created, it is first placed by the broker into the HALF CREATED state (see ). In this state, a client can read and update the configuration of the topic and delete the topic. A publisher can publish to the topic-data resource. However, a subscriber cannot yet subscribe to the topic-data resource nor read the latest data. - - -
- Lifecycle of a Topic - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - HALF - FULLY - CREATED - Delete - CREATED - topic-data - Publish - Create - Publish - Subscribe - Read/ - Read/ - Update - Delete - Delete - Update - Topic - Topic - DELETED - - - - | | <------------------- | | ------------. - Create | | | | | - |____| -------------------> |____| <-----------' - \ Publish / Subscribe - | ^ \ ___ / | ^ - Read/ | | '--> | | <--' | | Read/ - Update | | Delete |___| Delete | | Update - '-' Topic Topic '-' - DELETED -]]> - -
- After a publisher publishes to the topic-data for the first time, the topic is placed into the FULLY CREATED state. In this state, a client can read data by means of a GET request without observe. A publisher can publish to the topic-data resource and a subscriber can observe the topic-data resource. - When a client deletes a topic-configuration resource, the topic is placed into the DELETED state and shortly after removed from the server. In this state, all subscribers are removed from the list of observers of the topic-data resource and no further interactions with the topic are possible. - When a client deletes a topic-data, the topic is placed into the HALF CREATED state, where clients can read, update and delete the topic-configuration and await for a publisher to begin publication. -
-
- Topic-Data Interactions - - -Interactions with the topic-data resource are covered in this section. -
- Publish - A topic-configuration with a topic-data resource must have been created in order to publish data to it (See ) and be in the half-created or fully-created state in order to the publish operation to work (see ). - A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource property. Please note that the topic-data URI is not the same as the topic-configuration URI used for configuring the topic (see ). - On success, the server returns a 2.04 (Updated) response. However, when data is published to the topic for the first time, the server instead MUST return a 2.01 (Created) response and set the topic in the fully-created state (see ). - If the request does not have an acceptable content-format, the server returns a 4.15 (Unsupported Content-Format) response. - If the client is sending publications too fast, the server returns a -4.29 (Too Many Requests) response . - Example of first publication: - 0.03 PUT - Uri-Path: ps - Uri-Path: data - Uri-Path: 1bd0d6d - Content-Format: 110 - - { - "n": "coap://dev1.example.com/temperature", - "u": "Cel", - "t": 1621452122, - "v": 23.5 - } - -<= 2.01 Created -]]> - Example of subsequent publication: - 0.03 PUT - Uri-Path: ps - Uri-Path: data - Uri-Path: 1bd0d6d - Content-Format: 110 - - { - "n": "coap://dev1.example.com/temperature", - "u": "Cel", - "t": 1621452149, - "v": 22.5 - } - -<= 2.04 Updated -]]> -
-
- Subscribe - A client can subscribe to a topic-data by sending a CoAP GET request with the Observe set to 0 to subscribe to resource updates. . - On success, the server hosting the topic-data resource MUST return 2.05 (Content) notifications with the data and the Observe Option. Otherwise, if no Observe Option is present the client should assume that the subscription was not successful. - If the topic is not yet in the fully created state (see ) the broker SHOULD return a response code 4.04 (Not Found). - - -The following response codes are defined for the Subscribe operation: -
-
Success:
-
- 2.05 "Content". Successful subscribe with observe response, current value included in the response. -
-
Failure:
-
- 4.04 "Not Found". The topic-data does not exist. -
-
- If the 'max-subscribers' parameter has been reached, the server must treat that as specified in section 4.1 of . The response MUST NOT include an Observe Option, the absence of which signals to the subscriber that the subscription failed. - - -Example: - 0.01 GET - Uri-Path: ps - Uri-Path: data - Uri-Path: 1bd0d6d - Observe: 0 - -<= 2.05 Content - Content-Format: 110 - Observe: 10001 - Max-Age: 15 - - { - "n": "urn:dev:os:32473-123456", - "u": "Cel", - "t": 1696341182, - "v": 19.87 - } - -<= 2.05 Content - Content-Format: 110 - Observe: 10002 - Max-Age: 15 - - { - - "n": "urn:dev:os:32473-123456", - "u": "Cel", - "t": 1696340184, - "v": 21.87 - } -]]> -
-
- Unsubscribe - A CoAP client can unsubscribe simply by cancelling the observation as described in Section 3.6 of . The client MUST either use CoAP GET with the Observe Option set to 1 or send a CoAP Reset message in response to a notification. Also on Section 3.6 of the client can simply "forget" the observation and the server will remove it from the list of observers after the next notification. - As per a server that transmits notifications mostly in non-confirmable messages, but it MUST send a notification in a confirmable message instead of a non-confirmable message at least every 24 hours. - This value can be modified at the broker by the administrator of a topic by modifying the parameter "observer-check" on . This would allow to change the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource. - - -
-
- Delete topic-data - A publisher MAY delete a topic by making a CoAP DELETE request on the topic-data URI. - On success, the server returns a 2.02 (Deleted) response. - When a topic-data resource is deleted, the broker SHOULD also delete the topic-data parameter in the topic resource, unsubscribe all subscribers by removing them from the list of observers and return a final 4.04 (Not Found) response as per Section 3.2. The topic is then set back to the half created state as per . - Example: - 0.04 DELETE - Uri-Path: ps - Uri-Path: data - Uri-Path: 1bd0d6d - -<= 2.02 Deleted -]]> -
-
-
- Read latest data - A client can get the latest published topic-data by making a GET request to the topic-data URI in the broker. Please note that discovery of the topic-data parameter is a required previous step (see ). - On success, the server MUST return 2.05 (Content) response with the data. - If the target URI does not match an existing resource or the topic is not in the fully created state (see ), the broker MUST return a response code 4.04 (Not Found). - Example: - 0.01 GET - Uri-Path: ps - Uri-Path: data - Uri-Path: 1bd0d6d - -<= 2.05 Content - Content-Format: 110 - Max-Age: 15 - - { - "n": "coap://dev1.example.com/temperature", - "u": "Cel", - "t": 1621452122, - "v": 23.5 - } -]]> - - -
-
- Rate Limiting - The server hosting the topic-data may have to handle a potentially large number of publishers and subscribers at the same time. This means it could become overwhelmed if it receives too many publications in a short period of time. - In this situation, if a publisher is sending publications too fast, the server SHOULD return a 4.29 (Too Many Requests) response . As described in , the Max-Age option in this response indicates the number of seconds after which the client may retry. The broker MAY also stop publishing messages from that publisher for the indicated time. - - -When a publisher receives a 4.29 (Too Many Requests) response, it MUST NOT send any new publication requests to the same topic-data resource before the time indicated by the Max-Age option has passed. -
-
-
- CoAP Pubsub Parameters - This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and configuration process (see ). The table below summarizes them and specifies the CBOR key to use instead of the full descriptive name. - Note that the media type application/core-pubsub+cbor MUST be used when these parameters are transported in the respective message fields. -
- CoAP Pubsub Parameters - -
-
-
- Security Considerations - The architecture presented in this document inherits the security considerations from CoAP and Observe , as well as from Web Linking , Link-Format , and the CoRE Resource Directory . - Communications between each client and the broker MUST be secured, e.g., by using OSCORE or DTLS . Security considerations for the used secure communication protocols apply too. - The content published on a topic by a publisher client SHOULD be protected end-to-end between the publisher and all the subscribers to that topic. In such a case, it MUST be possible to assert source authentication of the published data. This can be achieved at the application layer, e.g., by using COSE , , . - Access control of clients at the broker MAY be enforced for performing discovery operation, and SHOULD be enforced in a fine-grained fashion for operations related to the the creation, update, and deletion of topic resources, as well as for operations on topic-data resources such as publication on and subscription to topics. This prevents rogue clients to, among other things, repeatedly create topics at the broker or publish (large) contents, which may result in Denial of Service against the broker and the active subscribers. - Building on , its application profile for publish-subscribe communication with CoAP provides a security model that can be used in the architecture presented in this document, in order to enable secure communication between the different parties as well as secure, authorized operations of publishers and subscribers that fulfill the requirements above. - In particular, the application profile above relies on the ACE framework for Authentication and Authorization in Constrained Environments (ACE) and defines a method to: authorize publishers and subscribers to perform operations at the broker, with fine-grained access control; authorize publishers and subscribers to obtain the keying material required to take part to a topic managed by the broker; protect published data end-to-end between its publisher and all the subscribers to the targeted topic, ensuring confidentiality, integrity, and source authentication of the published content end-to-end. That approach can be extended to enforce authorization and fine-grained access control for administrator clients that are intended to create, update, and delete topic configurations at the broker. -
-
- IANA Considerations - This document has the following actions for IANA. - Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification and delete this paragraph. -
- Media Type - IANA is requested to add the following Media-Type to the "Media Types" -registry . - - New Media Type application/pubsub+cbor - - - - - - - - - - - - - - -
NameTemplateReference
pubsub+cborapplication/pubsub+cborRFC XXXX,
-
-
Type name:
-
- application -
-
Subtype name:
-
- pubsub+cbor -
-
Required parameters:
-
- N/A -
-
Optional parameters:
-
- N/A -
-
Encoding considerations:
-
- binary (CBOR data item) -
-
Security considerations:
-
- of RFC XXXX -
-
Interoperability considerations:
-
- none -
-
Published specification:
-
- of RFC XXXX -
-
Applications that use this media type:
-
- This type is used by clients that create, retrieve, and update topic configurations at servers acting as a pub-sub broker. -
-
Fragment identifier considerations:
-
- N/A -
-
Person & email address to contact for further information:
-
- CoRE WG mailing list (core@ietf.org), -or IETF Applications and Real-Time Area (art@ietf.org) -
-
Intended usage:
-
- COMMON -
-
Restrictions on usage:
-
- none -
-
Author/Change controller:
-
- IETF -
-
Provisional registration:
-
- no -
-
-
-
- Content-Format - IANA has added the following Content-Formats to the - -sub-registry, within the "Constrained RESTful Environments (CoRE) -Parameters" Registry , as follows: - - New Content-Format - - - - - - - - - - - - - - - - -
Content TypeContent CodingIDReference
application/pubsub+cbor-TBD9RFC XXXX
- TBD9 is to be assigned from the space 256..999. -
-
- CoAP Pubsub Parameters - IANA is asked to register the following entries in the subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry group. - This specification establishes the "Pubsub Topic Configuration Parameters" IANA registry within the "Constrained RESTful Environments (CoRE) -Parameters" registry group. - The columns of this registry are: -
    -
  • - Name: This is a descriptive name that enables easier reference to the item. The name MUST be unique. It is not used in the encoding. -
    • -
  • - CBOR Key: This is the value used as CBOR key of the item. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges of values use different registration policies . Integer values from -256 to 255 as well as text strings of length 1 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535, as well as text strings of length 2 are designated as "Specification Required". Integer values greater than 65535 as well as text strings of length greater than 2 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use". -
    • -
  • - CBOR Type: This contains the CBOR type of the item, or a pointer to the registry that defines its type, when that depends on another item. -
    • -
  • - Reference: This contains a pointer to the public specification for the item. -
    • -
- The registry is initially populated with the entries in of . -
-
- Resource Types - IANA is asked to enter the following values in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained Restful Environments (CoRE) Parameters" registry group. - -
-
-
- Acknowledgements - The current version of this document contains a substantial contribution by Klaus Hartke's proposal , which defines the topic resource model and structure as well as the topic lifecycle and interactions. It also follows a similar architectural design as that provided by Marco Tiloca's . - The authors would like to also thank Carsten Bormann, Hannes Tschofenig, Zach Shelby, Mohit Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran Selander, Mikko Majanen, Olaf Bergmann and Oscar Novo for their valuable contributions and reviews. -
- - - - References - - Normative References - - - URI Template - - - - - - - - A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] - - - - - - - - Constrained RESTful Environments (CoRE) Link Format - - - - This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] - - - - - - - - The Constrained Application Protocol (CoAP) - - - - - - The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. - CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. - - - - - - - - "Too Many Requests" Response Code for the Constrained Application Protocol - - - - A Constrained Application Protocol (CoAP) server can experience temporary overload because one or more clients are sending requests to the server at a higher rate than the server is capable or willing to handle. This document defines a new CoAP response code for a server to indicate that a client should reduce the rate of requests. - - - - - - - - Constrained RESTful Environments (CoRE) Resource Directory - - - - - - - - In many Internet of Things (IoT) applications, direct discovery of resources is not practical due to sleeping nodes or networks where multicast traffic is inefficient. These problems can be solved by employing an entity called a Resource Directory (RD), which contains information about resources held on other servers, allowing lookups to be performed for those resources. The input to an RD is composed of links, and the output is composed of links constructed from the information stored in the RD. This document specifies the web interfaces that an RD supports for web servers to discover the RD and to register, maintain, look up, and remove information on resources. Furthermore, new target attributes useful in conjunction with an RD are defined. - - - - - - - - Object Security for Constrained RESTful Environments (OSCORE) - - - - - - - This document defines Object Security for Constrained RESTful Environments (OSCORE), a method for application-layer protection of the Constrained Application Protocol (CoAP), using CBOR Object Signing and Encryption (COSE). OSCORE provides end-to-end protection between endpoints communicating using CoAP or CoAP-mappable HTTP. OSCORE is designed for constrained nodes and networks supporting a range of proxy operations, including translation between different transport protocols. - Although an optional functionality of CoAP, OSCORE alters CoAP options processing and IANA registration. Therefore, this document updates RFC 7252. - - - - - - - - Observing Resources in the Constrained Application Protocol (CoAP) - - - - The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. - - - - - - - - Key words for use in RFCs to Indicate Requirement Levels - - - - In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. - - - - - - - - - Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words - - - - RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. - - - - - - - - - Media Types - - IANA - - - - - - Constrained RESTful Environments (CoRE) Parameters - - IANA - - - - - - Informative References - - - Web Linking - - - - This specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). - It also defines the serialisation of such links in HTTP headers with the Link header field. - - - - - - - - Guidelines for Writing an IANA Considerations Section in RFCs - - - - - - Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). - To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. - This is the third edition of this document; it obsoletes RFC 5226. - - - - - - - - - CBOR Object Signing and Encryption (COSE): Structures and Process - - - - Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. - This document, along with RFC 9053, obsoletes RFC 8152. - - - - - - - - - The Datagram Transport Layer Security (DTLS) Protocol Version 1.3 - - - - - - This document specifies version 1.3 of the Datagram Transport Layer Security (DTLS) protocol. DTLS 1.3 allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. - The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection / non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol. - This document obsoletes RFC 6347. - - - - - - - - CBOR Object Signing and Encryption (COSE): Initial Algorithms - - - - Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines a set of algorithms that can be used with the CBOR Object Signing and Encryption (COSE) protocol (RFC 9052). - This document, along with RFC 9052, obsoletes RFC 8152. - - - - - - - - Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth) - - - - - - - - This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE-OAuth. The framework is based on a set of building blocks including OAuth 2.0 and the Constrained Application Protocol (CoAP), thus transforming a well-known and widely used authorization solution into a form suitable for IoT devices. Existing specifications are used where possible, but extensions are added and profiles are defined to better serve the IoT use cases. - - - - - - - - CBOR Object Signing and Encryption (COSE): Countersignatures - - - - Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. CBOR Object Signing and Encryption (COSE) defines a set of security services for CBOR. This document defines a countersignature algorithm along with the needed header parameters and CBOR tags for COSE. This document updates RFC 9052. - - - - - - - - - Publish/Subscribe over the Constrained Application Protocol (CoAP) using the Constrained RESTful Application Language (CoRAL) - - Ericsson - - - - This document explores how the Constrained RESTful Application - Language (CoRAL) might be used for enabling publish/subscribe-style - communication over the Constrained Application Protocol (CoAP), which - allows CoAP nodes with long breaks in connectivity and/or up-time to - exchange data via a publish/subscribe broker. - - - - - - - - - Admin Interface for the OSCORE Group Manager - - RISE AB - - - RISE AB - - - - - Ericsson AB - - - - Group communication for CoAP can be secured using Group Object - Security for Constrained RESTful Environments (Group OSCORE). A - Group Manager is responsible for handling the joining of new group - members, as well as managing and distributing the group keying - material. This document defines a RESTful admin interface at the - Group Manager that allows an Administrator entity to create and - delete OSCORE groups, as well as to retrieve and update their - configuration. The ACE framework for Authentication and - Authorization is used to enforce authentication and authorization of - the Administrator at the Group Manager. Protocol-specific transport - profiles of ACE are used to achieve communication security, proof-of- - possession, and server authentication. - - - - - - - - - Publish-Subscribe Profile for Authentication and Authorization for Constrained Environments (ACE) - - Ericsson - - - Brunel University - - - RISE AB - - - - This document defines an application profile of the Authentication - and Authorization for Constrained Environments (ACE) framework, to - enable secure group communication in the Publish-Subscribe (pub/sub) - architecture for the Constrained Application Protocol (CoAP) [draft- - ietf-core-coap-pubsub], where Publishers and Subscribers communicate - through a Broker. This profile relies on protocol-specific transport - profiles of ACE to achieve communication security, server - authentication, and proof-of-possession for a key owned by the Client - and bound to an OAuth 2.0 Access Token. This document specifies the - provisioning and enforcement of authorization information for Clients - to act as Publishers and/or Subscribers, as well as the provisioning - of keying material and security parameters that Clients use for - protecting their communications end-to-end through the Broker. - - Note to RFC Editor: Please replace "[draft-ietf-core-coap-pubsub]" - with the RFC number of that document and delete this paragraph. - - - - - - - - - Key Provisioning for Group Communication using ACE - - Ericsson AB - - - RISE AB - - - - This document defines how to use the Authentication and Authorization - for Constrained Environments (ACE) framework to distribute keying - material and configuration parameters for secure group communication. - Candidate group members acting as Clients and authorized to join a - group can do so by interacting with a Key Distribution Center (KDC) - acting as Resource Server, from which they obtain the keying material - to communicate with other group members. While defining general - message formats as well as the interface and operations available at - the KDC, this document supports different approaches and protocols - for secure group communication. Therefore, details are delegated to - separate application profiles of this document, as specialized - instances that target a particular group communication approach and - define how communications in the group are protected. Compliance - requirements for such application profiles are also specified. - - - - - - - - -
- Contributors - - RISE AB -
- marco.tiloca@ri.se -
- - Marco offered comprehensive reviews and insightful guidance on the recent iterations of this document. His contributions were particularly notable in the Security Considerations section, among others. -
- - - - diff --git a/reference/draft-ietf-core-coap-pubsub-14.xml b/reference/draft-ietf-core-coap-pubsub-14.xml new file mode 100644 index 0000000..6ee25ef --- /dev/null +++ b/reference/draft-ietf-core-coap-pubsub-14.xml @@ -0,0 +1,2228 @@ + + + + + + + + + + + +]> + + + + + A publish-subscribe architecture for the Constrained Application Protocol (CoAP) + + + Ericsson +
+ jaime@iki.fi +
+ + + Dogtiger Labs +
+ michaeljohnkoster@gmail.com +
+ + + Ericsson +
+ ari.keranen@ericsson.com +
+ + + + + Applications + CoRE Working Group + + + + + + + +This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker. + + + + + + + + Status information for this document may be found at . + + + Discussion of this document takes place on the + core Working Group mailing list (), + which is archived at . + Subscribe at . + + Source for this draft and an issue tracker can be found at + . + + + + + + + + + + +
Introduction + +The Constrained Application Protocol (CoAP) supports +machine-to-machine communication across networks of constrained +devices and constrained networks. 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, a client, or both. + +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 up-time because they spend most of their time in a sleeping state with no network connectivity. Another important class of nodes are devices with limited reachability due to middle-boxes like Network Address Translators (NATs) and firewalls. + +For these nodes, the client/server-oriented architecture of REST can be challenging when interactions are not initiated by the devices themselves. A publish/subscribe-oriented architecture where nodes exchange data via topics through a broker entity might fit these nodes better. + +This document applies the idea of broker-based publish-subscribe to Constrained RESTful Environments using CoAP. It defines a broker that allows to create, discover subscribe and publish on topics. + +
Terminology + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", +"MAY", and "OPTIONAL" in this document are to be interpreted as +described in BCP 14 when, and only when, they +appear in all capitals, as shown here. + + +This specification requires readers to be familiar with all the terms and +concepts that are discussed in and . Readers +should also be familiar with the terms and concepts discussed in +, and . The URI template +format is used to describe the REST API defined in +this specification. + +This specification makes use of the following terminology: + +
+
publish-subscribe (pub/sub):
+
+ A message communication model where messages associated with specific topics are sent to a broker. Interested parties, i.e. subscribers, receive these topic-based messages from the broker without the original sender knowing the recipients. The broker handles matching and delivering these messages to the appropriate subscribers. +
+
publishers and subscribers:
+
+ CoAP clients can act as publishers or as subscribers. Publishers send CoAP messages (publications) to the broker on specific topics. Subscribers have an ongoing observation relation (subscription) to a topic. Both roles operate without any mutual knowledge, guided by their respective topic interests. +
+
topic collection:
+
+ A set of topic configurations. A topic collection is hosted as one collection resource at the broker, and its representation is the list of links to the topic resources corresponding to each topic configuration. +
+
topic-configuration:
+
+ A set of information concerning a topic, including its configuration and other metadata. A topic configuration is hosted as one topic resource at the broker, and its representation is the set of configuration information concerning the topic. All the topic resources associated with the same topic collection share a common base URI, i.e., the URI of the collection resource. Throughout this document the word "topic" and "topic-configuration" can be used interchangeably. +
+
topic-data resource:
+
+ A resource where clients can publish data and/or subscribe to data for a specific topic. The representation of the topic resource corresponding to such a topic also specifies the URI to the present topic-data resource. +
+
broker:
+
+ A CoAP server that hosts one or more topic collections with their topic-configurations, and also topic-data resources. The broker is responsible for the store-and-forward of state update representations, for the topics for which it hosts the corresponding topic-data resources. The broker is also responsible of handling the topic lifecycle as defined in . The creation, configuration, and discovery of topics at a broker is specified in . +
+
+ +
+
CoAP Publish-Subscribe Architecture + + shows a simple Publish/Subscribe architecture over CoAP. + +Topics are created by the broker, but the initial configuration can be proposed by a client (e.g., a publisher or a dedicated administrator) over the RESTful interface of a corresponding topic resource hosted by the broker. + +Publishers submit their data over the RESTful interface of a topic-data resource corresponding to the topic, which may be hosted by the broker. Subscribers to a topic are notified of new publications by using Observe on the corresponding topic-data resource. + +The broker is responsible for the store-and-forward of state update representations between CoAP clients. Subscribers observing a resource will receive notifications, the delivery of which is done on a best-effort basis. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +CoAP +CoAP +CoAP +clients +server +clients +observe +publish +publisher +subscriber +... +broker +... +... +... +observe +publish +publisher +subscriber + + ++ +---------->| subscriber | + | | | +---------->| | + '-----------' | | '------------' + ... | broker | ... + ... | | ... + .-----------. | | observe .------------. + | | publish | |<----------+ | + | publisher +--------->| +---------->| subscriber | + | | | +---------->| | + '-----------' '----------' '------------' +]]>
+ +This document describes two sets of interactions, interactions to configure topics and their lifecycle (see ) and interactions about the topic-data (see ). + +Topic-configuration interactions are discovery, create, read configuration, update configuration, and delete configuration. These operations handle the management of the topics. + +Topic-data interactions are publish, subscribe, unsubscribe, read, and delete. These operations are oriented on how data is transferred from a publisher to a subscriber. + + + +
+
Managing Topics + + shows the resources related to a Topic Collection that can be managed at the Broker. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +topic +collection +resource +... +topic +resources + + +
+ +The Broker exports one or more topic-collection resources, with resource type "core.ps.coll" defined in of this document. The interfaces for the topic-collection resource is defined in . + +A topic-collection resource can have topic resources as its child resources, with resource type "core.ps.conf". + +
+
+
Pub-Sub Topics + +The configuration side of a "publish/subscribe broker" consists of a collection of topics. These topics as well as the collection itself are exposed by a CoAP server as resources (see ). Each topic is associated with a topic configuration resource and a topic-data resource. The topic configuration resource is used by a client creating or administering a topic. The topic-data resource is used by the publishers and the subscribers to a topic. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +topic +collection +resource +...... +...... +...... +topic +: +: +: +: +: +: +configuration +: +: +: +: +: +: +resource +: +_ +_ +: +: +_ +_ +: +: +_ +_ +: +.... +.... +.... +.... +.... +.... +.... +.... +.... +.... +.... +.... +: +_ +_ +: +: +_ +_ +: +... +: +_ +_ +: +topic-data +: +: +: +: +: +: +resource +: +: +: +: +: +: +:.......: +:.......: +:.......: +\ +/ +... +\ +/ +topic +1 +topic +2 +topic +n + + +
+ +
Collection Representation + +Each topic configuration is represented as a link, where the link target is the URI of the corresponding topic resource. + +Publication and subscription to a topic occur at a link, where the link target is the URI of the corresponding topic-data resource. Such a link is specified by the topic-data entry within the topic resource (see ). + +A topic resource with a topic-data link can also be simply called "topic". + +The list of links to the topic resources can be retrieved from the associated topic collection resource, and represented as a Link Format document where each such link specifies the link target attribute 'rt' (Resource Type), with value "core.ps.conf" defined in this document. + +
+
Topic-Configuration Representation + +A CoAP client can create a new topic by submitting an initial configuration for the topic (see ). It can also read and update the configuration of existing topics and delete them when they are no longer needed (see ). + +The configuration of a topic itself consists of a set of properties that can be set by a client or by the broker. The topic-configuration is represented as a CBOR map containing the configuration properties of the topic as top-level elements. + +Unless specified otherwise, these are defined in this document and their CBOR abbreviations are defined in . + +
Topic Properties + +The CBOR map includes the following configuration parameters, whose CBOR abbreviations are defined in of this document. + + + 'topic-name': A required field used as an application identifier. It encodes the topic name as a CBOR text string. Examples of topic names include human-readable strings (e.g., "room2"), UUIDs, or other values. + 'topic-data': A required field (optional during creation) containing the URI of the topic-data resource for publishing/subscribing to this topic. It encodes the URI as a CBOR text string. + 'resource-type': A required field used to indicate the resource type of the topic-data resource for the topic. It encodes the resource type as a CBOR text string. The value should be "core.ps.conf". + + + + + + 'media-type': An optional field used to indicate the media type of the topic-data resource for the topic. It encodes the media type as a this information as the integer identifier of the CoAP content-format (e.g., value is "50" for "application/json"). + 'topic-type': An optional field used to indicate the attribute or property of the topic-data resource for the topic. It encodes the attribute as a CBOR text string. Example attributes include "temperature". + 'expiration-date': An optional field used to indicate the expiration date of the topic. It encodes the expiration date as a CBOR text string. The value should be a date string in ISO 8601 format (e.g., "2023-03-31T23:59:59Z"). The broker can use this field to automatically remove topics that are no longer valid. If this field is not present, the topic will not expire automatically. + 'max-subscribers': An optional field used to indicate the maximum number of simultaneous subscribers allowed for the topic. It encodes the maximum number as an unsigned CBOR integer. If this field is not present, there is no limit to the number of simultaneous subscribers allowed. The broker can use this field to limit the number of subscribers for the topic. The default value for this field has been set to 100 subscribers. + 'observer-check': An optional field that controls the maximum number of seconds between two consecutive Observe notifications sent as Confirmable messages to each topic subscriber. Encoded as a CBOR unsigned integer greater than 0, it ensures subscribers who have lost interest and silently forgotten the observation do not remain indefinitely on the server's observer list. If another CoAP server hosts the topic-data resource, that server is responsible for applying the observer-check value. The default value for this field is 86400, as defined in , which corresponds to 24 hours. + + +
+
+
Discovery + +A client can perform a discovery of: the broker; the topic collection resources and topic resources hosted by the broker; and the topic-data resources associated with those topic resources. + +
Broker Discovery + +CoAP clients MAY discover brokers by using CoAP Simple Discovery, via multicast, through a Resource Directory (RD) or by other means specified in extensions to . Brokers MAY register with a RD by following the steps on Section 5 of with the resource type set to "core.ps" as defined in of this document. + +The following example shows an endpoint discovering a broker using the "core.ps" resource type over a multicast network. Brokers within the multicast scope will answer the query. + +
0.01 GET + Uri-Path: coap://[ff0x::fe]/.well-known/core + Resource-Type: core.ps + +<= 2.05 Content + Payload: + Content-Format: 40 (application/link-format) + ; rt=core.ps +]]>
+ +
+
Topic Collection Discovery + +A Broker SHOULD offer a topic discovery entry point to enable clients to find topics of interest. The resource entry point is the topic collection resource collecting the topic configurations for those topics (see Section 1.2.2 of ) and is identified by the resource type "core.ps.coll". + +The specific resource path is left for implementations, examples in this document use the "/ps" path. The interactions with a topic collection are further defined in . + +Since the representation of the topic collection resource includes the links to the associated topic resources, it is not required to locate those links under "/.well-known/core", also in order to limit the size of the Link Format document returned as result of the discovery. + +Example: + +
0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.coll + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.coll";ct=40, + ;rt="core.ps.coll";ct=40 +]]>
+ +
+
Topic-Configuration Discovery + +Each topic collection is associated with a group of topic resources, each detailing the configuration of its respective topic (refer to ). Each topic resource is identified by the resource type "core.ps.conf". + +Below is an example of discovery via /.well-known/core with rt=core.ps.conf that returns a list of topics, as the list of links to the corresponding topic resources. + + + +
0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.conf + +<= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf";ct=TBD, + ;rt=core.ps.conf;ct=TBD +]]>
+ +
+
Topic-Data Discovery + + + +Within a topic, there is the topic-data property containing the URI of the topic-data resource that a CoAP client can subscribe and publish to. Resources exposing resources of the topic-data type are expected to use the resource type 'core.ps.data'. + +The topic-data contains the URI of the topic-data resource for publishing and subscribing. So retrieving the topic configuration will also provide the URL of the topic-data (see ). + +It is also possible to discover a list of topic-data resources by sending a request to the collection with with rt=core.ps.data resources as shown below. + +
0.01 GET + Uri-Path: /ps + Resource-Type: core.ps.data + +<= 2.05 Content + Content-Format: 40 (application/link-format) + ; rt=core.ps.data; obs +]]>
+ +
+
+
Topic Collection Interactions + +These are the interactions that can happen directly with a specific topic collection. + +
Retrieving all topic-configurations + +A client can request a collection of the topics present in the broker by making a GET request to the collection URI. + +On success, the server returns a 2.05 (Content) response, specifying the list of links to topic resources associated with this topic collection (see ). + +Depending on its granted permissions, a client MAY retrieve a different list of links, corresponding to the topics that the client is authorized to access. + +Example: + +
0.01 GET + Uri-Path: ps + +<= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf", + ; rt="core.ps.conf" +]]>
+ +
+
Getting topic-configurations by Properties + + +A client can filter a collection of topics by submitting the +representation of a topic filter (see ) in a FETCH request to the topic collection URI. + +On success, the server returns a 2.05 (Content) response with a +representation of a list of topics in the collection (see + ) that match the filter in CoRE link format . + +Upon success, the server responds with a 2.05 (Content), providing a list of links to topic resources associated with this topic collection that match the request's filter criteria (refer to ). A positive match happens only when each request parameter is present with the indicated value in the topic resource representation. + +Example: + +
0.05 FETCH + Uri-Path: ps + Content-Format: TBD (application/pubsub+cbor) + + { + "resource-type": "core.ps.conf", + "topic-type": "temperature" + } + +<= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf" +]]>
+ +
+
Creating a Topic + + +A client can add a new topic-configurations to a collection of topics by submitting an initial representation of the initial topic resource (see ) in a POST request to the topic collection URI. The request MUST specify at least a subset of the properties in , namely: topic-name and resource-type. + + + +Please note that the topic will NOT be fully created until a publisher has published some data to it (See ). + +On success, the server returns a 2.01 (Created) response, indicating the Location-Path of the new topic and the current representation of the topic resource. The response payload includes a CBOR map with key-value pairs. The response must include the required topic properties (see ), namely: "topic-name", "resource-type" and "topic-data". It may also include a number of optional properties too. + +If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor". + +The broker MUST issue a 4.00 (Bad Request) error if a received parameter is invalid, unrecognized, or if the topic-name is already in use or otherwise invalid. + + + +
0.02 POST + Uri-Path: ps + Content-Format: TBD2 (application/core-pubsub+cbor) + TBD (this should be a CBOR map with the mandatory parameters) + { + "topic-name": "living-room-sensor", + "resource-type": "core.ps.conf" + } + +<= 2.01 Created + Location-Path: ps/h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf" + } +]]>
+ +
+
+
Topic-Configuration Interactions + +These are the interactions that can happen at the topic resource level. + +
Getting a topic-configuration + + + +A client can read the configuration of a topic by making a GET request to the topic resource URI. + +On success, the server returns a 2.05 (Content) response with a partial representation of the topic resource, as specified in . The partial representation includes only the configuration parameters such that they are present and have the same value in both the current topic configuration as well as in the FETCH request. + +If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. + +The response payload is a CBOR map, whose possible entries are specified in and use the same abbreviations defined in . + +For example, below is a request on the topic "ps/h9392": + +
0.01 GET + Uri-Path: ps + Uri-Path: h9392 + +<= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-00T23:59:59Z", + "max-subscribers": 100 + } + +]]>
+ +
+
Getting part of a topic-configuration + + +A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific parameters. This is done in order to retrieve part of the current topic resource. + +The request contains a CBOR map with a configuration filter or 'conf-filter', a CBOR array with CBOR abbreviation. Each element of the array specifies one requested configuration parameter of the current topic resource (see ). + +On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the partial representation of the topic resource as specified in . + +If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. + +The response payload is a CBOR map, whose possible entries are specified in and use the same abbreviations defined in . + +Both request and response MUST have Content-Format set to "application/core-pubsub+cbor". + +Example: + +
0.05 FETCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "conf-filter": ["topic-data", "media-type"] + } + +<= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-data": "ps/data/1bd0d6d", + "media-type": "application/senml-cbor" + } + +]]>
+ +
+
Updating the topic-configuration + + + +A client can update a topic's configuration by submitting the updated topic representation in a PUT request to the topic URI. However, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker. + +On success, the topic configuration is overwritten and server returns a 2.04 (Changed) response and the current full resource representation. The broker may chose not to overwrite parameters that are not explicitly modified in the request. + +Note that updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Updating the "topic-data" may happen also after it being deleted, as described on {delete-topic-data}, this will in turn create a new "topic-data" path for that topic configuration. + +Similarly, decreasing max-subscribers will also cause that some subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per Section 3.2. + +Please note that when using PUT the topic configuration is being overwritten, thus some of the optional parameters (e.g., "max-subscribers", "observer-check") not included in the PUT message will be reset to their default values. + +Example: + +
0.03 PUT + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + } + +<= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + "max-subscribers": 100, + "observer-check": 86400 + } +]]>
+ +Note that when a topic configuration changes, it may result in disruptions for the subscribers. Some potential issues that may arise include: + + + Limiting the number of subscribers will cause to cancel ongoing subscriptions until max-subscribers has been reached. + Changing the topic-data value will cancel all ongoing subscriptions. + Changing of the expiration-date may cause to cancel ongoing subscriptions if the topic expires at an earlier data. + + +
+
Updating the topic-configuration with iPATCH + +A client can partially update a topic's configuration by submitting a partial topic representation in an iPATCH request to the topic URI. The iPATCH request allows for updating only specific fields of the topic configuration while leaving the others unchanged. As with the PUT method, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker. + +On success, the server returns a 2.04 (Changed) response and the current full resource representation. The broker only updates parameters that are explicitly mentioned in the request. + +As with the PUT method, updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Decreasing max-subscribers will also cause some subscribers to get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per Section 3.2. + +Contrary to PUT, iPATCH operations will explicitly update some parameters, leaving others unmodified. + +
0.07 iPATCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-type": "humidity", + "max-subscribers": 5 + } + +<= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "humidity", + "expiration-date": "2023-05-28T23:59:59Z", + "max-subscribers": 5 + } +]]>
+ +Note that when a topic configuration changes through an iPATCH request, it may result in disruptions for the subscribers. For example, limiting the number of subscribers will cause to cancel ongoing subscriptions until max-subscribers has been reached. + +
+
Deleting a topic-configuration + +A client can delete a topic by making a CoAP DELETE request on the topic resource URI. + +On success, the server returns a 2.02 (Deleted) response. + +When a topic-configuration resource is deleted, the broker MUST also delete the topic-data resource, unsubscribe all subscribers by removing them from the list of observers and returning a final 4.04 (Not Found) response as per section 3.2 of . + +Example: + +
0.04 DELETE + Uri-Path: ps + Uri-Path: h9392 + +<= 2.02 Deleted +]]>
+ +
+
+
+
Publish and Subscribe + +The overview of the publish/subscribe mechanism over CoAP is as follows: a publisher publishes to a topic by submitting the data in a PUT request to a topic-data resource and subscribers subscribe to a topic by submitting a GET request with Observe option set to 0 (register) to a topic-data resource. When resource state changes, subscribers observing the resource at that time will receive a notification. + +A topic-data resource does not exist until some initial data has been published to it. Before initial data publication, a GET request to the topic-data resource URI results in a 4.04 (Not Found) response. If such a "half created" topic is undesired, the creator of the topic can simply immediately publish some initial placeholder data to make the topic "fully created" (see ). + + + +URIs for topic resources are broker-generated (see ). There is no necessary URI pattern dependence between the URI where the topic-data exists and the URI of the topic-configuration resource. + +
Topic Lifecycle + +When a topic is newly created, it is first placed by the broker into the HALF CREATED state (see ). In this state, a client can read and update the configuration of the topic and delete the topic. A publisher can publish to the topic-data resource. However, a subscriber cannot yet subscribe to the topic-data resource nor read the latest data. + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +HALF +FULLY +CREATED +Delete +CREATED +topic-data +Publish +Create +Publish +Subscribe +Read/ +Read/ +Update +Delete +Delete +Update +Topic +Topic +DELETED + + + | | <------------------- | | ------------. + Create | | | | | + |____| -------------------> |____| <-----------' + \ Publish / Subscribe + | ^ \ ___ / | ^ + Read/ | | '--> | | <--' | | Read/ + Update | | Delete |___| Delete | | Update + '-' Topic Topic '-' + DELETED +]]>
+ +After a publisher publishes to the topic-data for the first time, the topic is placed into the FULLY CREATED state. In this state, a client can read data by means of a GET request without observe. A publisher can publish to the topic-data resource and a subscriber can observe the topic-data resource. + +When a client deletes a topic-configuration resource, the topic is placed into the DELETED state and shortly after removed from the server. In this state, all subscribers are removed from the list of observers of the topic-data resource and no further interactions with the topic are possible. + +When a client deletes a topic-data, the topic is placed into the HALF CREATED state, where clients can read, update and delete the topic-configuration and await for a publisher to begin publication. + +
+
Topic-Data Interactions + + + +Interactions with the topic-data resource are covered in this section. + +
Publish + +A topic-configuration with a topic-data resource must have been created in order to publish data to it (See ) and be in the half-created or fully-created state in order to the publish operation to work (see ). + +A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource property. Please note that the topic-data URI is not the same as the topic-configuration URI used for configuring the topic (see ). + +On success, the server returns a 2.04 (Updated) response. However, when data is published to the topic for the first time, the server instead MUST return a 2.01 (Created) response and set the topic in the fully-created state (see ). + +If the request does not have an acceptable content-format, the server returns a 4.15 (Unsupported Content-Format) response. + +If the client is sending publications too fast, the server returns a +4.29 (Too Many Requests) response . + +Example of first publication: + +
0.03 PUT + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + +<= 2.01 Created +]]>
+ +Example of subsequent publication: + +
0.03 PUT + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452149, + "v": 22.5 + } + +<= 2.04 Updated +]]>
+ +
+
Subscribe + +A client can subscribe to a topic-data by sending a CoAP GET request with the Observe set to 0 to subscribe to resource updates. . + +On success, the server hosting the topic-data resource MUST return 2.05 (Content) notifications with the data and the Observe Option. Otherwise, if no Observe Option is present the client should assume that the subscription was not successful. + +If the topic is not yet in the fully created state (see ) the broker SHOULD return a response code 4.04 (Not Found). + + + +The following response codes are defined for the Subscribe operation: + +
+
Success:
+
+ 2.05 "Content". Successful subscribe with observe response, current value included in the response. +
+
Failure:
+
+ 4.04 "Not Found". The topic-data does not exist. +
+
+ +If the 'max-subscribers' parameter has been reached, the server must treat that as specified in section 4.1 of . The response MUST NOT include an Observe Option, the absence of which signals to the subscriber that the subscription failed. + + + +Example: + +
0.01 GET + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + Observe: 0 + +<= 2.05 Content + Content-Format: 110 + Observe: 10001 + Max-Age: 15 + + { + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696341182, + "v": 19.87 + } + +<= 2.05 Content + Content-Format: 110 + Observe: 10002 + Max-Age: 15 + + { + + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696340184, + "v": 21.87 + } +]]>
+ +
+
Unsubscribe + +A CoAP client can unsubscribe simply by cancelling the observation as described in Section 3.6 of . The client MUST either use CoAP GET with the Observe Option set to 1 or send a CoAP Reset message in response to a notification. Also on Section 3.6 of the client can simply "forget" the observation and the server will remove it from the list of observers after the next notification. + +As per a server that transmits notifications mostly in non-confirmable messages, but it MUST send a notification in a confirmable message instead of a non-confirmable message at least every 24 hours. + +This value can be modified at the broker by the administrator of a topic by modifying the parameter "observer-check" on . This would allow to change the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource. + + + +
+
Delete topic-data + +A publisher MAY delete a topic by making a CoAP DELETE request on the topic-data URI. + +On success, the server returns a 2.02 (Deleted) response. + +When a topic-data resource is deleted, the broker SHOULD also delete the topic-data parameter in the topic resource, unsubscribe all subscribers by removing them from the list of observers and return a final 4.04 (Not Found) response as per Section 3.2. The topic is then set back to the half created state as per . + +Example: + +
0.04 DELETE + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + +<= 2.02 Deleted +]]>
+ +
+
+
Read latest data + +A client can get the latest published topic-data by making a GET request to the topic-data URI in the broker. Please note that discovery of the topic-data parameter is a required previous step (see ). + +On success, the server MUST return 2.05 (Content) response with the data. + +If the target URI does not match an existing resource or the topic is not in the fully created state (see ), the broker MUST return a response code 4.04 (Not Found). + +Example: + +
0.01 GET + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + +<= 2.05 Content + Content-Format: 110 + Max-Age: 15 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } +]]>
+ + + +
+
Rate Limiting + +The server hosting the topic-data may have to handle a potentially large number of publishers and subscribers at the same time. This means it could become overwhelmed if it receives too many publications in a short period of time. + +In this situation, if a publisher is sending publications too fast, the server SHOULD return a 4.29 (Too Many Requests) response . As described in , the Max-Age option in this response indicates the number of seconds after which the client may retry. The broker MAY also stop publishing messages from that publisher for the indicated time. + + + +When a publisher receives a 4.29 (Too Many Requests) response, it MUST NOT send any new publication requests to the same topic-data resource before the time indicated by the Max-Age option has passed. + +
+
+
CoAP Pubsub Parameters + +This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and configuration process (see ). The table below summarizes them and specifies the CBOR key to use instead of the full descriptive name. + +Note that the media type application/core-pubsub+cbor MUST be used when these parameters are transported in the respective message fields. + +
+ +
+
Security Considerations + +The architecture presented in this document inherits the security considerations from CoAP and Observe , as well as from Web Linking , Link-Format , and the CoRE Resource Directory . + +Communications between each client and the broker MUST be secured, e.g., by using OSCORE or DTLS . Security considerations for the used secure communication protocols apply too. + +The content published on a topic by a publisher client SHOULD be protected end-to-end between the publisher and all the subscribers to that topic. In such a case, it MUST be possible to assert source authentication of the published data. This can be achieved at the application layer, e.g., by using COSE , , . + +Access control of clients at the broker MAY be enforced for performing discovery operation, and SHOULD be enforced in a fine-grained fashion for operations related to the the creation, update, and deletion of topic resources, as well as for operations on topic-data resources such as publication on and subscription to topics. This prevents rogue clients to, among other things, repeatedly create topics at the broker or publish (large) contents, which may result in Denial of Service against the broker and the active subscribers. + +Building on , its application profile for publish-subscribe communication with CoAP provides a security model that can be used in the architecture presented in this document, in order to enable secure communication between the different parties as well as secure, authorized operations of publishers and subscribers that fulfill the requirements above. + +In particular, the application profile above relies on the ACE framework for Authentication and Authorization in Constrained Environments (ACE) and defines a method to: authorize publishers and subscribers to perform operations at the broker, with fine-grained access control; authorize publishers and subscribers to obtain the keying material required to take part to a topic managed by the broker; protect published data end-to-end between its publisher and all the subscribers to the targeted topic, ensuring confidentiality, integrity, and source authentication of the published content end-to-end. That approach can be extended to enforce authorization and fine-grained access control for administrator clients that are intended to create, update, and delete topic configurations at the broker. + +
+
IANA Considerations + +This document has the following actions for IANA. + +Note to RFC Editor: Please replace all occurrences of "&SELF;" with the RFC number of this specification and delete this paragraph. + +
Media Type + +IANA is requested to add the following Media-Type to the "Media Types" +registry . + + + Name + Template + Reference + pubsub+cbor + application/pubsub+cbor + RFC XXXX, + + +
+
Type name:
+
+ application +
+
Subtype name:
+
+ pubsub+cbor +
+
Required parameters:
+
+ N/A +
+
Optional parameters:
+
+ N/A +
+
Encoding considerations:
+
+ binary (CBOR data item) +
+
Security considerations:
+
+ of RFC XXXX +
+
Interoperability considerations:
+
+ none +
+
Published specification:
+
+ of RFC XXXX +
+
Applications that use this media type:
+
+ This type is used by clients that create, retrieve, and update topic configurations at servers acting as a pub-sub broker. +
+
Fragment identifier considerations:
+
+ N/A +
+
Person & email address to contact for further information:
+
+ CoRE WG mailing list (core@ietf.org), +or IETF Applications and Real-Time Area (art@ietf.org) +
+
Intended usage:
+
+ COMMON +
+
Restrictions on usage:
+
+ none +
+
Author/Change controller:
+
+ IETF +
+
Provisional registration:
+
+ no +
+
+ +
+
Content-Format + +IANA has added the following Content-Formats to the + +sub-registry, within the "Constrained RESTful Environments (CoRE) +Parameters" Registry , as follows: + + + Content Type + Content Coding + ID + Reference + application/pubsub+cbor + - + TBD9 + RFC XXXX + + +TBD9 is to be assigned from the space 256..999. + +
+
CoAP Pubsub Parameters + +IANA is asked to register the following entries in the subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry group. + +This specification establishes the "Pubsub Topic Configuration Parameters" IANA registry within the "Constrained RESTful Environments (CoRE) +Parameters" registry group. + +The columns of this registry are: + + + Name: This is a descriptive name that enables easier reference to the item. The name MUST be unique. It is not used in the encoding. + CBOR Key: This is the value used as CBOR key of the item. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges of values use different registration policies . Integer values from -256 to 255 as well as text strings of length 1 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535, as well as text strings of length 2 are designated as "Specification Required". Integer values greater than 65535 as well as text strings of length greater than 2 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use". + CBOR Type: This contains the CBOR type of the item, or a pointer to the registry that defines its type, when that depends on another item. + Reference: This contains a pointer to the public specification for the item. + + +The registry is initially populated with the entries in of . + +
+
Resource Types + +IANA is asked to enter the following values in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained Restful Environments (CoRE) Parameters" registry group. + +
+ +
+
+
Acknowledgements + +The current version of this document contains a substantial contribution by Klaus Hartke's proposal , which defines the topic resource model and structure as well as the topic lifecycle and interactions. It also follows a similar architectural design as that provided by Marco Tiloca's . + +The authors would like to also thank Carsten Bormann, Hannes Tschofenig, Zach Shelby, Mohit Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran Selander, Mikko Majanen, Olaf Bergmann and Oscar Novo for their valuable contributions and reviews. + +
+ + + + + + + + + + + + + + URI Template + + + + + + + + A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] + + + + + + + + + Constrained RESTful Environments (CoRE) Link Format + + + + This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] + + + + + + + + + The Constrained Application Protocol (CoAP) + + + + + + The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. + CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. + + + + + + + + + "Too Many Requests" Response Code for the Constrained Application Protocol + + + + A Constrained Application Protocol (CoAP) server can experience temporary overload because one or more clients are sending requests to the server at a higher rate than the server is capable or willing to handle. This document defines a new CoAP response code for a server to indicate that a client should reduce the rate of requests. + + + + + + + + + Constrained RESTful Environments (CoRE) Resource Directory + + + + + + + + In many Internet of Things (IoT) applications, direct discovery of resources is not practical due to sleeping nodes or networks where multicast traffic is inefficient. These problems can be solved by employing an entity called a Resource Directory (RD), which contains information about resources held on other servers, allowing lookups to be performed for those resources. The input to an RD is composed of links, and the output is composed of links constructed from the information stored in the RD. This document specifies the web interfaces that an RD supports for web servers to discover the RD and to register, maintain, look up, and remove information on resources. Furthermore, new target attributes useful in conjunction with an RD are defined. + + + + + + + + + Object Security for Constrained RESTful Environments (OSCORE) + + + + + + + This document defines Object Security for Constrained RESTful Environments (OSCORE), a method for application-layer protection of the Constrained Application Protocol (CoAP), using CBOR Object Signing and Encryption (COSE). OSCORE provides end-to-end protection between endpoints communicating using CoAP or CoAP-mappable HTTP. OSCORE is designed for constrained nodes and networks supporting a range of proxy operations, including translation between different transport protocols. + Although an optional functionality of CoAP, OSCORE alters CoAP options processing and IANA registration. Therefore, this document updates RFC 7252. + + + + + + + + + Observing Resources in the Constrained Application Protocol (CoAP) + + + + The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. + + + + + + + + + Key words for use in RFCs to Indicate Requirement Levels + + + + In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. + + + + + + + + + + Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words + + + + RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. + + + + + + + + + + Media Types + + IANA + + + + + + + Constrained RESTful Environments (CoRE) Parameters + + IANA + + + + + + + + + + + + + + + + Web Linking + + + + This specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). + It also defines the serialisation of such links in HTTP headers with the Link header field. + + + + + + + + + Guidelines for Writing an IANA Considerations Section in RFCs + + + + + + Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). + To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. + This is the third edition of this document; it obsoletes RFC 5226. + + + + + + + + + + CBOR Object Signing and Encryption (COSE): Structures and Process + + + + Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. + This document, along with RFC 9053, obsoletes RFC 8152. + + + + + + + + + + The Datagram Transport Layer Security (DTLS) Protocol Version 1.3 + + + + + + This document specifies version 1.3 of the Datagram Transport Layer Security (DTLS) protocol. DTLS 1.3 allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. + The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection / non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol. + This document obsoletes RFC 6347. + + + + + + + + + CBOR Object Signing and Encryption (COSE): Initial Algorithms + + + + Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines a set of algorithms that can be used with the CBOR Object Signing and Encryption (COSE) protocol (RFC 9052). + This document, along with RFC 9052, obsoletes RFC 8152. + + + + + + + + + Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth) + + + + + + + + This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE-OAuth. The framework is based on a set of building blocks including OAuth 2.0 and the Constrained Application Protocol (CoAP), thus transforming a well-known and widely used authorization solution into a form suitable for IoT devices. Existing specifications are used where possible, but extensions are added and profiles are defined to better serve the IoT use cases. + + + + + + + + + CBOR Object Signing and Encryption (COSE): Countersignatures + + + + Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. CBOR Object Signing and Encryption (COSE) defines a set of security services for CBOR. This document defines a countersignature algorithm along with the needed header parameters and CBOR tags for COSE. This document updates RFC 9052. + + + + + + + + + + + Publish/Subscribe over the Constrained Application Protocol (CoAP) using the Constrained RESTful Application Language (CoRAL) + + Ericsson + + + + This document explores how the Constrained RESTful Application + Language (CoRAL) might be used for enabling publish/subscribe-style + communication over the Constrained Application Protocol (CoAP), which + allows CoAP nodes with long breaks in connectivity and/or up-time to + exchange data via a publish/subscribe broker. + + + + + + + + + + + + Admin Interface for the OSCORE Group Manager + + RISE AB + + + RISE AB + + + + + Ericsson AB + + + + Group communication for CoAP can be secured using Group Object + Security for Constrained RESTful Environments (Group OSCORE). A + Group Manager is responsible for handling the joining of new group + members, as well as managing and distributing the group keying + material. This document defines a RESTful admin interface at the + Group Manager that allows an Administrator entity to create and + delete OSCORE groups, as well as to retrieve and update their + configuration. The ACE framework for Authentication and + Authorization is used to enforce authentication and authorization of + the Administrator at the Group Manager. Protocol-specific transport + profiles of ACE are used to achieve communication security, proof-of- + possession, and server authentication. + + + + + + + + + + + + Publish-Subscribe Profile for Authentication and Authorization for Constrained Environments (ACE) + + Ericsson + + + Brunel University + + + RISE AB + + + + This document defines an application profile of the Authentication + and Authorization for Constrained Environments (ACE) framework, to + enable secure group communication in the Publish-Subscribe (pub/sub) + architecture for the Constrained Application Protocol (CoAP) [draft- + ietf-core-coap-pubsub], where Publishers and Subscribers communicate + through a Broker. This profile relies on protocol-specific transport + profiles of ACE to achieve communication security, server + authentication, and proof-of-possession for a key owned by the Client + and bound to an OAuth 2.0 Access Token. This document specifies the + provisioning and enforcement of authorization information for Clients + to act as Publishers and/or Subscribers, as well as the provisioning + of keying material and security parameters that Clients use for + protecting their communications end-to-end through the Broker. + + Note to RFC Editor: Please replace "[draft-ietf-core-coap-pubsub]" + with the RFC number of that document and delete this paragraph. + + + + + + + + + + + + Key Provisioning for Group Communication using ACE + + Ericsson AB + + + RISE AB + + + + This document defines how to use the Authentication and Authorization + for Constrained Environments (ACE) framework to distribute keying + material and configuration parameters for secure group communication. + Candidate group members acting as Clients and authorized to join a + group can do so by interacting with a Key Distribution Center (KDC) + acting as Resource Server, from which they obtain the keying material + to communicate with other group members. While defining general + message formats as well as the interface and operations available at + the KDC, this document supports different approaches and protocols + for secure group communication. Therefore, details are delegated to + separate application profiles of this document, as specialized + instances that target a particular group communication approach and + define how communications in the group are protected. Compliance + requirements for such application profiles are also specified. + + + + + + + + + + + + + + +
+ Contributors + + RISE AB +
+ marco.tiloca@ri.se +
+ +Marco offered comprehensive reviews and insightful guidance on the recent iterations of this document. His contributions were particularly notable in the Security Considerations section, among others. + +
+ + + + + + +