.. redirect-from:: Tutorials/Security/Introducing-ros2-security .. _sros2: .. _ROS-2-Security-Tutorials: Setting up security =================== **Goal:** Set up security with ``sros2``. **Tutorial level:** Advanced **Time:** 15 minutes .. contents:: Contents :depth: 2 :local: 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 :doc:`ROS 2 Installation Guide <../../../Installation>` and the :doc:`configuration guide <../../Beginner-CLI-Tools/Configuring-ROS2-Environment>`. 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: .. tabs:: .. group-tab:: Linux .. code-block:: console $ sudo apt update $ sudo apt install libssl-dev .. group-tab:: MacOS .. code-block:: console $ 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``: .. code-block:: console $ export DYLD_LIBRARY_PATH=`brew --prefix openssl`/lib:$DYLD_LIBRARY_PATH $ export OPENSSL_ROOT_DIR=`brew --prefix openssl` .. group-tab:: Windows If you don't have OpenSSL installed, please follow :ref:`these instructions ` Fast DDS requires an additional CMake flag to build the security plugins, so the colcon invocation needs to be modified to pass: .. code-block:: console $ colcon build --symlink-install --cmake-args -DSECURITY=ON --packages-select fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp rmw_fastrtps_shared_cpp Selecting an alternate middleware ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you choose not to use the default middleware implementation, be sure to :doc:`change your RMW implementation <../../../Installation/RMW-Implementations/>` before proceeding. ROS 2 allows you to change the RMW implementation at runtime. See `how to work with multiple RMW implementations <../../../How-To-Guides/Working-with-multiple-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: .. tabs:: .. group-tab:: Linux .. code-block:: console $ mkdir ~/sros2_demo .. group-tab:: MacOS .. code-block:: console $ mkdir ~/sros2_demo .. group-tab:: Windows .. code-block:: console $ md 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. .. tabs:: .. group-tab:: Linux .. code-block:: console $ cd ~/sros2_demo $ ros2 security create_keystore demo_keystore .. group-tab:: MacOS .. code-block:: console $ cd ~/sros2_demo $ ros2 security create_keystore demo_keystore .. group-tab:: Windows .. code-block:: console $ 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. .. tabs:: .. group-tab:: Linux .. code-block:: console $ ros2 security create_enclave demo_keystore /talker_listener/talker $ ros2 security create_enclave demo_keystore /talker_listener/listener .. group-tab:: MacOS .. code-block:: console $ ros2 security create_enclave demo_keystore /talker_listener/talker $ ros2 security create_enclave demo_keystore /talker_listener/listener .. group-tab:: Windows .. code-block:: console $ 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``. .. code-block:: console $ 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 `_. .. tabs:: .. group-tab:: Linux .. code-block:: console $ export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore $ export ROS_SECURITY_ENABLE=true $ export ROS_SECURITY_STRATEGY=Enforce .. group-tab:: MacOS .. code-block:: console $ export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore $ export ROS_SECURITY_ENABLE=true $ export ROS_SECURITY_STRATEGY=Enforce .. group-tab:: Windows .. code-block:: console $ 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. .. code-block:: console $ 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. .. code-block:: console $ 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 use ``ros2cli`` and answer the questions below. 6) Use ``ros2cli`` with security ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To use ``ros2cli`` to iterate with ROS 2 secured network, you need to provide it with override enclave by ``ROS_SECURITY_ENCLAVE_OVERRIDE`` environmental variable. Open an another terminal and set up the following environmental variables. .. tabs:: .. group-tab:: Linux .. code-block:: console $ export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore $ export ROS_SECURITY_ENABLE=true $ export ROS_SECURITY_STRATEGY=Enforce $ export ROS_SECURITY_ENCLAVE_OVERRIDE=/talker_listener/listener .. group-tab:: MacOS .. code-block:: console $ export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore $ export ROS_SECURITY_ENABLE=true $ export ROS_SECURITY_STRATEGY=Enforce $ export ROS_SECURITY_ENCLAVE_OVERRIDE=/talker_listener/listener .. group-tab:: Windows .. code-block:: console $ set ROS_SECURITY_KEYSTORE=%cd%/demo_keystore $ set ROS_SECURITY_ENABLE=true $ set ROS_SECURITY_STRATEGY=Enforce $ set ROS_SECURITY_ENCLAVE_OVERRIDE=/talker_listener/listener Now you can use ``ros2cli`` to communicate with ROS 2 secured network. .. code-block:: console $ ros2 node list --no-daemon --spin-time 3 [INFO] [1733862009.410918416] [rcl]: Found security directory: /root/ros2_ws/colcon_ws/demo_keystore/enclaves/talker_listener/talker /listener /talker .. code-block:: console $ ros2 topic list --no-daemon --spin-time 3 [INFO] [1733861998.562163611] [rcl]: Found security directory: /root/ros2_ws/colcon_ws/demo_keystore/enclaves/talker_listener/talker /chatter /parameter_events /rosout .. note:: Avoid using ros2 daemon because it may not have security enclaves, and enough time duration should be given for the discovery in ROS 2 secured network. Take the Quiz! -------------- .. tabs:: .. group-tab:: Question 1 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? .. group-tab:: Answer 1 The listener launches but does not receive any messages. All traffic is encrypted, and without security enabled the listener does not receive anything. .. tabs:: .. group-tab:: Question 2 Stop the listener, set the environment variable ``ROS_SECURITY_ENABLE`` to ``true`` and start the listener again. What results do you expect this time? .. group-tab:: Answer 2 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. .. tabs:: .. group-tab:: Question 3 Stop the listener and set ``ROS_SECURITY_STRATEGY`` to ``Enforce``. What happens now? .. group-tab:: Answer 3 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!