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

Signed-off-by: Nils-Christian Iseke <[email protected]>
Signed-off-by: Christophe Bedard <[email protected]>
Co-authored-by: Christophe Bedard <[email protected]>

Author: Nils-ChristianIseke

source/Tutorials/Advanced/Security/Access-Controls.rst

@@ -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.
@@ -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
 
@@ -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
 
 
@@ -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

source/Tutorials/Advanced/Security/Deployment-Guidelines.rst

@@ -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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -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:
 
@@ -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:
 

source/Tutorials/Advanced/Security/Examine-Traffic.rst

@@ -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.
 
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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