You're reading the documentation for a development version. For the latest released version, please have a look at Humble.

Setting up security

Goal: Set up security with sros2.

Tutorial level: Advanced

Time: 15 minutes

Background

The sros2 package provides the tools and instructions to use ROS2 on top of DDS-Security. The security features have been tested across platforms (Linux, macOS, and Windows) as well as across different languages (C++ and Python). The SROS2 has been designed to work with any secure middleware, although not all middleware is open source and support varies depending on the ROS distribution in use. Please reach out to the ROS 2 Security Working Group if you encounter any support issues.

Installation

Typically security is available following installation using the ROS 2 Installation Guide and the configuration guide. However, if you intend to install from source or switch middleware implementations, consider the following caveats:

Installing from source

Before installing from source, you will need to have a recent version openssl (1.0.2g or later) installed:

sudo apt update
sudo apt install libssl-dev

Fast DDS requires an additional CMake flag to build the security plugins, so the colcon invocation needs to be modified to pass:

colcon build --symlink-install --cmake-args -DSECURITY=ON

Selecting an alternate middleware

If you choose not to use the default middleware implementation, be sure to change your DDS implementation before proceeding.

ROS2 allows you to change the DDS implementation at runtime. See how to work with mulitple RMW implementations to explore different middleware implementations.

Note that secure communication between vendors is not supported.

Run the demo

1. Create a folder for the security files

Begin by creating folder to store all the files necessary for this demo:

mkdir ~/sros2_demo

2. Generate a keystore

Use the sros2 utilities to create the keystore. Files in the keystore will be used to enable security for all the participants in the ROS 2 graph.

cd ~/sros2_demo
ros2 security create_keystore demo_keystore

3. Generate keys and certificates

Once the keystore is created, create keys and certificates for each node with security enabled. For our demo, that includes the talker and listener nodes. This command uses the create_enclave feature which is covered in more detail in the next tutorial.

ros2 security create_enclave demo_keystore /talker_listener/talker
ros2 security create_enclave demo_keystore /talker_listener/listener

4. Configure environment variables

Three environment variables allow the middleware to locate encryption materials and enable (and possibly enforce) security. These and other security-related environment variables are described in the ROS 2 DDS-Security Integration design document.

export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore
export ROS_SECURITY_ENABLE=true
export ROS_SECURITY_STRATEGY=Enforce

These variables need to be defined in each terminal used for the demo. For convenience you can add them to your boot environment.

5. Run the talker/listener demo

Begin the demo by launching the talker node.

ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker

In another terminal, do the same to launch the listener node. The environment variables in this terminal must be properly set as described in step 4 above.

ros2 run demo_nodes_py listener --ros-args --enclave /talker_listener/listener

These nodes will be communicating using authentication and encryption! If you look at the packet contents (for example, using tcpdump or Wireshark as covered in another tutorial), you can see that the messages are encrypted.

Note: You can switch between the C++ (demo_nodes_cpp) and Python (demo_nodes_py) packages arbitrarily.

These nodes are able to communicate because we have created the appropriate keys and certificates for them.

Leave both nodes running as you answer the questions below.

Take the Quiz!

Open another terminal session, but do not set the environment variables so that security is not enabled. Start the listener. What do you expect to happen?

Stop the listener, set the environment variable ROS_SECURITY_ENABLE to true and start the listener again. What results do you expect this time?

Stop the listener and set ROS_SECURITY_STRATEGY to Enforce. What happens now?

Learn More!

Are you ready to go further with ROS Security? Take a look at the Secure Turtlebot2 Demo. You’ll find a functioning and complex implementation of ROS 2 security, ready to try out your own custom scenarios. Be sure to create pull requests and issues here so we can continue improving security support in ROS!