5. Hands-On 2: Defining Your System’s Security Requirements

In this Hands-On, we will define the security requirements for your project, expressing them in the form of a Governance File. We will sign this Governance File with the provided Permissions CA. Lastly, we will tell your secure participants where to find the new Governance File and we will see how the new security requirements are applied to your system.

Note

We will use the OpenSSL CLI to perform the security operations in the generation of the security artifacts. Make sure to include in the path your OpenSSL binary directory 8. The installation process is described in the RTI Security Plugins Installation Guide.

Note that the Security Plugins do not depend on OpenSSL to generate these artifacts; you can use the security toolkit of your choice.

5.1. Specifying the Security Requirements

If you completed Hands-On 1: Securing Connext DDS Applications, you should have two applications using Security Plugins to communicate securely. But what does “securely” actually mean? What kind or what level of security is being applied? As mentioned in Introduction to RTI Security Plugins, the answers to these questions are in the Governance File, which defines the security rules that every DomainParticipant in your Secure Domain needs to follow. We will now focus on writing a Governance File to specify your project’s security requirements.

Governance Files define two levels of rules that can be configured:

  • Domain-level rules, which affect participants in the Domain;

  • Topic-level rules, which affect Endpoints (DataReaders and DataWriters) for that Topic.

You will find a description of the currently available rules in the tables below. For more information, see these sections in the RTI Security Plugins User’s Manual:

Table 5.1 Domain-Level Rules

Rule

Description

Possible values

allow_unauthenticated_participants

Determines if a secure DomainParticipant is allowed to match a participant that is not able to successfully complete the authentication process. By disallowing unauthenticated participants, we prevent them from publishing or subscribing to Topics in our Secure Domain. 1

TRUE or FALSE

enable_join_access_control

Determines if the participant-level permissions configured in the Permissions File are enforced for remote participants.

TRUE or FALSE

discovery_protection_kind

Configures the Discovery Protection, determining what level of protection is applied to the Builtin Secure Discovery Topics.

ENCRYPT, ENCRYPT_WITH_ORIGIN_AUTHENTICATION, SIGN, SIGN_WITH_ORIGIN_AUTHENTICATION, NONE

liveliness_protection_kind

Configures the Liveliness Protection, determining what level of protection is applied to the Builtin Secure Liveliness Topic.

ENCRYPT, ENCRYPT_WITH_ORIGIN_AUTHENTICATION, SIGN, SIGN_WITH_ORIGIN_AUTHENTICATION, NONE

rtps_protection_kind

Configures the RTPS Protection, determining what level of protection is applied to RTPS messages.

ENCRYPT, ENCRYPT_WITH_ORIGIN_AUTHENTICATION, SIGN, SIGN_WITH_ORIGIN_AUTHENTICATION, NONE

Table 5.2 Topic-Level Rules

Rule

Description

Possible values

enable_discovery_protection

Determines if discovery information updates related to Endpoints from this Topic will be sent with the level of security defined in the discovery_protection_kind domain-level rule.

TRUE or FALSE

enable_liveliness_protection

Determines if liveliness updates related to Endpoints from this Topic will be sent with the level of security defined in the liveliness_protection_kind domain-level rule.

TRUE or FALSE

enable_read_access_control

Determines if endpoint-level permissions configured in the Permissions File are enforced for local and remote DataReaders.

TRUE or FALSE

enable_write_access_control

Determines if endpoint-level permissions configured in the Permissions File are enforced for local and remote DataWriters.

TRUE or FALSE

metadata_protection_kind

Configures the Submessage Protection, determining what level of protection is applied to RTPS submessages from Endpoints of the associated Topic.

ENCRYPT, ENCRYPT_WITH_ORIGIN_AUTHENTICATION, SIGN, SIGN_WITH_ORIGIN_AUTHENTICATION, NONE

data_protection_kind

Configures the Serialized Data Protection, determining what level of protection is applied to the serialized payload from DataWriters of the associated Topic.

ENCRYPT, SIGN, NONE

1

A system may allow unauthenticated participants as a way of combining older, unsecured applications with newer secure applications (not recommended, see Using Separate Domains for Secure and Unsecure Participants in the Security Plugins User’s Manual).

5.2. Composing a Governance File with the Security Requirements

As the DDS Security expert at Patient Monitoring Innovations (PMI), you are going to specify the security requirements of your system in a file called pmiGovernance.xml.

Create pmiGovernance.xml in the xml directory (along with the XML files we copied from the Connext DDS examples) and add the following content:

Listing 5.1 Sample Governance File that applies to all the Domains. Different Topics will have a different kind of protection.
<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://community.rti.com/schema/6.1.0/dds_security_governance.xsd">
  <!-- Rules affecting different domains are defined under this tag -->
  <domain_access_rules>
    <domain_rule>
      <!-- 1. This determines when to apply this rule. In this case, any domain -->
      <domains>
        <id_range>
          <min>0</min>
        </id_range>
      </domains>

      <!-- 2. The following fields determine behavior of
       DomainParticipants matching this rule -->
      <allow_unauthenticated_participants>TRUE</allow_unauthenticated_participants>
      <enable_join_access_control>FALSE</enable_join_access_control>
      <discovery_protection_kind>ENCRYPT</discovery_protection_kind>
      <liveliness_protection_kind>ENCRYPT</liveliness_protection_kind>
      <rtps_protection_kind>NONE</rtps_protection_kind>

      <!-- 3. Rules affecting topics are defined under this tag -->
      <topic_access_rules>
        <!-- 3.1 Let's have a rule for all topics -->
        <topic_rule>
          <!-- This determines when to apply the rule -->
          <topic_expression>*</topic_expression>

          <!-- The following fields determine the behavior of
           topics/endpoints matching this rule -->
          <enable_discovery_protection>FALSE</enable_discovery_protection>
          <enable_liveliness_protection>FALSE</enable_liveliness_protection>
          <enable_read_access_control>FALSE</enable_read_access_control>
          <enable_write_access_control>FALSE</enable_write_access_control>
          <metadata_protection_kind>NONE</metadata_protection_kind>
          <data_protection_kind>ENCRYPT</data_protection_kind>
        </topic_rule>

        <!-- 3.2 Later we will define other topic rules for specific topics -->

      </topic_access_rules>
    </domain_rule>
  </domain_access_rules>
</dds>

Note: The following references to (1), (2), etc. correspond to comments in the above XML.

This Governance File defines just one configuration, to be applied to any Domain in the system (1). Consequently, all the Domains and Topics in the system are protected in the same way. In particular, the following rules are defined (2):

Domain rule (domain_rule)

Value

Security implications

allow_unauthenticated_participants

TRUE

Non-authenticated participants are allowed to publish/subscribe unprotected Topics

enable_join_access_control

FALSE

Remote participant-level permissions are not checked

discovery_protection_kind

ENCRYPT

Endpoint Discovery will be protected with encryption for Topics setting enable_discovery_protection to TRUE 2

liveliness_protection_kind

ENCRYPT

Liveliness assertions will be protected with encryption for Topics setting enable_liveliness_assertion to TRUE 3

rtps_protection_kind

NONE

RTPS messages are sent without any additional protection (required to allow unauthenticated participants)

Then we can define different levels of protection depending on the Topic to protect (3). This Governance specifies a single rule that applies to every Topic and protects the user’s data with encryption (3.1). We will define the protection of the PatientMonitoring Topic (3.2) as part of a later exercise.

2

Enabling Discovery Protection has further implications, as described in discovery_protection_kind (domain_rule).

3

Enabling Liveliness Protection has further implications, as described in discovery_protection_kind (domain_rule).

5.3. Signing the Governance File

As mentioned in Securing a DDS Domain, both Governance and Permissions Files must be signed by the Permissions CA. This way, all DomainParticipants trusting that Permissions CA can make sure that the Governance File was not forged by an attacker.

We will use the provided Permissions CA’s certificate and key to sign the Governance File that we composed. 4

Run the command below to create the signed Governance File (with PKCS#7 format) named xml/signed/signed_pmiGovernance.p7s:

$ openssl smime -sign -in xml/pmiGovernance.xml -text -out xml/signed/signed_pmiGovernance.p7s -signer cert/ecdsa01/ca/ecdsa01RootCaCert.pem -inkey cert/ecdsa01/ca/private/ecdsa01RootCaKey.pem
$ openssl smime -sign -in xml/pmiGovernance.xml -text -out xml/signed/signed_pmiGovernance.p7s -signer cert/ecdsa01/ca/ecdsa01RootCaCert.pem -inkey cert/ecdsa01/ca/private/ecdsa01RootCaKey.pem
> openssl smime -sign -in xml\pmiGovernance.xml -text -out xml\signed\signed_pmiGovernance.p7s -signer cert\ecdsa01\ca\ecdsa01RootCaCert.pem -inkey cert\ecdsa01\ca\private\ecdsa01RootCaKey.pem
4

In this example, we have control of the Permissions CA. This is not always the case and we may be required to send the Governance File to an external entity to get it signed.

5.4. Updating the QoS Profiles in Your Project

Now we need to update USER_QOS_PROFILES.xml to make your DomainParticipants load the new Governance File. Replace the value of the dds.sec.access.governance property as follows:

...
<!-- Signed Governance and Permissions Files -->
<element>
    <name>dds.sec.access.governance</name>
    <value>file:./xml/signed/signed_pmiGovernance.p7s</value>
</element>
...

Here, the file: prefix means that the signed Governance File will be loaded from the specified path in the file system. Note that the path is relative to the working directory from which you run your application (unless you specify an absolute path).

Another option is to set the value of the dds.sec.access.governance property to the contents of the Governance File. You can do that by using the data:, prefix. This is useful when your application does not have access to a file system. For details, see DDS Security Properties for Configuring Access Control in the RTI Security Plugins User’s Manual.

5.5. Checking that the Specified Security Rules Are Applied

It’s time to see the changes in your security requirements! We will start by verifying that your DomainParticipants can communicate when they load the new Governance File.

5.5.1. Verifying Communication

  1. Run your publisher and subscriber as explained in Running the Applications.

    Note that building the applications is not required, but you still may have to set up your environment.

  2. You should see the message “Received data” on the subscriber side, which indicates that it received samples from the publisher.

    Publisher:

    $ ./objs/<architecture>/PatientMonitoring_publisher
    Writing PatientMonitoring, count 0
    Writing PatientMonitoring, count 1
    Writing PatientMonitoring, count 2
    Writing PatientMonitoring, count 3
    

    Subscriber:

    $ ./objs/<architecture>/PatientMonitoring_subscriber
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    

    Publisher:

    $ ./objs/<architecture>/PatientMonitoring_publisher
    Writing PatientMonitoring, count 0
    Writing PatientMonitoring, count 1
    Writing PatientMonitoring, count 2
    Writing PatientMonitoring, count 3
    

    Subscriber:

    $ ./objs/<architecture>/PatientMonitoring_subscriber
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    

    Publisher:

    > objs\<architecture>\PatientMonitoring_publisher.exe
    Writing PatientMonitoring, count 0
    Writing PatientMonitoring, count 1
    Writing PatientMonitoring, count 2
    Writing PatientMonitoring, count 3
    

    Subscriber:

    > objs\<architecture>\PatientMonitoring_subscriber.exe
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    PatientMonitoring subscriber sleeping up to 1 sec...
    [patient_condition: ]
    PatientMonitoring subscriber sleeping up to 1 sec...
    

5.5.2. Checking the New Security Rules

So far, your Governance File protects the privacy of the user’s data by encrypting the messages’ payload. However, it does not protect discovery data, allowing unauthenticated participants to receive this information. To verify that these rules are applied, we’ll try to subscribe to the PatientMonitoring Topic with RTI Administration Console.

  1. Open Administration Console and join Domain 0.

    (For details on using Administration Console, see Viewing Your Data, in Introduction to Publish/Subscribe.)

    Your secure participants should show up in the DDS Logical View window.

  2. Right-click on the Example PatientMonitoring Topic and select Subscribe….

  3. A dialog will prompt you to select the data type; click OK.

  4. Go to the Data Visualization perspective — by default, a dialog will give you the option to switch perspectives.

  5. Notice that Administration Console’s subscriber is unable to receive any data samples, while your secure subscriber is receiving them.

At this point, you can be sure 5 that your applications are using the security rules you have defined. Congratulations!

5

In Hands-On 5: Checking that Your DDS Traffic Is Protected we will use Wireshark to verify that the messages from the publisher application are encrypted on the network.

5.6. Further Exercises

The Governance File we defined allows unauthenticated participants to join the Secure Domains and to receive discovery data. This may be acceptable for some Topics or some systems. However, you may have more restrictive security requirements and want to prevent unauthenticated participants from communicating at all. Perhaps your security requirements may vary from one Topic to another. We will address these two issues in the following exercises.

Note

Defining the security requirements for a real system is not a trivial task. If you plan to deploy a secure system, your organization will need an in-house security expert to define the security requirements your system needs.

5.6.1. Protecting the Domain

Now, we want to disallow unauthenticated participants from performing any kind of communication in your Secure Domains.

To do so, modify your Governance File to meet the following domain-level rules:

Domain rule (domain_rule)

Value

Security implications

allow_unauthenticated_participants

FALSE

Only authenticated participants are allowed in the system

enable_join_access_control

TRUE

Permissions are checked for any discovered DomainParticipant

rtps_protection_kind

SIGN

All RTPS messages in the system are signed

Make sure the Permissions CA signs the modified Governance File (see Signing the Governance File); otherwise the changes will not be applied.

5.6.2. Adding a Topic Rule for the PatientMonitoring Topic

Your Governance may define different levels of protection, depending on the Topic to be protected.

Write a second Topic rule (topic_rule) to protect the Example PatientMonitoring Topic as follows:

Topic rule (topic_rule)

Value

Security implications

enable_discovery_protection

TRUE

Endpoint discovery data is protected (encrypted, as specified by discovery_protection_kind)

enable_liveliness_protection

TRUE

Liveliness assertions are protected 6 (encrypted, as specified by liveliness_protection_kind)

enable_read_access_control

TRUE

Enforce local endpoint-level permissions on locally created DataReaders; enforce remote endpoint-level permissions on remotely discovered DataReaders

enable_write_access_control

TRUE

Enforce local endpoint-level permissions on locally created DataWriters; enforce remote endpoint-level permissions on remotely discovered DataWriters

metadata_protection_kind

ENCRYPT

DataWriters’ and DataReaders’s outgoing submessages are encrypted 7

data_protection_kind

ENCRYPT

Payloads are encrypted

Make sure the Permissions CA signs the modified Governance File (see Signing the Governance File); otherwise the changes will not be applied.

After applying this configuration, only authenticated and authorized participants will be allowed to join the system. Since RTPS messages are signed, only authenticated and authorized participants will be allowed to write messages to the system. Also, since PatientMonitoring updates are sensitive, they are exchanged encrypted, so an eavesdropper will not be able to have access to that data.

6

The value of this attribute matters only if the DataWriter’s LIVELINESS QosPolicy is AUTOMATIC or MANUAL_BY_PARTICIPANT. See enable_liveliness_protection (topic_rule) in the Security Plugins User’s Manual.

7

These submessages include, but are not limited to, DATA, HEARTBEAT, ACKNACK, and GAP. For more information, see Submessage Protection in the RTI Security Plugins User’s Manual.

8

In the license-managed version (with “lm” in the bundle name), OpenSSL is installed automatically when you install the Connext DDS host bundle. After installation, OpenSSL will be in <installdir>/third_party/openssl-<version>.

5.7. Troubleshooting

  • When I run openssl smime, I get this error:

    WARNING: can't open config file: <default openssl built-in path>/openssl.cnf
    

    Set the environment variable OPENSSL_CONF to ./cert/openssl.cnf.