You're reading the documentation for a development version. For the latest released version, please have a look at Jazzy.
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 ROS 2 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.
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
brew install openssl
You will need to have OpenSSL on your library path to run DDS-Security demos.
Run the following command, and consider adding to your ~/.bash_profile:
export DYLD_LIBRARY_PATH=`brew --prefix openssl`/lib:$DYLD_LIBRARY_PATH
export OPENSSL_ROOT_DIR=`brew --prefix openssl`
If you don’t have OpenSSL installed, please follow these instructions
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.
ROS 2 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_demomkdir ~/sros2_demomd C:\dev\ros2\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
cd ~/sros2_demo
ros2 security create_keystore demo_keystore
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
ros2 security create_enclave demo_keystore /talker_listener/talker
ros2 security create_enclave demo_keystore /talker_listener/listener
ros2 security create_enclave demo_keystore /talker_listener/talker
ros2 security create_enclave demo_keystore /talker_listener/listener
If unable to write 'random state' appears then set the environment variable RANDFILE.
set RANDFILE=C:\dev\ros2\sros2_demo\.rnd
Then re-run the commands above.
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
export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore
export ROS_SECURITY_ENABLE=true
export ROS_SECURITY_STRATEGY=Enforce
set ROS_SECURITY_KEYSTORE=%cd%/demo_keystore
set ROS_SECURITY_ENABLE=true
set 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?
The listener launches but does not receive any messages. All traffic is encrypted, and without security enabled the listener does not receive anything.
Stop the listener, set the environment variable ROS_SECURITY_ENABLE to true and start the listener again.
What results do you expect this time?
The listener still launches but does not receive messages. Although security has now been enabled, it is not been configured properly since ROS is unable to locate the key files. The listener launches, but in non-secure mode since security is not enforced, which means that although the properly configured talker is sending encrypted messages, this listener is unable to decrypt them.
Stop the listener and set ROS_SECURITY_STRATEGY to Enforce.
What happens now?
The listener fails to launch. Security has been enabled and is being enforced. Since it still is not properly configured, an error is thrown rather than launching in non-secure mode.
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!