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 Document. We will sign this Governance Document with the provided Permissions CA. Lastly, we will tell your secure participants where to find the new Governance Document 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. With that said, we recommend using OpenSSL to make sure that the certificates are in the right format.

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 Document, which defines the security rules that every DomainParticipant in your Secure Domain needs to follow. We will now focus on writing a Governance Document to specify your project’s security requirements.

Governance Documents 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 Document 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`
`rtps_preshared_secret_protection_kind`	Determines how to protect RTPS bootstrapping messages. Read section Domain-Level Rules in the Security Plugins User’s Manual for more information.	`ENCRYPT`, `SIGN`, `NONE`
`allowed_security_algorithms`	Determines the cryptographic algorithms that are allowed in your system.	The values are a list of algorithms that depend on whether they are used for `digital_signature`, `digital_signature_identity_trust_chain`, `key_establishment`, or `symmetric_cipher`. For more information read section Domain-Level Rules in the Security Plugins User’s Manual.

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 Document are enforced for local and remote DataReaders.	`TRUE` or `FALSE`
`enable_write_access_control`	Determines if endpoint-level permissions configured in the Permissions Document 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 Document 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 examples) and add the following content:

Listing 5.1 Sample Governance Document 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.1/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 Document 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 Document

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

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

Run the command below to create the signed Governance Document (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 Document 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 Document. Replace the value of the dds.sec.access.governance property as follows:

...
<!-- Signed Governance and Permissions Documents -->
<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 Document 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 Document. 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 Document.

5.5.1. Verifying Communication

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.

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
No data after 1 second
Received data

   patient_condition: ""
No data after 1 second
Received data

   patient_condition: ""

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
No data after 1 second
Received data

   patient_condition: ""
No data after 1 second
Received data

   patient_condition: ""

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
No data after 1 second
Received data

   patient_condition: ""
No data after 1 second
Received data

   patient_condition: ""

5.5.2. Checking the New Security Rules

So far, your Governance Document 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.

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.
Right-click on the Example PatientMonitoring Topic and select Subscribe….
A dialog will prompt you to select the data type; click OK.
Go to the Data Visualization perspective — by default, a dialog will give you the option to switch perspectives.
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 Document 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 Document 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 Document (see Signing the Governance Document); 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.

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

The Governance Document is parsed from top to bottom (for more information, see How the Governance Document is Interpreted in the Security Plugins User’s Manual). Therefore, you must add your new topic_rule before the wildcard rule that matches all topics (the one with a topic_expression value of *).

After applying the configuration, PatientMonitoring updates are exchanged encrypted, so an eavesdropper will not be able to have access to that data. Make sure the Permissions CA signs the modified Governance Document (see Signing the Governance Document); otherwise the changes will not be applied.

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 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.