From 5a6d5dfbbc017128dc977a33e145358d38bd0324 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Thu, 18 May 2023 08:47:24 -0400 Subject: [PATCH] Fix keystore dir name (#3634) (#3635) Signed-off-by: Yadunund (cherry picked from commit ee95bb6829b05a3230f88135d6ac9e056f805f41) Co-authored-by: Yadu --- .../Advanced/Security/Access-Controls.rst | 6 ++++-- .../Advanced/Security/Security-on-Two.rst | 2 ++ .../Tutorials/Advanced/Security/The-Keystore.rst | 14 ++++++++------ 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/source/Tutorials/Advanced/Security/Access-Controls.rst b/source/Tutorials/Advanced/Security/Access-Controls.rst index 9e37888a9f..511520dc9b 100644 --- a/source/Tutorials/Advanced/Security/Access-Controls.rst +++ b/source/Tutorials/Advanced/Security/Access-Controls.rst @@ -21,6 +21,8 @@ Setting access controls Background ---------- +Before proceeding ensure you have completed the :doc:`Introducing-ros2-security` tutorial. + Permissions are quite flexible and can be used to control many behaviors within the ROS graph. For this tutorial, we demonstrate a policy which only allows publishing messages on the default ``chatter`` topic. @@ -37,7 +39,7 @@ Begin by making a backup of your permissions files, and open ``permissions.xml`` .. code-block:: bash - cd ~/sros2_demo/demo_keys/enclaves/talker_listener/talker + cd ~/sros2_demo/demo_keystore/enclaves/talker_listener/talker mv permissions.p7s permissions.p7s~ mv permissions.xml permissions.xml~ vi permissions.xml @@ -115,7 +117,7 @@ If the private key has been protected, additional steps may be required to unloc openssl smime -sign -text -in permissions.xml -out permissions.p7s \ --signer permissions_ca.cert.pem \ - -inkey ~/sros2_demo/demo_keys/private/permissions_ca.key.pem + -inkey ~/sros2_demo/demo_keystore/private/permissions_ca.key.pem Launch the node diff --git a/source/Tutorials/Advanced/Security/Security-on-Two.rst b/source/Tutorials/Advanced/Security/Security-on-Two.rst index 0d7b6f9822..b005a312ec 100644 --- a/source/Tutorials/Advanced/Security/Security-on-Two.rst +++ b/source/Tutorials/Advanced/Security/Security-on-Two.rst @@ -21,6 +21,8 @@ Ensuring security across machines Background ---------- +Before proceeding ensure you have completed the :doc:`Introducing-ros2-security` tutorial. + The previous tutorials have used two ROS nodes on the same machine sending all network communications over the localhost interface. Let's extend that scenario to involve multiple machines, since the benefits of authentication and encryption then become more obvious. diff --git a/source/Tutorials/Advanced/Security/The-Keystore.rst b/source/Tutorials/Advanced/Security/The-Keystore.rst index 79e75736f0..cae9b5b607 100644 --- a/source/Tutorials/Advanced/Security/The-Keystore.rst +++ b/source/Tutorials/Advanced/Security/The-Keystore.rst @@ -21,6 +21,8 @@ Understanding the security keystore Background ---------- +Before proceeding ensure you have completed the :doc:`Introducing-ros2-security` tutorial. + The ``sros2`` package can be used to create keys, certificates and policies necessary to enable ROS 2 security. However, the security configuration is extrememly flexible. A basic understanding of the ROS 2 Security Keystore will allow integration with an existing PKI (Public Key Infrastructure) and managment of sensitive key materials consistent with organizational policies. @@ -41,7 +43,7 @@ For this tutorial, we use the directory ``~/sros2_demo/demo_keystore``. Public Key Materials ^^^^^^^^^^^^^^^^^^^^ -You will find three encryption certificates in the public directory at ``~/sros2_demo/demo_keys/public``; however, the identity and permissions certificates are actually just a link to the Certificate Authority (CA) certificate. +You will find three encryption certificates in the public directory at ``~/sros2_demo/demo_keystore/public``; however, the identity and permissions certificates are actually just a link to the Certificate Authority (CA) certificate. In a public key infrastructure, the `Certificate Authority `_ acts as a trust anchor: it validates the identities and permissions of participants. For ROS, that means all the nodes that participate in the ROS graph (which may extend to an entire fleet of individual robots). @@ -58,7 +60,7 @@ Use ``openssl`` to view this x509 certificate and display it as text: .. code-block:: bash - cd ~/sros2_demo/demo_keys/public + cd ~/sros2_demo/demo_keystore/public openssl x509 -in ca.cert.pem -text -noout The output should look similar to the following:: @@ -106,7 +108,7 @@ Since this is a public certificate, it can be freely copied as needed to establi Private Key Materials ^^^^^^^^^^^^^^^^^^^^^ -Private key materials can be found in the keystore directory ``~/sros2_demo/demo_keys/private``. +Private key materials can be found in the keystore directory ``~/sros2_demo/demo_keystore/private``. Similar to the ``public`` directory, this contains one certificate authority key ``ca.key.pem`` and symbolic links to it to be used as both an Identity and a Permissions CA private key. .. warning:: @@ -128,7 +130,7 @@ Use the following command to show details about this elliptic curve private key: .. code-block:: bash - cd ~/sros2_demo/demo_keys/private + cd ~/sros2_demo/demo_keystore/private openssl ec -in ca.key.pem -text -noout Your output should look similar to the following:: @@ -154,7 +156,7 @@ In addition to the private key itself, note that the public key is listed, and i Domain Governance Policy ^^^^^^^^^^^^^^^^^^^^^^^^ -Find the domain governance policy in the enclave directory within the keystore, ``~/sros2_demo/demo_keys/enclaves``. +Find the domain governance policy in the enclave directory within the keystore, ``~/sros2_demo/demo_keystore/enclaves``. The ``enclave`` directory contains XML governance policy document ``governance.xml``, as well as a copy of the document which has been signed by the Permissions CA as ``governance.p7s``. The ``governance.p7s`` file contains domain-wide settings such as how to handle unauthenticated participants, whether to encrypt discovery, and default rules for access to topics. @@ -211,7 +213,7 @@ Begin with a new terminal session and enable security with the keystore created export ROS_SECURITY_ENABLE=true export ROS_SECURITY_STRATEGY=Enforce - cd ~/sros2_demo/demo_keys/enclaves/talker_listener/listener + cd ~/sros2_demo/demo_keystore/enclaves/talker_listener/listener Make a backup copy of ``permissions.p7s`` before beginning.