3.12. Secure communications with ROS 2 Router

3.12.1. Background

eProsima ROS 2 Router, a.k.a DDS Router, is a cross-platform non-graphical application developed by eProsima that allows users to connect physically or virtually separated DDS networks.

Configuring the ROS 2 Router to have one or many interfaces for each isolated network will allow to establish the communication and data transmission between the nodes. In compliance with the DDS Security specification, Fast DDS provides secure communication by implementing pluggable security at three levels:

  • Authentication (DDS:Auth:PKI-DH plugin): provides the mechanisms and operations required for nodes (DomainParticipants) authentication at discovery.

  • Access control (DDS:Access:Permissions plugin): after a remote node (DomainParticipant) is authenticated, its permissions are validated and enforced.

  • Data encryption (DDS:Crypto:AES-GCM-GMAC): provides the tools and operations required to support encryption and decryption, digests computation, message authentication codes computation and verification, key generation, and key exchange for nodes (DomainParticipants), publishers (DataWriters) and subscriptions (DataReaders).

Fast DDS allows security plugins to be activated through the DomainParticipantQos properties.

This tutorial will show how to configure the ROS 2 Router via XML profiles to setup a secure communication. Specifically, the configured ROS 2 Router will allow the communication between two distinct domains, a capability that would be unattainable in the absence of the Router. The chosen security configuration in this case will be related to authentication, access control, and data encryption.

To know more about Security plugins, please refer to Fast DDS Security Documentation.

../../../../_images/secure_router.png

This tutorial will use the demo_nodes_cpp ROS 2 package, available in the Vulcanexus Desktop distribution. Two ROS 2 nodes, a talker and a listener, will be launched on different ROS 2 Domains, so that they cannot communicate between each other in a first instance. Then, the ROS 2 Router will be used as a bridge between the two Domains, checking the security features between the Participants and allowing the listener to receive the messages from the talker.

3.12.2. Prerequisites

To proceed, please install Vulcanexus with one of the following installation methods:

3.12.3. Preparing all security certificates

Participants security can only be configured by XML, following the instructions of Fast DDS Security Documentation to fulfill the pertinent requirements of the chosen security mechanisms. To generate the security certificates needed for both talker and listener nodes and both ROS 2 Router participants please follow the Setting up security ROS 2 tutorial. Additionally to the steps followed in the tutorial, when generating keys and certificates for the talker and listener nodes (Section 3), generate also their corresponding security files for both ROS 2 Router participants as follows:

ros2 security create_enclave demo_keystore /ros2_router/participant0
ros2 security create_enclave demo_keystore /ros2_router/participant1

3.12.3.1. Configuring governance.xml and permissions.xml

By default, the create_enclave feature configures security for ROS Domain 0. We can set up another domain or even a range of domains applying the following change in <domain></domain> in the governance.xml and in the permissions.xml files.

<domains>
    <id>(new domain)</id>
</domains>

For our specific case, we will modify the corresponding listener and ROS 2 Router participant in domain 1 permissions.xml files to apply to ROS 2 Domain 1. In order to do so, please find the <domain></domain> section in

  • ~/sros2_demo/demo_keystore/enclaves/talker_listener/listener/permissions.xml, and

  • ~/sros2_demo/demo_keystore/enclaves/ros2_router/participant1/permissions.xml

files and replace it by:

<domains>
    <id>1</id>
</domains>

We also need to update the governance.xml file (~/sros2_demo/demo_keystore/enclaves/governance.xml) that applies to all entities in our demo to include both ROS 2 Domains 0 and 1.

<domains>
    <id_range>
        <min>0</min>
        <max>1</max>
    </id_range>
</domains>

Note

Make sure that you have applied the changes in all <domain></domain> sections, as some files have it more than once.

3.12.3.2. Signing governance.xml and permissions.xml

Once applied the changes, the updated files must be signed with the permission CA certificate.

  • Sign permissions files

    openssl smime -sign -text \
    -in ~/sros2_demo/demo_keystore/enclaves/talker_listener/listener/permissions.xml \
    -out ~/sros2_demo/demo_keystore/enclaves/talker_listener/listener/permissions.p7s \
    -signer ~/sros2_demo/demo_keystore/public/permissions_ca.cert.pem \
    -inkey ~/sros2_demo/demo_keystore/private/permissions_ca.key.pem

openssl smime -sign -text \
    -in ~/sros2_demo/demo_keystore/enclaves/ros2_router/participant1/permissions.xml \
    -out ~/sros2_demo/demo_keystore/enclaves/ros2_router/participant1/permissions.p7s \
    -signer ~/sros2_demo/demo_keystore/public/permissions_ca.cert.pem \
    -inkey ~/sros2_demo/demo_keystore/private/permissions_ca.key.pem

  • Sign governance file

    openssl smime -sign -text -in ~/sros2_demo/demo_keystore/enclaves/governance.xml \
    -text -out ~/sros2_demo/demo_keystore/enclaves/governance.p7s \
    -signer ~/sros2_demo/demo_keystore/public/permissions_ca.cert.pem \
    -inkey ~/sros2_demo/demo_keystore/private/permissions_ca.key.pem

3.12.4. Configuration of ROS 2 Router

The following YAML configuration file configures a ROS 2 Router to create two participants in ROS 2 Domains 0 and 1 so that it creates a bridge between the isolated networks enabling communication between them.

##################################
# CONFIGURATION VERSION
version: v3.1

##################################
# XML CONFIGURATION FILE
xml:
  files:
    - ./sros2_demo/ros2_router/secure_domain_0.xml
    - ./sros2_demo/ros2_router/secure_domain_1.xml

##################################
# PARTICIPANTS
participants:

  - name: ROS_2_Domain_0
    kind: xml
    profile: participant_domain_0

  - name: ROS_2_Domain_1
    kind: xml
    profile: participant_domain_1

Please, save this file in ~/sros_demo/ros2_router directory.

3.12.4.1. ROS 2 Router Participants Configuration

A ROS 2 Router Participant is a ROS 2 Router entity that works as an interface between a network and the core of the router. Participants security can only be configured via XML profiles, following the instructions of Fast DDS Security Documentation to fulfill the pertinent requirements of the chosen security mechanisms.

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="participant_domain_0">
        <domainId>0</domainId>
        <rtps>
            <propertiesPolicy>
                <properties>
                    <!-- Activate DDS:Auth:PKI-DH plugin -->
                    <property>
                        <name>dds.sec.auth.plugin</name>
                        <value>builtin.PKI-DH</value>
                    </property>
                    <!-- Configure DDS:Auth:PKI-DH plugin -->
                    <property>
                        <name>dds.sec.auth.builtin.PKI-DH.identity_ca</name>
                        <value>file://./sros2_demo/demo_keystore/enclaves/ros2_router/participant0/identity_ca.cert.pem</value>
                    </property>
                    <property>
                        <name>dds.sec.auth.builtin.PKI-DH.identity_certificate</name>
                        <value>file://./sros2_demo/demo_keystore/enclaves/ros2_router/participant0/cert.pem</value>
                    </property>
                    <property>
                        <name>dds.sec.auth.builtin.PKI-DH.private_key</name>
                        <value>file://./sros2_demo/demo_keystore/enclaves/ros2_router/participant0/key.pem</value>
                    </property>
                    <!-- DDS:Access:Permissions plugin -->
                    <property>
                        <name>dds.sec.access.plugin</name>
                        <value>builtin.Access-Permissions</value>
                    </property>
                    <property>
                        <name>dds.sec.access.builtin.Access-Permissions.permissions_ca</name>
                        <value>file://./sros2_demo/demo_keystore/enclaves/ros2_router/participant0/permissions_ca.cert.pem</value>
                    </property>
                    <property>
                        <name>dds.sec.access.builtin.Access-Permissions.governance</name>
                        <value>file://./sros2_demo/demo_keystore/enclaves/ros2_router/participant0/governance.p7s</value>
                    </property>
                    <property>
                        <name>dds.sec.access.builtin.Access-Permissions.permissions</name>
                        <value>file://./sros2_demo/demo_keystore/enclaves/ros2_router/participant0/permissions.p7s</value>
                    </property>
                    <!-- Activate DDS:Crypto:AES-GCM-GMAC plugin -->
                    <property>
                        <name>dds.sec.crypto.plugin</name>
                        <value>builtin.AES-GCM-GMAC</value>
                    </property>
                </properties>
            </propertiesPolicy>
        </rtps>
    </participant>
</profiles>

Please add these files (secure_domain_0.xml and secure_domain_1.xml) to the current workspace so they can be referenced when running the ROS 2 Router. At this point we have a workspace structure as follows:

These XML snippets configure security settings for two participants in the Fast DDS middleware. They activate the PKI-DH plugin, specifying the paths to the participants’ identities certificates, identity CA certificate, and private keys for authentication through the DDS:Auth:PKI-DH plugin. Additionally, they enable access control through the DDS:Access:Permissions plugin, defining paths to the permissions CA certificate, governance files, and permissions files. The configuration also includes the activation of the DDS:Crypto:AES-GCM-GMAC plugin for data encryption, enhancing communication security.

3.12.5. Running the tutorial

Once all the files needed have been generated, the workspace sros2_demo generated in the previous steps will have the following structure:

~/sros2_demo
├── ros2_router
│   ├── secure_domain_0.xml
│   ├── secure_domain_1.xml
│   ├── ddsrouter.yaml
└── demo_keystore
    ├── enclaves
    │   ├── ros2_router
    │   ├── talker_listener
    │   ├── governance.p7s
    │   ├── governance.xml
    ├── private
    └── public

3.12.5.1. Running ROS2 nodes with security

Now that everything is prepared, we can launch the demo nodes with security. For this, open two different terminals and setup the Vulcanexus environment and the corresponding environment variables for configuring ROS 2 secure communications.

source /opt/vulcanexus/iron/setup.bash
export ROS_SECURITY_KEYSTORE=<absolute/path/to/sros2_demo>/sros2_demo/demo_keystore
export ROS_SECURITY_ENABLE=true
export ROS_SECURITY_STRATEGY=Enforce

Open the first terminal to run a ROS 2 demo_nodes_cpp talker node in domain 0 with its corresponding security configuration:

ROS_DOMAIN_ID=0 ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker

And the same with the listener in domain 1 on a second terminal:

ROS_DOMAIN_ID=1 ros2 run demo_nodes_cpp listener --ros-args --enclave /talker_listener/listener

At this point, the listener should not receive any data from the talker since they are in different domains. To connect them, we will use the ROS 2 Router.

3.12.5.2. Running DDS Router

Open a third terminal and source the Vulcanexus environment:

source /opt/vulcanexus/iron/setup.bash

Then run the ROS 2 Router with the yaml configuration file created before.

ddsrouter --config-path ~/sros2_demo/ros2_router/ddsrouter.yaml

The output from the ROS 2 Router should be something like:

Starting DDS Router Tool execution.
DDS Router running.

If so, the ROS 2 Router has started correctly and it is currently running. Once the ROS 2 Router is running, it will forward the messages from the talker on domain 0 to the listener on domain 1. In order to close the execution, press ^C or send a signal (SIGINT 2 or SIGTERM 15) to stop it.

To make sure security is working properly try running again the talker and listener ROS 2 nodes the security configuration:

ROS_DOMAIN_ID=0 ros2 run demo_nodes_cpp talker

ROS_DOMAIN_ID=1 ros2 run demo_nodes_cpp listener

This way the ROS 2 Router will not receive any data from the talker and therefore neither will the listener.