Permissions Document

You are here:

6.3 Permissions Document

The Permissions Document is an XML document containing the permissions of the DomainParticipant and binding them to the subject name of the DomainParticipant as defined in the Identity Certificate. The Permissions CA must sign the Permissions Document. This document contains a set of <grant> sections, each of which contains a <subject_name> section, a <validity> section, zero or more <allow_rule> sections, and zero or more <deny_rule> sections. This document is exchanged during authentication handshaking, so to conserve bandwidth, it is best to have this document contain exactly one <grant> section, which contains the subject name and rules for the DomainParticipant that is sending the document.

The following sections describe the elements within the <publish> and <subscribe> sections, which are inside <allow_rule> and <deny_rule> sections.

6.3.1 Topics

The <topics> element defines the DDS Topic names that must be matched for the rule to apply. Topic names may be given explicitly or by means of Topic name expressions. Each topic name or topic-name expression appears separately in a <topic> sub-element within the <topics> element. The Topic name expression syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6.

Example (appearing within an <allow_rule> and within a publish or subscribe action):

<topics>

    <topic>Square</topic>

    <topic>B*</topic>

</topics>

The above topic condition would match Topic “Square” and any topic that starts with a “B”.

6.3.2 Partitions

The RTI Connext DDS Core Libraries User's Manual describes the PartitionQosPolicy as a sequence of strings that belong to a Publisher or Subscriber. The Security Plugins Access Control plugin uses these partitions to determine whether or not a DataWriter or DataReader is allowed to exist according to the Permissions Document. Inside the Permissions Document, the <partitions> element may appear within a <publish> or <subscribe> element. <partitions> may contain one or more <partition> elements, each containing a string. For example:

<subscribe>

    <topics>

        <topic>Square</topic>

    </topics>

    <partitions>

        <partition>aPartition1</partition>

        <partition>aPartition2</partition>

        <partition>bPartition*</partition>

    </partitions>

</subscribe>

Note the asterisk in the third partition. POSIX fnmatch() matching is allowed for the <partition> element.

6.3.2.1 Allowed

If the <partitions> are under an <allow_rule>, then the <partitions> delimit an allowed partitions condition section. In order for an action (e.g., a publish action) to meet the allowed partitions condition, the set of the partitions associated with the DDS Entity performing the action (e.g., a DataWriter for a publish action) must be contained in the set of partitions defined by the allowed partitions condition section. If there is no <partitions> section, then the default "empty string" partition is assumed. This means that the allow action (e.g., publish action) would only allow publishing on the "empty string" partition.

Example (appearing within a <allow_rule> and within a <publish> action):

<partitions>

    <partition>A</partition>

    <partition>B</partition>

</partitions>

The above allowed partitions condition would be matched if the partitions associated with the DDS Entity performing the action (e.g., DataWriter for publish action) are a subset of the set [A, B] . So it would be OK to publish in partition A, in B, or in [A, B] but not in [A, B, C] (assuming the value of the property access_control.use_530_partitions is FALSE) or in the "empty string" partition.

6.3.2.2 Denied

If the <partitions> are under a <deny_rule>, then the <partitions> delimit a denied partitions condition section. For this condition to be met, the DDS Entity associated with the action (e.g., DataWriter for a publish action) must have a partition that matches one of the partitions explicitly listed in the denied partitions condition section. If there is no <partitions> section, then the "*" partition expression is assumed. This means that the deny action (e.g., deny publish action) would apply regardless of the partitions associated with the DDS Endpoint (e.g., DataWriter for a publish action).

Example (appearing within a <deny_rule> and within a <publish> action):

<partitions>

    <partition>A</partition>

    <partition>B</partition>

</partitions>

The above denied partitions condition would be matched if the partitions associated with the DDS Entity performing the action (e.g., DataWriter for a publish action) intersect the set [A, B]. So, it would be OK to publish in partition C or in the "empty string" partition, but not in partition A, in [A,B], or in [A, B, C].

6.3.2.3 Partitions Mutability

Security Plugins does not allow a Publisher to change the PartitionQosPolicy after the Publisher has been enabled if the Publisher contains any DataWriter that meets the following two criteria:

The TopicSecurityAttributes for that DataWriter have is_read_protected (which corresponds to enable_read_access_control in the Governance Document) set to TRUE.
The DataWriter has the DurabilityQos policy kind set to something other than VOLATILE.

When these two criteria are met, a DataWriter should send historical data only to DataReaders that were passing the topic access control rules at the time the historical data was generated. The rule about PartitionQos immutability enforces this behavior by conservatively preventing a DataWriter of a protected topic from sending historical data to DataReaders that were not matched before a PartitionQos change and that potentially could have failed to pass the topic access control rules.

6.3.3 Data Tags

The RTI Connext DDS Core Libraries User's Manual describes the DataTagQosPolicy as a sequence of (name, value) string pairs that belong to a DataWriter or DataReader. The Security Plugins Access Control plugin uses these tags to determine whether or not a DataWriter or DataReader is allowed to exist according to the Permissions Document. Inside the Permissions Document, the <data_tags> element may appear within a <publish> or <subscribe> element. <data_tags> may contain one or more <tag> elements, each containing a <name> and a <value> element. For example:

<subscribe>

    <topics>

        <topic>Sq*</topic>

    </topics>

    <data_tags>

        <tag>

            <name>Department</name>

            <value>Engineering</value>

        </tag>

        <tag>

            <name>Seniority</name>

            <value>Senior</value>

        </tag>

        <tag>

            <name>Title</name>

            <value>*Software*</value>

        </tag>

    </data_tags>

</subscribe>

Note the asterisk in the third tag’s value. POSIX fnmatch() matching is allowed for the <value> element, but not for the <name> element.

6.3.3.1 Allowed

If the <data_tags> are under an <allow_rule>, then the <data_tags> delimit an allowed data tags condition section. In order for an action (e.g., a publish action) to meet the allowed data tags condition, the set of the data tags associated with the DDS Entity performing the action (e.g., a DataWriter for a publish action) must be contained in the set of data tags defined by the allowed data tags condition section. If there is no <data_tags> section, then the default empty set is assumed. This means that the allow action (e.g., publish action) would only allow publishing if there are no data tags associated with the DDS Endpoint (DataWriter for a publish action).

Example (appearing within a <allow_rule> and within a <publish> action):

<data_tags>

    <tag>

        <name>aTagName1</name>

        <value>aTagValue1</value>

    </tag>

</data_tags>

The above allowed data tags condition would be matched if the data tags associated with the DDS Entity performing the action (e.g., DataWriter for publish action) are a subset of the set [(aTagName1, aTagValue)]. So it would be OK to publish using a DataWriter with no associated data tags, or a DataWriter with a single tag with name "aTagName1" and value "aTagValue1".

6.3.3.2 Denied

If the <data_tags> are under a <deny_rule>, then the <data_tags> delimit a denied data tags condition section. For this condition to be met, the DDS Entity associated with the action (e.g., DataWriter for a publish action) must have a data tag name and value pair that matches one of the data tags explicitly listed in the denied data tags condition section. If there is no <data_tags> section, then the "set of all possible tags" set is assumed as default. This means that the deny action (e.g., deny publish action) would apply regardless of the data tags associated with the DDS Endpoint (e.g., DataWriter for a publish action).

Example (appearing within a <deny_rule> and within a <publish> action):

<data_tags>

    <tag>

        <name>aTagName1</name>

        <value>aTagValue1</value>

    </tag>

</data_tags>

The above denied data tags condition would be matched if the data tags associated with the DDS Entity performing the action (e.g., DataWriter for a publish action) intersect the set [(aTagName1, aTagValue1)]. So it would not deny publishing using a DataWriter with no associated data-tags, or a DataWriter with a single tag with name "aTagName2", or a DataWriter with a single tag with name "aTagName1" and value "aTagValue2". But it would deny publishing using a DataWriter with two associated data tags [(aTagName1, aTagValue1), (aTagName2, aTagValue2)].