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’ll use the OpenSSL CLI to perform the security operations in the generation of the security artifacts. Note that the Security Plugins do not depend on OpenSSL to generate these artifacts; you can choose another security toolkit.

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>`	The OMG DDS Security specification defines a set of secure endpoint discovery builtin Topics. This rule determines what level of protection is applied to those builtin Topics.	`ENCRYPT`, `ENCRYPT_WITH_ORIGIN_AUTHENTICATION`, `SIGN`, `SIGN_WITH_ORIGIN_AUTHENTICATION`, `NONE`
`<liveliness_protection_kind>`	The OMG DDS Security specification defines a set of secure participant liveliness builtin Topics. This rule determines what level of protection is applied to those builtin Topics.	`ENCRYPT`, `ENCRYPT_WITH_ORIGIN_AUTHENTICATION`, `SIGN`, `SIGN_WITH_ORIGIN_AUTHENTICATION`, `NONE`
`<rtps_protection_kind>`	Determines 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 domain-level `<discovery_protection_kind>` 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 domain-level `<liveliness_protection_kind>` rule.	`true` or `false`
`<enable_read_access_control>`	Determines if topic-level permissions configured in the Permissions file are enforced for local and remote readers.	`true` or `false`
`<enable_write_access_control>`	Determines if topic-level permissions configured in the Permissions file are enforced for local and remote writers.	`true` or `false`
`<metadata_protection_kind>`	Determines 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>`	Determines what level of protection is applied to the serialized payload from endpoints of the associated Topic.	`ENCRYPT`, `SIGN`, `NONE`

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.0.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 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 DomainParticipant permissions are not checked
`<discovery_protection_kind>`	`ENCRYPT`	Endpoint discovery will be protected with encryption for Topics enabling discovery protection
`<liveliness_protection_kind>`	`ENCRYPT`	Liveliness assertions will be protected with encryption for Topics enabling liveliness assertion
`<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.

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. [2]

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/cacertECdsa.pem -inkey cert/cakeyECdsa.pem

$ openssl smime -sign -in xml/pmiGovernance.xml -text -out xml/signed/signed_pmiGovernance.p7s -signer cert/cacertECdsa.pem -inkey cert/cakeyECdsa.pem

> openssl smime -sign -in xml\pmiGovernance.xml -text -out xml\signed\signed_pmiGovernance.p7s -signer cert\cacertECdsa.pem -inkey cert\cakeyECdsa.pem

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¶

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

Subscriber:

$ ./objs/<architecture>/PatientMonitoring_subscriber

PatientMonitoring subscriber sleeping for 4 sec...
[patientCondition: ]
PatientMonitoring subscriber sleeping for 4 sec...
[patientCondition: ]
PatientMonitoring subscriber sleeping for 4 sec...

Publisher:

$ ./objs/<architecture>/PatientMonitoring_publisher

Writing PatientMonitoring, count 0
Writing PatientMonitoring, count 1
Writing PatientMonitoring, count 2

Subscriber:

$ ./objs/<architecture>/PatientMonitoring_subscriber

PatientMonitoring subscriber sleeping for 4 sec...
[patientCondition: ]
PatientMonitoring subscriber sleeping for 4 sec...
[patientCondition: ]
PatientMonitoring subscriber sleeping for 4 sec...

Publisher:

> objs\<architecture>\PatientMonitoring_publisher.exe

Writing PatientMonitoring, count 0
Writing PatientMonitoring, count 1
Writing PatientMonitoring, count 2

Subscriber:

> objs\<architecture>\PatientMonitoring_subscriber.exe

PatientMonitoring subscriber sleeping for 4 sec...
[patientCondition: ]
PatientMonitoring subscriber sleeping for 4 sec...
[patientCondition: ]
PatientMonitoring subscriber sleeping for 4 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 Admin Console.

Open Admin Console and join domain 0.

(For details on using Admin 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 Admin Console’s subscriber is unable to receive any data samples, while your secure subscriber is receiving them.

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

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 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 (encrypted, as specified by `<liveliness_protection_kind>`)
`<enable_read_access_control>`	`true`	Enforce local permissions on locally created DataReaders; enforce remote permissions on remotely discovered DataReaders
`<enable_write_access_control>`	`true`	Enforce local permissions on locally created DataWriters; enforce remote permissions on remotely discovered DataWriters
`<metadata_protection_kind>`	`ENCRYPT`	DataWriters’ and DataReaders’ outgoing submessages are encrypted [3]
`<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.

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.

[1]	A system may allow unauthenticated participants as a way of combining older, unsecured applications with newer secure applications (the recommended alternative is to use RTI Routing Service).

[2]	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.

[3]	These submessages include, but are not limited to, `DATA`, `HEARTBEAT`, `ACKNACK`, and `GAP`. For more information, see `<topic_rule>` in the Related Governance Attributes for Cryptography, in the RTI Security Plugins User’s Manual.