5. Access Control

Access Control makes sure that DomainParticipants in your system have the right permissions to join your DDS Secure Domains, to publish data on sensitive Topics, and to subscribe to them.

Once a DomainParticipant successfully authenticates, its permissions need to be validated and enforced. In this sense, the OMG DDS Security specification goes beyond many traditional security methods, where an application that is allowed to communicate within a secure system is trusted to access any information in it. Instead, the Access Control Plugin provides fine-grained permissions that let you define whether a DomainParticipant is allowed to join a particular Domain, whether it is allowed to subscribe to a specific Topic within a particular partition, etc. These permissions lock down the specific access that trusted applications have, so if one application becomes compromised, the damage to the system is limited.

There is a strong relationship between the Access Control Plugin and the Cryptography plugin because encryption keys need to be generated for Secure Entities based on the DomainParticipant’s permissions (see Secure Entities).

When a DomainParticipant is created, the Access Control Plugin will check whether the local Permissions Document has a grant for the DomainParticipant being created, based on its Identity Certificate. Then the plugin will check whether the DomainParticipant has permission to join the Domain and permission to create the necessary entities. This is done by examining the Permissions Document. Permissions Documents are exchanged between DomainParticipants during the Authentication process. This way, it’s possible to check whether the remote participants have permission to join the Domain, to publish/subscribe to certain Topics, etc. The Permissions Documents need to be signed by the Permissions CA, therefore it’s possible to verify that the Permissions Documents provided by remote participants are legitimate.

The Cryptography plugin has an important role in making sure the permissions apply by protecting the data. The Governance Document specifies how Domain-wide permissions are enforced, and how data and metadata is protected on those Domains. Permissions Documents provide granular access control at an individual participant level.

Definition

We will refer to “Governance Document” and “Permissions Document” as the abstract concept that contains the Governance rules or Permission grants that will apply in the system. On the other hand, we will refer to Governance Document and Permissions Document to refer to the XML representation of the Governance rules and Permission grants. XML representation is the only one that is supported in the latest version of the OMG DDS Security specification and also in the current version of the Security Plugins, so we will use these terms interchangeably in this chapter.

Note

In the case of Lightweight Builtin Security Plugins, which implements OMG DDS Security 1.2 specification builtin PSK plugins, the Access Control Plugin does not support granular access control. Instead, all access control is based on the access to the right PSK. Consequently, most of this chapter is only applicable to Builtin Security Plugins or custom security plugins.

Access Control consists of two components: governance and permissions checking. Governance is the process of configuring locally created DomainParticipants, Topics, DataWriters, and DataReaders to perform the right amount of security for the right use case. Permissions checking is the process of making sure locally created and remotely discovered Entities are allowed to do what they want to do. Both governance and permissions checking are enforced by XML documents that are signed by a Permissions Certificate Authority that can be the same as the Identity Certificate Authority that signs Identity Certificates. The XSD definitions of these documents are in XML Validation in the Governance Document and XML Validation in the Permissions Document.

For examples of these documents, refer to Elements of a Security Plugins System. Use these examples just as a reference; you will need to modify their content to match your system configuration (Domains, Topics, and used Identity Certificates) and sign the XML files. To specify that you want to use these files, add the corresponding properties detailed in Table 5.3 and Table 5.4 to the DomainParticipant’s PROPERTY QosPolicy (see QoS Properties).

5.1. Governance Document

The Governance Document is an XML document that specifies how the Domain should be secured. The Permissions CA (specified with the dds.sec.access.permissions_ca property) must sign the Governance Document using S/MIME version 3.2 format (which corresponds to the mime-type application/pkcs7-signature). The signed Governance Document needs to be provided to the plugins using the dds.sec.access.governance property as specified in Table 5.3.

This document configures multiple aspects that apply to the whole Domain, such as:

• whether the discovery/liveliness information should be protected and the kind of protection,

• whether the whole RTPS message should be protected and the kind of protection,

• whether a discovered DomainParticipant that cannot authenticate or fail the authentication should be allowed to join the Domain,

• whether any successfully authenticated DomainParticipant should be allowed to join the Domain and see the discovery data without checking the access control policies.

This document also specifies how the information on specific Topics within the Domain should be treated. More specifically, it specifies:

• whether the discovery/liveliness information on specific Topics should be sent using the secure (protected) writers or using the regular (unprotected) ones,

• whether read/write access to the Topic should be open to all or restricted to the DomainParticipants that have the proper permissions,

• whether the metadata information sent on the Topic should be protected and the kind of protection,

• whether the payload data (serialized application level data) sent on the Topic should be protected and the kind of protection.

The local DomainParticipant validates the locally loaded Governance Document against the Permissions CA specified in the dds.sec.access.permissions_ca property (see Table 5.3). If the Permissions CA cannot validate the Governance Document, the validation will be retried with the alternative certificates specified in the access_control.alternative_permissions_authority_files property (see Table 5.4). If none of the alternative CAs can validate the file (or if you did not set this property), the creation of the local DomainParticipant will fail.

The local DomainParticipant checks the compatibility of the Governance Document for remotely discovered DomainParticipants by checking the participant security attributes and the endpoint security attributes exchanged in the discovery, as explained in Governance Compatibility Validation.

Further details on the Governance Document: Governance Document.

5.2. Permissions Document

The Permissions Document specifies what actions a DomainParticipant is allowed to take in a Secure Domain. For example, it determines whether the DomainParticipant can join the Domain (participant-level rules), whether it can publish or subscribe to particular Topics, partitions, etc. (endpoint-level rules).

The Permissions Document is stored as an XML file. The Permissions CA must sign the Permissions Document using S/MIME version 3.2 format (which corresponds to the mime-type application/pkcs7-signature). The signed Permissions Document is provided to the Builtin Security Plugins using the dds.sec.access.permissions property, as specified in Table 5.3.

The local DomainParticipant validates the Permissions Document against the Permissions CA specified in the dds.sec.access.permissions_ca property (see Table 5.3). If the Permissions CA cannot validate the Permissions Document, the validation will be retried with the alternative certificates specified in the access_control.alternative_permissions_authority_files property (see Table 5.4). If none of the alternative CAs can validate the Permissions Document (or if you did not set this property), the validation process will fail.

The Permissions Document contains a set of grant sections, each of which contains a subject_name or subject_name_expression section, a validity section, zero or more allow_rule sections, and zero or more deny_rule sections. Each grant contains the permissions of a particular subject name or subject name expression, and the rules in Rules for matching a subject name in the Permissions Document determine which grant is bound to a particular DomainParticipant. The validity tag determines whether the Permissions Document is valid for the current date and time. Please note that in the current version of Connext, the signed Permissions Document only supports validity dates between 1970-01-01T00:00:00Z and 2106-02-07T06:28:15Z. Any dates before 1970-01-01T00:00:00Z will result in an error, and any dates after 2106-02-07T06:28:15Z will be treated as 2106-02-07T06:28:15Z. Currently, Connext is undefined if the system time is after 7 February 2106, 06:28:15 UTC.

Permissions Documents are exchanged between DomainParticipants during the authentication process to claim and verify permissions. Hence, to conserve bandwidth, it is best for this document to have exactly one grant section, which contains the subject name and rules for the DomainParticipant presenting it.

For more information about the Permissions Document, its structure, and its role in your secured system, see Permissions Document.

Using the domains tag you can control what Domains your DomainParticipants are allowed to join (participant-level permissions), as described in Specifying Domains. The following sections describe how to give your DomainParticipants permission to publish and subscribe to different Topics based on the topic name, partitions, and data tags. These endpoint-level permissions are specified using the elements in the publish and subscribe sections, which are inside the allow_rule and deny_rule sections.

5.2.1. Rules for matching a subject name in the Permissions Document

The Permissions Document contains a set of grant sections, each of which must contain either a subject_name or a subject_name_expression XML element. If a valid match is found between the subject name of the DomainParticipant (as defined in its Identity Certificate) and one of the subject names in the Permissions Document’s grants, then the DomainParticipant is bound to the rules for that grant.

The Builtin Security Plugins consider that a match is valid if one of the following occurs:

• The Permissions Document grant has a subject_name element with attributes that exactly match those from the DomainParticipant’s Identity Certificate subject name. Capitalization is ignored when comparing the attribute values. The ordering of the attributes may be different between the subject_name and the DomainParticipant’s Identity Certificate subject name.

  • There can only be one exact match because different grants with the same value of the subject_name element are not allowed. The Builtin Security Plugins also detect a duplicate subject_name that has a different attribute order.

• The Permissions Document grant has a subject_name_expression element with attributes that match the ones from the DomainParticipant’s Identity Certificate subject name. This is a case-sensitive match that follows the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6. The ordering of the attributes may be different between the subject_name_expression and the DomainParticipant’s Identity Certificate subject name.

  • A DomainParticipant’s Identity Certificate subject name can match multiple subject_name_expression grants. Only the first matching subject_name_expression will be considered (even if later patterns are more specific).

  • Different grants can have values of subject_name_expression that are functionally equivalent. The Builtin Security Plugins will not detect these duplicates. The Builtin Security Plugins detect only exactly duplicated attribute values of the subject_name_expression elements (ordering of the attributes in the expression may vary).

Warning

An exact (case-insensitive, order of attributes may vary) match between the DomainParticipant’s Identity Certificate subject name and a subject_name will take precedence over a (case-sensitive, order of attributes may vary) pattern match with a subject_name_expression, regardless of the positions of their grants in the Permissions Document. To improve debuggability, the Builtin Security Plugins will log a warning message if a subject_name match happens after a subject_name_expression match.

Some examples

This Identity Certificate subject name:

C = US, ST = CA, O = Real-Time Innovations, CN = RTI ECDSA01 (p256) PEER01, emailAddress = ecdsa01Peer01@rti.com

will match any of the following <subject_name> values:

<grant name="ExactMatch">
  <subject_name>
    C = US, ST = CA, O = Real-Time Innovations, CN = RTI ECDSA01 (p256) PEER01, emailAddress = ecdsa01Peer01@rti.com
  </subject_name>
  [...]
</grant>

<!--
    Match: we ignore capitalization, whitespace around attribute values,
    and the order of the attributes. The ',' ';' '/' characters can act
    as delimiters between attributes.
-->
<grant name="MatchRegardlessOrderCaseAndWhitespace">
  <subject_name>
    /C=US/ST=CA/O=Real-Time Innovations/emailAddress=ecdsa01Peer01@rti.com/CN=rti ecdsa01 (p256) PEER01
  </subject_name>
  [...]
</grant>

or the following <subject_name_expression> values:

<grant name="ExactMatchInExpression">
  <subject_name_expression>
    /C=US/ST=CA/O=Real-Time Innovations/CN=RTI ECDSA01 (p256) PEER01/emailAddress=ecdsa01Peer01@rti.com
  </subject_name_expression>
  [...]
</grant>

<!--
    Match: we ignore whitespace around attribute values, and the order
    of the attributes. We do not ignore capitalization.
    The ',' ';' '/' characters can act as delimiters between attributes.
-->
<grant name="MatchRegardlessOrderAndWhitespace">
  <subject_name_expression>
    /C=US/ST=CA/O=Real-Time Innovations/emailAddress=*@rti.com/CN=RTI ECDSA01*
  </subject_name_expression>
  [...]
</grant>

The following <subject_name_expression> elements are considered duplicates if they are found in the same Permissions Document.

<!--
    Same attribute names and values, but in different order. We still
    detect them as duplicates.
-->
<grant name="DuplicateRegardlessOrderEmailLater">
  <subject_name_expression>
    /C=US/ST=CA/O=Real-Time Innovations/CN=*/emailAddress=ecdsa01Peer01@rti.com
  </subject_name_expression>
  [...]
</grant>

<grant name="DuplicateRegardlessOrderEmailFirst">
  <subject_name_expression>
    /C=US/CN=*/ST=CA/emailAddress=ecdsa01Peer01@rti.com/O=Real-Time Innovations
  </subject_name_expression>
  [...]
</grant>

But we wouldn’t consider them duplicates if they had different capitalization or attribute values. The Builtin Security Plugins only detects duplicates if the attribute values are exactly the same, even if they are redundant or functionally equivalent patterns. For example, these <subject_name_expression> elements won’t be detected as duplicates even though the second expression is a subset of the first one:

<!--
    Subject names matching the second expression will also match the
    first one. However, this redundancy will not cause the Builtin
    Security Plugins to reject this Permissions Document. Only the first
    grant will ever be used, and the second grant will always be
    silently ignored.
-->
<grant name="LessSpecificMatchFirst">
  <subject_name_expression>
    /C=US/CN=*/ST=CA/emailAddress=*@rti.com/O=Real-Time Innovations
  </subject_name_expression>
  [...]
</grant>

<grant name="MoreSpecificMatchIgnored">
  <subject_name_expression>
    /C=US/ST=CA/O=Real-Time Innovations/CN=*/emailAddress=*01@rti.com
  </subject_name_expression>
  [...]
</grant>

If the Identity Certificate subject name matches both a <subject_name> and a <subject_name_expression> in the same Permissions Document, the <subject_name> will take precedence over the <subject_name_expression>. This happens regardless of the position of the <subject_name_expression> (before or after the <subject_name>) and its specificity:

<!-- The subject_name takes precedence over the expressions. -->
<grant name="ExpressionBefore">
  <subject_name_expression>
    /C=US/ST=CA/O=Real-Time Innovations/CN=RTI ECDSA01 (p256) PEER01/emailAddress=ecdsa01Peer01@rti.com
  </subject_name_expression>
  [...]
</grant>

<grant name="ExactMatchPreferred">
  <subject_name>
    /C=US/ST=CA/O=Real-Time Innovations/CN=rti ecdsa01 (p256) PEER01/emailAddress=ecdsa01Peer01@rti.com
  </subject_name>
  [...]
</grant>

<grant name="ExpressionAfter">
  <subject_name_expression>
    /C=US/ST=CA/O=Real-Time Innovations/CN=*/emailAddress=ecdsa01Peer01@rti.com
  </subject_name_expression>
  [...]
</grant>

5.2.2. 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 in a separate 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 tag):

<allow_rule>
  <publish>
    <topics>
      <topic>Square</topic>
      <topic>B*</topic>
    </topics>
  </publish>
</allow_rule>

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

5.2.3. Partitions

The partitions element defines the DDS Partition names that must be matched for the rule to apply (see PARTITION QosPolicy in the RTI Connext DDS Core Libraries User’s Manual). Partition names may be given explicitly or by means of partition-name expressions. Each partition name or partition-name expression appears in a separate partition sub-element within the partitions element. The partition-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 subscribe tag):

<allow_rule>
  <subscribe>
    <topics>
      <topic>Square</topic>
    </topics>
    <partitions>
      <partition>Partition1</partition>
      <partition>Partition2</partition>
      <partition>PartitionA*</partition>
    </partitions>
     ...
  </subscribe>
</allow_rule>

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

The partitions tag can appear within a publish element and affect DataWriters, within a subscribe element and affect DataReaders, or directly under the allow_rule or deny_rule tags and affect DomainParticipants.

5.2.3.1. Behavior of the partitions tag within an allow_rule

If the partitions tag is under an allow_rule, it delimits which partitions (specified within partition tags) are allowed. In order for an action (e.g., a publish action) to meet the allowed partitions condition, the set of partitions associated with the DDS Entity performing that action (e.g., a DataWriter for a publish action) must be contained by the set of partitions defined by the allowed partitions condition section.

As a limitation, if the DDS Entity performing an action (e.g., a DataWriter for a publish action) uses patterns in its partitions, these patterns must appear explicitly in the allowed partitions condition section. An exception to this rule is adding the * pattern to the allowed partitions condition section, which will allow the attempted action, regardless of the partitions announced by the DDS Entity.

If there is no partitions section, then the default “empty string” partition is assumed. Hence, the allowed action (e.g., a publish action) would only allow publishing on the “empty string” partition.

Example (appearing within a allow_rule and within a publish tag):

<allow_rule>
  <publish>
    <topics>
      <topic>Square</topic>
    </topics>
    <partitions>
      <partition>A</partition>
      <partition>B</partition>
    </partitions>
  </publish>
  ...
</allow_rule>

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 partition B, or in partition [A, B] but not in partition [A, B, C] [1] or in the “empty string” partition.

[1]

Assuming the property access_control.use_530_partitions is FALSE (see Table 5.4).

5.2.3.2. Behavior of the partitions tag within a deny_rule

If the partitions tag is under a deny_rule, it delimits which partitions (specified within partition tags) are denied. 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.

In other words, the Access Control Plugin will deny the attempted action if the set of partitions announced by the DDS Entity attempting to perform that action (e.g., DataWriter for a publish action) intersects the set of partitions defined in the denied partitions condition section. For computing the intersection, both concrete partitions and expressions containing patterns are considered. Note that if the DDS Entity only announces partitions containing patterns, it will fall back to the “empty string” partition. Therefore, the action will be denied if the denied partitions condition section intersects with the “empty string” partition.

If there is no partitions section, then the * partition expression is assumed. This means that the deny action (e.g., publish action) would apply regardless of the partitions associated with the DDS Entity (e.g., DataWriter for a publish action).

Example (appearing within a deny_rule and within a publish tag):

<deny_rule>
  <subscribe>
    <topics>
      <topic>Square</topic>
    </topics>
    <partitions>
      <partition>A</partition>
      <partition>B</partition>
    </partitions>
  </subscribe>
  ...
</deny_rule>

<default>ALLOW</default>

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 partition 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 partition [A,B], or in partition [A, B, C].

5.2.3.3. Partition Mutability

DataWriters need to avoid sending historical data to unauthorized DataReaders joining a new partition. Therefore, there are scenarios where Publishers are not allowed to change partitions. Note that these restrictions do not apply to Subscribers or to DomainParticipants.

The Security Plugins do not allow a Publisher to change the PARTITION QosPolicy 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 DURABILITY QosPolicy 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.

Figure 5.1 Reliable DataWriter Changing Partitions

5.2.4. Data Tags

The RTI Connext DDS Core Libraries User’s Manual describes the DATATAG QosPolicy as a sequence of (name, value) string pairs that belong to a DataWriter or DataReader (see DATATAG QosPolicy in the Core Libraries User’s Manual). The 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.

For further information on data tags, refer to Data Tagging.

5.2.4.1. Behavior of data_tags within an allow_rule

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 Endpoint 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 (e.g., DataWriter for a publish action).

Example (appearing within an allow_rule and within a publish tag):

<allow_rule>
  <publish>
    <topics>
      <topic>Square</topic>
    </topics>
    <data_tags>
       <tag>
           <name>aTagName1</name>
           <value>aTagValue1</value>
       </tag>
    </data_tags>
  </publish>
</allow_rule>

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.

5.2.4.2. Behavior of data_tags within a deny_rule

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 tag):

<deny_rule>
  <publish>
    <data_tags>
      <tag>
         <name>aTagName1</name>
         <value>aTagValue1</value>
      </tag>
    </data_tags>
  </publish>
</deny_rule>

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)]. Table 5.1 analyzes other scenarios for this concrete example.

Table 5.1 Effect of the Example Deny Rule When Different Data Tags Are Present

DataWriter Tag(s)	Allow/Deny
<tag> <name>aTagName1</name> <value>aTagValue1</value> </tag>	Deny
<tag> </tag>	Allow
<tag> <name>aTagName1</name> <value>aTagValue2</value> </tag>	Allow
<tag> <name>aTagName2</name> <value>aTagValue1</value> </tag>	Allow
<tag> <name>aTagName1</name> <value>aTagValue1</value> </tag> <tag> <name>aTagName2</name> <value>aTagValue2</value> </tag>	Deny

5.3. Related Governance Rules

This section describes the Access Control attributes that appear in the Governance Document.

5.3.1. Domain-level rules

The following attributes can be configured inside a domain_rule:

5.3.1.1. enable_join_access_control (within a domain_rule)

enable_join_access_control may be TRUE or FALSE. It controls whether or not DomainParticipant-level permissions are checked when a DomainParticipant is created or discovered.

When enable_join_access_control = TRUE, the local DomainParticipant will check whether it has permission to join the Domain. If it does, it will perform the same check for each of the remotely discovered DomainParticipants.

When enable_join_access_control = FALSE, the local DomainParticipant is still required to have a valid Permissions Document, but this Permissions Document is not required to allow the local DomainParticipant to join the Domain. Remote DomainParticipants are not even required to have a valid Permissions Document unless enable_read_access_control = TRUE or enable_write_access_control = TRUE for a discovered Topic.

Note that enable_join_access_control does not affect endpoint-level permissions such as publishing or subscribing to specific Topics.

The Access Control Plugin will not check participant-level permissions for DomainParticipants that cannot be authenticated because they either are unsecure participants or they fail to authenticate. Therefore, enable_join_access_control does not have any effect when allow_unauthenticated_participants = TRUE, and the remote participant is unauthenticated.

For more information, see Participant-Level Permissions, Endpoint-Level Permissions, and Unsecure DomainParticipants.

5.3.1.2. topic_access_rules (domain_rule)

topic_access_rules contains one or more topic_rule attributes where you can define your system’s security requirements on a per-topic basis (see Governance Document).

5.3.2. Topic-level rules

The following attributes can be configured inside a topic_rule:

5.3.2.1. enable_read_access_control (topic_rule)

This attribute may be TRUE or FALSE. It controls whether or not endpoint-level permissions are checked for DataReaders. If enable_read_access_control = TRUE for a given topic, the local permissions are enforced on locally created DataReaders of that topic, and the remote permissions are enforced on remotely discovered DataReaders of that topic.

5.3.2.2. enable_write_access_control (topic_rule)

This attribute may be TRUE or FALSE. It controls whether or not DataWriter permissions are checked. If enable_writer_access_control is TRUE for a given topic, the local permissions are enforced on locally created DataWriters of that topic, and the remote permissions are enforced on remotely discovered DataWriters of that topic.

5.3.2.3. No Matching Rule

If no matching domain (in the case of DomainParticipants) or topic rule (in the case of DataWriters/DataReaders) is found in the Governance Document, the Entity creation will fail when Access Control checks if this Entity can be created in this Domain. This is done because if there is no rule, the Access Control Plugin assumes no permissions, which is the more restrictive decision.

5.4. Advanced Access-Control Concepts

5.4.1. Participant-Level Permissions, Endpoint-Level Permissions, and Unsecure DomainParticipants

As mentioned earlier, you can control whether the Access Control Plugin will check participant-level permissions and endpoint-level permissions for remote participants with the enable_*_control Governance rules (see Related Governance Rules). The Access Control Plugin checks these permissions in different stages of the communication, so they are independent. (Note that successfully authenticated remote participants must present a grant matching the subject name in its Identity Certificate, even though remote permissions checking is disabled. Authenticated participants failing to provide such a grant will be rejected.)

The enable_join_access_control Governance rule controls whether the Access Control Plugin will check participant-level permissions for remotely discovered participants. Your local participant (P1) checks participant-level permissions when it discovers and authenticates a remote participant (P2). When enable_join_access_control = TRUE, P1 will check whether P2 has permission to join the Secure Domain. In other words, P1 will check whether P2 has an allow_rule that includes this Domain in its Permissions Document (as specified with the domains tag). When enable_join_access_control = FALSE, P1 skips this check.

In turn, enable_read_access_control, and enable_write_access_control Governance rules control whether the Access Control Plugin will check endpoint-level permissions for both locally created and remotely discovered Endpoints. When enable_read_access_control = TRUE for a given Topic (T), P1 will enforce permissions on locally created DataReaders of Topic T. Also, P1 will check whether P2 DataReaders have permission to subscribe to Topic T. In other words, when enable_read_access_control = TRUE , P1 will check:

1. Whether P1 has an allow_rule that includes permissions to subscribe to Topic T (as specified with the subscribe tag). This check takes place upon the creation of a DataReader for Topic T.

2. Whether P2 has an allow_rule that includes permissions to subscribe to Topic T (as specified with the subscribe tag). This check takes place upon the discovery of a DataReader for Topic T in P2.

The same logic applies to enable_write_access_control and DataWriters.

When allow_unauthenticated_participants = TRUE, unsecure DomainParticipants will be allowed to join the Domain. Since unsecure DomainParticipants do not load the Security Plugins, participant-level permissions and endpoint-level permissions for unsecure participants cannot be verified.

Continuing with our previous example, a remote unsecure participant (P3) will not load the Security Plugins; therefore, it cannot be bound to a Permissions or Governance Document. From P1’s perspective, this is similar to having a Permissions Document that denies permissions for publishing/subscribing to any secure Topic (but not for joining the Domain). As a result, P3 has permission to join any Secure Domain that sets allow_unauthenticated_participants = TRUE. However, P3 is only allowed to subscribe to Topics that do not enforce read access control (enable_read_access_control = FALSE) and is only allowed to publish Topics that do not enforce write access control (enable_write_access_control = FALSE). Please note that if allow_unauthenticated_participants = FALSE for this domain, communication ends when P1 fails to authenticate P3; neither endpoint discovery nor Permissions checks happen in this case.

To summarize:

• When enable_read_access_control = TRUE, the Topic is protected from unauthorized DataReaders (only participants that have permissions to subscribe to that Topic can subscribe to it).

• When enable_read_access_control = FALSE, any DataReader of this Topic can subscribe to it (provided that the DomainParticipant this DataReader belongs to, succeeds in joining the Secure Domain).

Therefore, enabling read access control (enable_read_access_control = TRUE) does not affect secure participants’ ability to publish a particular Topic. However, it does affect the unsecure participants’ ability to subscribe to that Topic, since only secure participants with permissions to subscribe to that Topic will be allowed to do so.

Also note that enable_read_access_control = TRUE will enforce checks on both locally created and remotely discovered DataReaders, regardless of the value of enable_join_access_control. The same logic applies to enable_write_access_control and DataWriters.

5.4.2. Access Control and Unauthenticated Participants

The following matrix shows the security implications of the combinations of allow_unauthenticated_participants and enable_join_access_control. As described in allow_unauthenticated_participants (domain_rule), allow_unauthenticated_participants determines whether participants failing to authenticate will be allowed to communicate in the system, whereas enable_join_access_control determines whether the participant-level permissions of successfully authenticated remote participants will be checked. In other words, allow_unauthenticated_participants deals with the result of the authentication process (performed right after the participant discovery phase); enable_join_access_control deals with the result of a participant-level permissions check (performed right after the remote participant is successfully authenticated). Also note that the participant-level permissions check does not apply to allowed unauthenticated remote participants (i.e., unauthenticated remote participants that are allowed in the Domain because allow_unauthenticated_participants = TRUE).

Table 5.2 Security Implications of allow_unauthenticated_participants and enable_join_access_control

allow_unauthenticated_participants	enable_join_access_control	Security Implications
FALSE	FALSE	Participants failing to authenticate (including unsecure participants) cannot join the Secure Domain. Once a remote secure participant successfully authenticates, the local participant trusts it to communicate in the Domain and its permissions are not checked. Note that the Authentication Plugin always checks whether the local secure participant has permissions to join the Domain, regardless of enable_join_access_control.
FALSE	TRUE	Participants failing to authenticate (including unsecure participants) cannot join the Secure Domain. When a remote secure participant successfully authenticates, its permissions to joining the Domain are locally checked. The remote participant will only be allowed in the Domain if it has the right permissions.
TRUE	FALSE	Participants failing to authenticate (including unsecure participants) can join the Secure Domain. However, they can only publish to Topics that are not protected against unauthorized DataWriters and can only subscribe to Topics that are not protected against unauthorized DataReaders.
TRUE	TRUE	Participants failing to authenticate (including unsecure participants) can join the Secure Domain. However, they can only publish to Topics that are not protected against unauthorized DataWriters and can only subscribe to Topics that are not protected against unauthorized DataReaders. When a remote secure participant successfully authenticates, its permissions to joining the Domain are locally checked. The remote participant will only be allowed in the Domain if it has the right participant-level permissions.

5.5. Properties for Configuring Access Control

Table 5.3 lists the properties that you can set to configure Access Control. These properties are configured through the DomainParticipant’s PROPERTY QosPolicy (see QoS Properties).

Table 5.3 DDS Security Properties for Configuring Access Control

Property Name	Property Value Description
dds.sec.access.permissions_ca	Required This Permissions Certificate Authority is used for signing access control governance and permissions XML files and verifying the signatures of those files. The Permissions Certificate Authority file may or may not be the same as the Identity Certificate Authority file. Two participants that want to securely communicate with each other must use the same Permissions Certificate Authority. The document should be in PEM format. You may specify either the file name or the document contents. If specifying the file name, the property value must have the prefix file: (no space after the colon), followed by the fully qualified path and name of the file. If specifying the contents of the document, the property value must have the prefix data:, (no space after the comma), followed by the contents inside the document. For example: "data:,-----BEGIN CERTIFICATE-----\nabcdef\n-----END CERTIFICATE-----" Note that the two \n characters are required. String. Default: NULL
dds.sec.access.governance	Required The signed document that specifies the level of security required per Domain and per Topic (see Governance Document). The Permissions CA (dds.sec.access.permissions_ca) must sign the Governance Document using S/MIME version 3.2 format (which corresponds to the mime-type application/pkcs7-signature). You may specify either the file name or the document contents. If specifying the file name, the property value must have the prefix file: (no space after the colon), followed by the fully qualified path and name of the file. If specifying the contents of the document, the property value must have the prefix data:, (no space after the comma), followed by the contents inside the document. For example: "data:,MIME-Version: 1.0\nContent-Type:...boundary=\"---7236--\"\n\n" Note that for signed XML files, all whitespace characters (’ ‘, ‘r’, ‘n’) are significant, and all quotes must be escaped by a backslash. The safest way to get the correct property value is to call the fread() function on the file and use the resulting buffer as the property value. String. Default: NULL
dds.sec.access.permissions	Required The signed document that specifies the access control permissions per Domain and per Topic (see Permissions Document) for individual DomainParticipants identified by subject names. The Permissions CA (dds.sec.access.permissions_ca) must sign the Permissions Document using S/MIME version 3.2 format (which corresponds to the mime-type application/pkcs7-signature). The subject_name element identifies the DomainParticipant to which the permissions apply. Each subject name can only appear in a single permissions section within the XML Permissions Document. The contents of the subject_name element should be the X.509 subject name for the DomainParticipant. The format of the subject name should conform to IETF RFC 4514 “Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names. Specifically, the = character should separate an attribute’s name from its value, and the , character should separate attributes from each other. See Hands-on 4 in the RTI Security Plugins Getting Started Guide for an example openssl command to extract a correctly-formatted subject name. A permissions section with a subject name that does not match the subject name given in the corresponding Identity Certificate will be ignored. The signed Permissions Document only supports validity dates between 1970-01-01T00:00:00Z and 2106-02-07T06:28:15Z. Any dates before 1970-01-01T00:00:00Z will result in an error, and any dates after 2106-02-07T06:28:15Z will be treated as 2106-02-07T06:28:15Z. Currently, Connext behavior is undefined if the system time is after 7 February 2106, 06:28:15 UTC. You may specify either the file name or the document contents. If specifying the file name, the property value must have the prefix “file:” (no space after the colon), followed by the fully qualified path and name of the file. If specifying the contents of the document, the property value must have the prefix “data:,” (no space after the comma), followed by the contents inside the document. For example: "data:,MIME-Version: 1.0\nContent-Type:...boundary=\"---7236--\"\n\n" Note that for signed XML files, all whitespace characters (’ ‘, ‘r’, ‘n’) are significant, and all quotes must be escaped by a backslash. The safest way to get the correct property value is to call the fread() function on the file and use the resulting buffer as the property value. String. Default: NULL
dds.sec.access.rtps_psk_protection_kind	Optional It specifies how to protect messages when using Pre-Shared Key Protection: don’t protect them, protect only their integrity, or protect both their integrity and confidentiality. This property can only be used in The Lightweight Builtin Security Plugins. The Builtin Security Plugins do not support this property. Instead, use the rtps_psk_protection_kind domain rule from the Governance Document. For more information, read rtps_psk_protection_kind (domain_rule). Enum: NONE (do not protect), SIGN (protect the integrity), ENCRYPT (protect the integrity and confidentiality). Default: ENCRYPT

Table 5.4 Security Plugins Properties for Configuring Access Control

Property Name (prefix with com.rti.serv.secure.) [2]	Property Value Description
access_control.alternative_permissions_authority_files	Optional A comma-separated list of alternative Permissions CA certificates. If verification of either the Permissions Document or the Governance Document fails with the main certificate (dds.sec.access.permissions_ca), verification will be retried with all of the corresponding alternative certificates. If none of the alternative certificates can be used to verify the file, the verification process will fail. If any of the alternative certificate files fail to be loaded, the DomainParticipant creation will fail. This property value may optionally contain file: (no space after the colon) as a prefix to any of the elements in the list. String. Default: NULL
access_control.use_530_permissions_rules_precedence	Optional How to deal with conflicting allow/deny rules in a Permissions Document when checking for a Topic, DataWriter, or DataReader’s permission to exist. If TRUE: the last rule will take precedence, which is consistent with the behavior in Connext 5.3.0 and earlier versions. If FALSE: the first rule will take precedence, which is consistent with the intended behavior of the OMG DDS Security specification (see How the Permissions are Interpreted). Boolean. Default: FALSE
access_control.use_530_logging_protection	Optional How to set the value of metadata_protection_kind for the Builtin Secure Logging Topic. If TRUE: the value will be NONE, which is consistent with Connext 5.3.0 behavior. If FALSE: the value will be SIGN, which is consistent with the behavior of the OMG DDS Security specification. Boolean. Default: FALSE
access_control.use_530_partitions	Optional How to determine a match between a DataWriter or DataReader’s partitions and an “allowed partitions” condition in a Permissions Document. If TRUE: an Entity is matched if it has at least one partition in the condition; this is consistent with the behavior in Connext 5.3.0 and earlier versions. If FALSE: an Entity is matched only if all of its partitions are in the condition; this is consistent with the behavior of the OMG DDS Security specification (see Partitions). For example, if a DataWriter has partitions [A, B], and a Permissions Document allows partitions [B, C], then when use_530_partitions = TRUE, the DataWriter is allowed because B is allowed. When use_530_partitions = FALSE, the DataWriter is not allowed because A is not allowed. Boolean. Default: FALSE
access_control.use_610_permissions_rules_precedence	Optional How to deal with conflicting allow/deny rules in a Permissions Document when checking for a DomainParticipant’s permission to exist. If false: the first rule will take precedence, which is consistent with the behavior of the OMG DDS Security specification (see How the Permissions are Interpreted). If true: the last rule will take precedence, which is consistent with the behavior in Connext 6.1.0 and earlier versions. If auto: for the local DomainParticipant, the first rule will take precedence. For discovered remote DomainParticipants, the last rule will take precedence only if the discovered DomainParticipant is Connext 6.1.0 or earlier. Enum: false, true auto Default: auto

[2]

Assuming you used com.rti.serv.secure as the alias to load the plugin. If not, change the prefix to match the string used with com.rti.serv.load_plugins, followed by the . character.