Protecting Pub/Sub Topics¶
VIP authorization enables VOLTTRON platform owners to protect pub/sub topics. More specifically, a platform owner can limit who can publish to a given topic. This protects subscribers on that platform from receiving messages (on the protected topic) from unauthorized agents.
Example¶
To protect a topic, add the topic name to
$VOLTTRON_HOME/protected_topics.json
. For example, the following
protected-topics file declares that the topic foo
is protected:
{
"write-protect": [
{"topic": "foo", "capabilities": ["can_publish_to_foo"]}
]
}
Note: The capability name can_publish_to_foo
is not special. It
can be any string, but it is easier to manage capabilities with
meaningful names.
Now only agents with the capability can_publish_to_foo
can publish
to the topic foo
. To add this capability to authenticated agents,
run volttron-ctl auth update
(or volttron-ctl auth add
for new
authentication entries), and enter can_publish_to_foo
in the capabilities
field:
capabilities (delimit multiple entries with comma) []: can_publish_to_foo
Agents that have the can_publish_to_foo
capabilites can publish to topic foo
.
That is, such agents can call:
self.vip.pubsub.publish('pubsub', 'foo', message='Here is a message')
If unauthorized agents try to publish to topic foo
they will get an exception:
to publish to topic "foo" requires capabilities ['can_publish_to_foo'], but capability list [] was provided
Regular Expressions¶
Topic names in $VOLTTRON_HOME/protected_topics.json
can be specified
as regular expressions. In order to use a regular expression, the topic name
must begin and end with a “/”. For example:
{
"write-protect": [
{"topic": "/foo/*.*/", "capabilities": ["can_publish_to_foo"]}
]
}
This protects topics such as foo/bar
and foo/anything
.