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 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:
Rule |
Description |
Possible values |
---|---|---|
|
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] |
|
|
Determines if the participant-level permissions configured in the Permissions Document are enforced for remote participants. |
|
|
Configures the Discovery Protection, determining what level of protection is applied to the Builtin Secure Discovery Topics. |
|
|
Configures the Liveliness Protection, determining what level of protection is applied to the Builtin Secure Liveliness Topic. |
|
|
Configures the RTPS Protection, determining what level of protection is applied to RTPS messages. |
|
|
Determines how to protect RTPS bootstrapping messages. Read section Domain-Level Rules in the RTI Security Plugins User’s Manual for more information. |
|
|
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 |
Rule |
Description |
Possible values |
---|---|---|
|
Determines if discovery information updates related to Endpoints
from this Topic will be sent with the level of security defined
in the |
|
|
Determines if liveliness updates related to Endpoints from this
Topic will be sent with the level of security defined in the
|
|
|
Determines if endpoint-level permissions configured in the Permissions Document are enforced for local and remote DataReaders. |
|
|
Determines if endpoint-level permissions configured in the Permissions Document are enforced for local and remote DataWriters. |
|
|
Configures the Submessage Protection, determining what level of protection is applied to RTPS submessages from Endpoints of the associated Topic. |
|
|
Configures the Serialized Data Protection, determining what level of protection is applied to the serialized payload from DataWriters of the associated Topic. |
|
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:
<?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.3.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 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 ( |
Value |
Security implications |
---|---|---|
|
|
Non-authenticated participants are allowed to publish/subscribe unprotected Topics |
|
|
Remote participant-level permissions are not checked |
|
|
Endpoint Discovery will be protected with encryption for Topics
setting |
|
|
Liveliness assertions will be protected with encryption for Topics
setting |
|
|
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.
Enabling Discovery Protection has further implications, as described in discovery_protection_kind (domain_rule).
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
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 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 [5] that your applications are using the security rules you have defined. Congratulations!
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 ( |
Value |
Security implications |
---|---|---|
|
|
Only authenticated participants are allowed in the system |
|
|
Permissions are checked for any discovered DomainParticipant |
|
|
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 ( |
Value |
Security implications |
---|---|---|
|
|
Endpoint discovery data is protected (encrypted, as
specified by |
|
|
Liveliness assertions are protected [6] (encrypted, as
specified by |
|
|
Enforce local endpoint-level permissions on locally created DataReaders; enforce remote endpoint-level permissions on remotely discovered DataReaders |
|
|
Enforce local endpoint-level permissions on locally created DataWriters; enforce remote endpoint-level permissions on remotely discovered DataWriters |
|
|
DataWriters’ and DataReaders’s outgoing submessages are encrypted [7] |
|
|
Payloads are encrypted |
The Governance Document is parsed from top to bottom (for more information, see
How the Governance Document is Interpreted
in the RTI 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.
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 RTI Security Plugins User’s Manual.
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.
In the evaluation or LM version (with
“eval
” or “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 builtin path>/openssl.cnf
Set the environment variable
OPENSSL_CONF
to./cert/openssl.cnf
.