3. Quick Start: Primary Security Configurations

Security Plugins provides a wide variety of highly customizable security features that can be tailored to address the specific needs of your system. The multitude of options can be overwhelming at first, so this chapter provides a set of recommended configurations for common threat scenarios to help you jump-start your configuration process.

The configurations presented below address the majority of real-world deployments. The following sections explain the rationale behind each configuration choice and provide links to more detailed information.

3.1. Primary Security Configuration Options

There are three primary security configurations to consider as a starting point for most deployments. These entry-level security options address the most common threat scenarios:

Domain-level protection with Pre-Shared Key Protection
Domain-level protection with Builtin Security Plugins
Topic-granular protection inside domains with Builtin Security Plugins

Each configuration builds on the previous one, adding additional protection for more advanced threat scenarios.

3.1.1. Domain-level protection with Pre-Shared Key Protection

The Pre-Shared Key Protection security mechanism is the simplest configuration option. It uses the Lightweight Builtin Security Plugins to protect your data with pre-shared keys. This configuration is suitable for scenarios where:

you need to protect your data from outsiders
you don’t need fine-grained control over who can publish or subscribe to specific Topics
you have a resource-constrained environment

3.1.1.1. Pre-Shared Key Protection overview

When using Pre-Shared Key Protection, all DomainParticipants in the domain share the same pre-shared key (PSK), and everyone with the passphrase can publish or subscribe to any Topic. Use this configuration when you have a fairly static system that you fully trust, and the only threat possible is from outsiders.

Pre-Shared Key Protection offers domain outsider integrity, confidentiality, and availability protection. This mechanism also consumes the least amount of resources and has the least impact on performance. For more details, see Pre-Shared Key Protection.

3.1.1.2. Configuring Pre-Shared Key Protection

To configure the Lightweight Builtin Security Plugins to use Pre-Shared Key Protection, simply set the dds.sec.crypto.rtps_psk_secret_passphrase to the passphrase of your choice. The same passphrase must be used across all DomainParticipants in the system. By default, the Lightweight Builtin Security Plugins encrypts all RTPS messages with AES256+GCM. The code below illustrates a typical PSK configuration profile:

<domain_participant_qos>
  <property>
    <value>
      <element>
        <name>com.rti.serv.load_plugin</name>
        <value>com.rti.serv.secure</value>
      </element>
       <element>
        <name>com.rti.serv.secure.library</name>
        <value>nddslightweightsecurity</value>
      </element>
      <element>
        <name>com.rti.serv.secure.create_function</name>
        <value>RTI_SecurityLightweight_PluginSuite_create</value>
      </element>
      <element>
        <name>com.rti.serv.secure.dds.sec.crypto.rtps_psk_secret_passphrase</name>
        <value>data:,0:YourPassphraseHere</value>
      </element>
    </value>
  </property>
</domain_participant_qos>

For more details about the Lightweight Builtin Security Plugins configuration, see Configuring the Lightweight Builtin Security Plugins.

3.1.2. Domain-level protection with Builtin Security Plugins

This configuration builds on the Pre-Shared Key Protection feature described in the previous section. However, it uses the Builtin Security Plugins instead of the Lightweight Builtin Security Plugins and adds domain insider integrity and availability protection. This configuration is a good solution for most use cases, and particularly recommended for scenarios where:

you need to protect your data from outsiders, and
you want to have fine-grained control over who can publish to specific Topics, and/or
you want to protect your data from insider availability and integrity attacks

3.1.2.1. Domain-level Builtin Security Plugins overview

The Builtin Security Plugins authenticates DomainParticipants when they join the domain. This participant verification enables you to authorize DomainParticipants based on their identity, and allows the participants to perform certain actions while disallowing others. You can also keep track of identities that can access your system and remove ones that become untrustworthy. This capability increases the configuration complexity, but it provides a significant increase in security for scenarios where you have to worry about insider threats.

In addition to Pre-Shared Key Protection, the Builtin Security Plugins protects communication with a unique symmetric key. This key is derived for each DataWriter and shared only with authorized DomainParticipants. Before authentication, all traffic is protected with the pre-shared key; after authentication, traffic is protected with the unique symmetric key. This means that even if an insider has the pre-shared key, they cannot tamper with the traffic of other DomainParticipants.

For information about domain-level tags, see Domain-Level Rules in the Governance Document section.

3.1.2.2. Configuring Builtin Security Plugins for domain-level protection

To use the Builtin Security Plugins, you need to set up a Public Key Infrastructure (PKI) with a Permissions Certificate Authority (CA) and an Identity CA. You also need to create a Governance Document and a Permissions Document that define the access control rules for your system. The code below illustrates a typical configuration profile that loads the Builtin Security Plugins and sets the pre-shared key for the initial authentication:

<domain_participant_qos>
  <property>
    <value>
      <element>
        <name>com.rti.serv.load_plugin</name>
        <value>com.rti.serv.secure</value>
      </element>
       <element>
        <name>com.rti.serv.secure.library</name>
        <value>nddssecurity</value>
      </element>
      <element>
        <name>com.rti.serv.secure.create_function</name>
        <value>RTI_Security_PluginSuite_create</value>
      </element>
      <element>
        <name>com.rti.serv.secure.dds.sec.crypto.rtps_psk_secret_passphrase</name>
        <value>data:,0:<YourPassphraseHere></value>
      </element>
      <!--
          ... (CA, Identity, Governance, Permissions configuration)
      -->
    </value>
  </property>
</domain_participant_qos>

The Governance Document defines your system protection mechanisms and policies. For domain-level protection with Builtin Security Plugins, you need to populate the Governance Document with the following configuration and then have it signed by the Permissions CA.

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://community.rti.com/schema/7.7.0/dds_security_governance.xsd">
  <domain_access_rules>
    <domain_rule>
      <domains>
        <id_range>
          <min>0</min>
          <tag>RTI_o11y</tag>
        </id_range>
      </domains>
      <rtps_protection_kind>ENCRYPT_WITH_ORIGIN_AUTHENTICATION</rtps_protection_kind>
      <rtps_psk_protection_kind>ENCRYPT</rtps_psk_protection_kind>
      <topic_access_rules>
        <topic_rule>
          <topic_expression>*</topic_expression>
          <enable_discovery_protection>FALSE</enable_discovery_protection>
          <enable_liveliness_protection>FALSE</enable_liveliness_protection>
          <enable_read_access_control>TRUE</enable_read_access_control>
          <enable_write_access_control>TRUE</enable_write_access_control>
          <metadata_protection_kind>NONE</metadata_protection_kind>
          <data_protection_kind>NONE</data_protection_kind>
        </topic_rule>
      </topic_access_rules>
    </domain_rule>
  </domain_access_rules>
</dds>

You also need to create a Permissions Document for each DomainParticipant in your system to define the identity of the DomainParticipant and the permissions it has. This file also needs to be signed by the Permissions CA. The following Permissions Document allows ParticipantA to publish on the temperature Topic and subscribe to the pressure Topic:

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../schema/dds_security_permissions.xsd">
    <permissions>
        <grant name="ParticipantA">
            <subject_name>/C=US/ST=CA/O=Real Time Innovations/emailAddress=ecdsa01Peer01@rti.com/CN=RTI ECDSA01 (p256) PEER01</subject_name>
            <validity>
                <not_before>2026-01-01T01:00:00</not_before>
                <not_after>2037-09-14T01:00:00</not_after>
            </validity>
                <allow_rule>
                    <domains>
                        <id>0</id>
                        <id>2</id>
                    </domains>
                    <publish>
                        <topics>
                            <topic>temperature</topic>
                        </topics>
                    </publish>
                    <subscribe>
                        <topics>
                            <topic>pressure</topic>
                        </topics>
                    </subscribe>
                </allow_rule>
            <default>DENY</default>
        </grant>
    </permissions>
</dds>

Finally, you need to set the Identity CA and Permissions CA certificates. This is done by setting the com.rti.serv.secure.dds.sec.crypto.identity_ca_certificate and com.rti.serv.secure.dds.sec.crypto.permissions_ca_certificate properties, respectively.

For more details about the above configuration, see Public Key Infrastructure (PKI), including the Governance Document and Permissions Document sections. For information about domain-level attributes, see Domain-Level Rules in the Cryptography chapter.

3.1.3. Topic-granular protection inside domains with Builtin Security Plugins

This configuration builds on the domain-level Builtin Security Plugins configuration described in the previous section and offers the same level of protection. But topic-level protection adds confidentiality protection for Topics that you want to protect from insiders. With this setup, only participants with the appropriate permissions can read the protected Topics.

This configuration is recommended in scenarios where:

you want to protect the confidentiality of your data from third-party applications running on the same domain, or
you want to protect the confidentiality of your data if a less secure application running on the same domain experiences a security breach

3.1.3.1. Topic-level Builtin Security Plugins overview

Topic-level protection is a unique feature of the Builtin Security Plugins that gives you fine-grained control over who can access specific Topics in your system. This configuration provides the highest protection level of all options discussed in this chapter, but it also has the highest performance footprint. This option allows you to protect the confidentiality of certain Topics, while still offering the domain insider protection from the previous configuration.

This level of access control is implemented by encrypting the data of the protected Topics with a unique symmetric key that is only shared among the Endpoints that have permissions to access those Topics. This means that even if an insider has access to the domain and can authenticate with the DomainParticipant, they cannot read the data of the protected Topics unless they have the appropriate permissions.

For details about topic-level tags, see Topic-Level Rules in the Governance Document section.

3.1.3.2. Configuring Builtin Security Plugins for topic-level protection

To use topic-level protection, modify your Governance Document to include the <metadata_protection_kind>ENCRYPT</metadata_protection_kind> tag in the Topic access rules for those Topics you want to protect. The following Governance Document example enables this protection for all Topics in the system:

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://community.rti.com/schema/7.7.0/dds_security_governance.xsd">
  <domain_access_rules>
    <domain_rule>
      <domains>
        <id_range>
          <min>0</min>
          <tag>RTI_o11y</tag>
        </id_range>
      </domains>
      <rtps_protection_kind>ENCRYPT_WITH_ORIGIN_AUTHENTICATION</rtps_protection_kind>
      <rtps_psk_protection_kind>ENCRYPT</rtps_psk_protection_kind>
      <topic_access_rules>
        <topic_rule>
          <topic_expression>*</topic_expression>
          <enable_discovery_protection>FALSE</enable_discovery_protection>
          <enable_liveliness_protection>FALSE</enable_liveliness_protection>
          <enable_read_access_control>TRUE</enable_read_access_control>
          <enable_write_access_control>TRUE</enable_write_access_control>
          <metadata_protection_kind>ENCRYPT</metadata_protection_kind>
          <data_protection_kind>NONE</data_protection_kind>
        </topic_rule>
      </topic_access_rules>
    </domain_rule>
  </domain_access_rules>
</dds>

To learn more about Topic rule attributes, see Topic-Level Rules in the Cryptography chapter.

3.2. Advanced Security Configuration Options

The configurations presented above are good options for starting most deployments, and they should be sufficient for most systems. However, Security Plugins is highly configurable and can be tailored to meet the specific needs of your system.

You can further customize the configurations presented in this chapter. Familiarize yourself with the available options and different design concepts published in this manual to find the best security settings for your system.

3.2.1. Applying STRIDE principles to your configuration

The STRIDE threat modeling framework can be a useful tool to identify the specific threats that your system may face and design a configuration that addresses those threats. The fundamental configurations presented in this chapter stem from the STRIDE principles, and they are designed to address the most common threats.

If you have specific threats that are not covered by the above configurations, you can use the STRIDE principles to design a configuration that addresses your system’s vulnerabilities. See Using STRIDE Threat Modeling to Analyze Security Risks in DDS Systems for more details about the STRIDE framework and how to apply it to your system.

3.2.2. Bridging between different configurations

RTI Routing Service can act as a bridge between different security configurations in the same system. For example, for a domain using Pre-Shared Key Protection domain-level protection and another domain with Builtin Security Plugins domain-level protection, you can use Routing Service to bridge between them.

Use Routing Service to bridge between parts of your system that have different security requirements. This approach offers better access control than using the least common denominator configuration for the whole system. Adopting this strategy enables the best performance and highest level of protection for each part of your system, without compromising on either.

For more details, see the RTI Routing Service User’s Manual.