Skip to content

add $ Security Webots and Topic-Statics-Tutorial #5358

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 26, 2025
Merged

add $ Security Webots and Topic-Statics-Tutorial #5358

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c632ed0
add $
Nils-ChristianIseke Apr 25, 2025
2488c22
Apply suggestions from code review
christophebedard Apr 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions source/Tutorials/Advanced/Security/Access-Controls.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,12 @@ Modify ``permissions.xml``

Begin by making a backup of your permissions files, and open ``permissions.xml`` for editing:

.. code-block:: bash
.. code-block:: console

cd ~/sros2_demo/demo_keystore/enclaves/talker_listener/talker
mv permissions.p7s permissions.p7s~
mv permissions.xml permissions.xml~
vi permissions.xml
$ cd ~/sros2_demo/demo_keystore/enclaves/talker_listener/talker
$ mv permissions.p7s permissions.p7s~
$ mv permissions.xml permissions.xml~
$ vi permissions.xml

We will be modifying the ``<allow_rule>`` for ``<publish>`` and ``<subscribe>``.
The topics in this XML file use the DDS naming format, not the ROS name.
Expand Down Expand Up @@ -113,9 +113,9 @@ This next command creates the new S/MIME signed policy file ``permissions.p7s``
The file must be signed with the Permissions CA certificate, **which requires access to the Permission CA private key**.
If the private key has been protected, additional steps may be required to unlock and use it according to your security plan.

.. code-block:: bash
.. code-block:: console

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

Expand All @@ -125,15 +125,15 @@ Launch the node

With the updated permissions in place, we can launch the node successfully using the same command used in prior tutorials:

.. code-block:: bash
.. code-block:: console

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

However, attempting to remap the ``chatter`` topic prevents the node from launching (note that this requires the ``ROS_SECURITY_STRATEGY`` set to ``Enforce``).

.. code-block:: bash
.. code-block:: console

ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker \
$ ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker \
--remap chatter:=not_chatter


Expand All @@ -146,39 +146,39 @@ Let's creates a policy for both the ``talker`` and the ``listener`` to only use

Begin by downloading the ``sros2`` repository with the sample policy files:

.. code-block:: bash
.. code-block:: console

git clone https://github.com/ros2/sros2.git /tmp/sros2
$ git clone https://github.com/ros2/sros2.git /tmp/sros2

Then use the ``create_permission`` verb while pointing to the sample policy to generate the XML permission files:

.. code-block:: bash
.. code-block:: console

ros2 security create_permission demo_keystore \
$ ros2 security create_permission demo_keystore \
/talker_listener/talker \
/tmp/sros2/sros2/test/policies/sample.policy.xml
ros2 security create_permission demo_keystore \
$ ros2 security create_permission demo_keystore \
/talker_listener/listener \
/tmp/sros2/sros2/test/policies/sample.policy.xml

These permission files allow nodes to only publish or subscribe to the ``chatter`` topic, and enable communications required for parameters.

In one terminal with security enabled as in previous security tutorials, run the ``talker`` demo program:

.. code-block:: bash
.. code-block:: console

ros2 run demo_nodes_cpp talker --ros-args -e /talker_listener/talker
$ ros2 run demo_nodes_cpp talker --ros-args -e /talker_listener/talker

In another terminal do the same with the ``listener`` program:

.. code-block:: bash
.. code-block:: console

ros2 run demo_nodes_py listener --ros-args -e /talker_listener/listener
$ ros2 run demo_nodes_py listener --ros-args -e /talker_listener/listener

At this point, your ``talker`` and ``listener`` nodes will be communicating securely using explicit access control lists.
However, the following attempt for the ``listener`` node to subscribe to a topic other than ``chatter`` will fail:

.. code-block:: bash
.. code-block:: console

ros2 run demo_nodes_py listener --ros-args --enclave /talker_listener/listener \
$ ros2 run demo_nodes_py listener --ros-args --enclave /talker_listener/listener \
--remap chatter:=not_chatter
53 changes: 26 additions & 27 deletions source/Tutorials/Advanced/Security/Deployment-Guidelines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,28 +99,26 @@ Starting from the image, three containers will be created with the aim of:
In this example, the local host serves as the organization's system.
Let us start by creating a workspace folder:

.. code-block:: bash
.. code-block:: console

mkdir ~/security_gd_tutorial
cd ~/security_gd_tutorial
$ mkdir ~/security_gd_tutorial
$ cd ~/security_gd_tutorial

Generating the Docker Image
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to build a new docker image, a Dockerfile is required.
The one proposed for this tutorial can be retrieved with the following command:
To download the Dockerfile proposed for this tutorial, run:

.. code-block:: bash
.. code-block:: console

# Download the Dockerfile
wget https://raw.githubusercontent.com/ros2/ros2_documentation/{DISTRO}/source/Tutorials/Advanced/Security/resources/deployment_gd/Dockerfile
$ wget https://raw.githubusercontent.com/ros2/ros2_documentation/{DISTRO}/source/Tutorials/Advanced/Security/resources/deployment_gd/Dockerfile

Now, build the docker image with the command:

.. code-block:: bash
.. code-block:: console

# Build the base image
docker build -t ros2_security/deployment_tutorial --build-arg ROS_DISTRO={DISTRO} .
$ docker build -t ros2_security/deployment_tutorial --build-arg ROS_DISTRO={DISTRO} .

Understanding the compose file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -137,20 +135,18 @@ In this tutorial, three services are defined within the configuration:

The compose configuration yaml file can be downloaded with:

.. code-block:: bash
.. code-block:: console

# Download the compose file
wget https://raw.githubusercontent.com/ros2/ros2_documentation/{DISTRO}/source/Tutorials/Advanced/Security/resources/deployment_gd/compose.deployment.yaml
$ wget https://raw.githubusercontent.com/ros2/ros2_documentation/{DISTRO}/source/Tutorials/Advanced/Security/resources/deployment_gd/compose.deployment.yaml

Running the example
-------------------

In the same working directory ``~/security_gd_tutorial``, run:
In the same working directory ``~/security_gd_tutorial``, to start the example run:

.. code-block:: bash
.. code-block:: console

# Start the example
docker compose -f compose.deployment.yaml up
$ docker compose -f compose.deployment.yaml up

This should result in the following output:

Expand All @@ -162,19 +158,22 @@ This should result in the following output:
Examining the containers
^^^^^^^^^^^^^^^^^^^^^^^^

While having the containers running that simulate the two remote devices for this tutorial, attach to each of them by opening two different terminals and enter:
While having the containers running that simulate the two remote devices for this tutorial, attach to each of them by opening two different terminals.
In the first terminal, run:

.. code-block:: bash
.. code-block:: console

# Terminal 1
docker exec -it tutorial-listener-1 bash
cd keystore
tree
$ docker exec -it tutorial-listener-1 bash
$ cd keystore
$ tree

# Terminal 2
docker exec -it tutorial-talker-1 bash
cd keystore
tree
In the second terminal, run:

.. code-block:: console

$ docker exec -it tutorial-talker-1 bash
$ cd keystore
$ tree

A similar output to the one depicted below should be obtained:

Expand Down
85 changes: 41 additions & 44 deletions source/Tutorials/Advanced/Security/Examine-Traffic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,10 @@ Install ``tcpdump``
Begin in a new terminal window by installing `tcpdump <https://www.tcpdump.org/manpages/tcpdump.1.html>`_, a command-line tool for capturing and displaying network traffic.
Although this tutorial describes ``tcpdump`` commands, you can also use `Wireshark <https://www.wireshark.org/>`_, a similar graphical tool for capturing and analyzing traffic.

.. code-block:: bash
.. code-block:: console

sudo apt update
sudo apt install tcpdump
$ sudo apt update
$ sudo apt install tcpdump

Run following commands on a single machine through multiple ``ssh`` sessions.

Expand All @@ -58,17 +58,19 @@ Start the talker and listener

Start both the talker and the listener again, each in its own terminal.
The security environment variables are not set so security is not enabled for these sessions.
In one terminal run:

.. code-block:: bash
.. code-block:: console

# Disable ROS Security for both terminals
unset ROS_SECURITY_ENABLE
$ unset ROS_SECURITY_ENABLE
$ ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker

# In terminal 1:
ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker
In another terminal run:

# In terminal 2:
ros2 run demo_nodes_cpp listener --ros-args --enclave /talker_listener/listener
.. code-block:: console

$ unset ROS_SECURITY_ENABLE
$ ros2 run demo_nodes_cpp listener --ros-args --enclave /talker_listener/listener


Display unencrypted discovery packets
Expand All @@ -79,12 +81,9 @@ You need to use ``sudo`` since reading raw network traffic is a privileged opera

The command below uses the ``-X`` option to print packet contents, the ``-i`` option to listen for packets on any interface, and captures only `UDP <https://en.wikipedia.org/wiki/User_Datagram_Protocol>`_ port 7400 traffic.

.. code-block:: bash

sudo tcpdump -X -i any udp port 7400

You should see packets like the following::
.. code-block:: console

$ sudo tcpdump -X -i any udp port 7400
20:18:04.400770 IP 8_xterm.46392 > 239.255.0.1.7400: UDP, length 252
0x0000: 4500 0118 d48b 4000 0111 7399 c0a8 8007 [email protected].....
0x0010: efff 0001 b538 1ce8 0104 31c6 5254 5053 .....8....1.RTPS
Expand All @@ -109,14 +108,12 @@ Some other features of a typical discovery packet:
Display unencrypted data packets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use ``tcpdump`` to capture non-discovery RTPS packets by filtering on UDP ports above 7400:
Use ``tcpdump`` to capture non-discovery RTPS packets by filtering on UDP ports above 7400.
You will see few different types of packets, but watch for something like the following which is obviously data being sent from a talker to a listener:

.. code-block:: bash

sudo tcpdump -i any -X udp portrange 7401-7500

You will see few different types of packets, but watch for something like the following which is obviously data being sent from a talker to a listener::
.. code-block:: console

$ sudo tcpdump -i any -X udp portrange 7401-7500
20:49:17.927303 IP localhost.46392 > localhost.7415: UDP, length 84
0x0000: 4500 0070 5b53 4000 4011 e127 7f00 0001 E..p[S@.@..'....
0x0010: 7f00 0001 b538 1cf7 005c fe6f 5254 5053 .....8...\.oRTPS
Expand All @@ -138,32 +135,34 @@ Enable encryption
Stop both the talker and the listener nodes.
Enable encryption for both by setting the security environment variables and run them again.

.. code-block:: bash
In terminal 1:

# In terminal 1:
export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore
export ROS_SECURITY_ENABLE=true
export ROS_SECURITY_STRATEGY=Enforce
ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker
.. code-block:: console

# In terminal 2:
export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore
export ROS_SECURITY_ENABLE=true
export ROS_SECURITY_STRATEGY=Enforce
ros2 run demo_nodes_cpp listener --ros-args --enclave /talker_listener/listener
$ export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore
$ export ROS_SECURITY_ENABLE=true
$ export ROS_SECURITY_STRATEGY=Enforce
$ ros2 run demo_nodes_cpp talker --ros-args --enclave /talker_listener/talker

In terminal 2:

Display encrypted discovery packets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console

$ export ROS_SECURITY_KEYSTORE=~/sros2_demo/demo_keystore
$ export ROS_SECURITY_ENABLE=true
$ export ROS_SECURITY_STRATEGY=Enforce
$ ros2 run demo_nodes_cpp listener --ros-args --enclave /talker_listener/listener

Run the same ``tcpdump`` command used earlier to examine the output of discovery traffic with encryption enabled:

.. code-block:: bash
Display encrypted discovery packets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

sudo tcpdump -X -i any udp port 7400
Run the same ``tcpdump`` command used earlier to examine the output of discovery traffic with encryption enabled
The typical discovery packet looks somewhat like the following:

The typical discovery packet looks somewhat like the following::
.. code-block:: console

$ sudo tcpdump -X -i any udp port 7400
21:09:07.336617 IP 8_xterm.60409 > 239.255.0.1.7400: UDP, length 596
0x0000: 4500 0270 c2f6 4000 0111 83d6 c0a8 8007 E..p..@.........
0x0010: efff 0001 ebf9 1ce8 025c 331e 5254 5053 .........\3.RTPS
Expand Down Expand Up @@ -192,14 +191,12 @@ Take a look at the excellent paper `Network Reconnaissance and Vulnerability Exc
Display encrypted data packets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now use ``tcpdump`` to capture data packets:

.. code-block:: bash

sudo tcpdump -i any -X udp portrange 7401-7500
Now use ``tcpdump`` to capture data packets.
A typical data packet looks like the following:

A typical data packet looks like the following::
.. code-block:: console

$ sudo tcpdump -i any -X udp portrange 7401-7500
21:18:14.531102 IP localhost.54869 > localhost.7415: UDP, length 328
0x0000: 4500 0164 bb42 4000 4011 8044 7f00 0001 E..d.B@[email protected]....
0x0010: 7f00 0001 d655 1cf7 0150 ff63 5254 5053 .....U...P.cRTPS
Expand Down
Loading