From 0f94ed23c8c5642dc8b9f3b6e05648002f196a23 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Sat, 22 Feb 2020 02:57:30 -0800 Subject: [PATCH 01/49] Add initial draft for ROS 2 Security Contexts Signed-off-by: ruffsl Co-Authored-By: Mikael Arguedas --- articles/ros2_security_contexts.md | 307 +++++++++++++++++++++++++++++ 1 file changed, 307 insertions(+) create mode 100644 articles/ros2_security_contexts.md diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md new file mode 100644 index 000000000..a8f56431c --- /dev/null +++ b/articles/ros2_security_contexts.md @@ -0,0 +1,307 @@ +--- +layout: default +title: ROS 2 Security Contexts +permalink: articles/ros2_security_contexts.html +abstract: + This article specifies the integration between security and contexts. +author: > + [Ruffin White](https://github.com/ruffsl), + [Mikael Arguedas](https://github.com/mikaelarguedas) + +published: false +categories: Security +--- + +{:toc} + + +# {{ page.title }} + +
+{{ page.abstract }} +
+ +Original Author: {{ page.author }} + + +TODO: Some concise overview introduction here + +## Concepts + +Before detailing the SROS 2 integration of the contexts, the following concepts are introduced. + +### Participant + +Participant is the object representing a single entity on the network, in the case of DDS the ``Participant`` is a DDS DomainParticipant and the object to which a set of access control and security identity apply. + +### Namespaces + +Namespaces are a fundamental design pattern in ROS and are widely used to organize and differentiate many types of resources as to be uniquely identifiable; i.e. for topics, services, actions, and node names. +As such, the concept of namespaceing is well know and understood by current users, as well as strongly supported with the existing tooling. +Namespaces are often configurable at runtime via command line arguments or statically/programmatically via launch file declarations. + +Previously, the Fully Qualified Name (FQN) of a node was used directly by a selected security directory lookup strategy to load the necessary key material. +However, with the advent of contexts, such a direct mapping of FQN to security artifacts may no longer suffice. + +### Contexts + +With the advent of ROS 2, multiple nodes may now be composed into one process for improved performance. +Previously however, each node would retain it's one to one mapping to a separate middleware ``Participant``. +Given the non-negligible overhead incurred of multiple ``Participant``s per process, a concept of contexts was introduced. +Contexts permit a many-to-one mapping of nodes to ``Participant`` by grouping many nodes per context, and one ``Participant`` per context. + +Based on the DDS Security specification v1.1, a ``Participant`` can only utilise a single security identity; consequently the access control permissions applicable to every node mapped to a given context must be consolidated and combined into a single set of security artifacts. +As such, additional tooling and extensions to SROS 2 are necessary to support this new paradigm. + + +## Keystore + +With the additional structure of contexts, it’s perhaps best to take the opportunity to restructure the keystore layout as well. +Rather than a flat directory of namespaced node security directories, we can push all such security directories down into a designated `contexts` sub-folder. +Similarly, private and public keystore materials can also be pushed down into their own respective sub-folders within the root keystore directory. +This is reminiscent of the pattern used earlier Keymint [1]. + + +``` +$ tree keystore/ +keystore +├── contexts +│ └── ... +│ └── ... +├── private +│ ├── ca.csr.pem +│ └── ca.key.pem +└── public + ├── ca.cert.pem + ├── identity_ca.cert.pem + └── permissions_ca.cert.pem +``` + + +### ``public`` + +The ``public`` directory contains anything permissable as public, such as public certificates for the identity or permissions certificate authorities. +As such, this can be given read access to all executables. +Note that in the default case, both the `identity_ca` and `permissions_ca` are the same CA certificate. + +### ``private`` + +The ``private`` directory contains anything permissable as private, such as private key material for aforementioned certificate authorities. +This directory should be redacted before deploying the keystore onto the target device/robot. + +### ``contexts`` + +The ``contexts`` directory contains the security artifacts associated with individual contexts, and thus node directories are no longer relevant. +Similar to node directories however, the `contexts` folder may still recursively nest sub-paths for organizing separate contexts. + + +## Runtime + +TODO: Some transition paragraph here about ros launch + +### Unqualified context path + +For nodes with unqualified context paths, the context directory will subsequently default to the root level context. + +``` xml + + + + +``` + +``` +$ tree contexts/ +contexts/ +├── cert.pem +├── governance.p7s +├── identity_ca.cert.pem +├── key.pem +├── permissions_ca.cert.pem +└── permissions.p7s +``` + +### Pushed unqualified context path + +For nodes with unqualified context paths pushed by a namespace, the context directory will subsequently be pushed to the relative sub-folder. + +``` xml + + + + + + + +``` + +``` +$ tree --dirsfirst contexts/ +contexts/ +├── foo +│ ├── cert.pem +│ ├── governance.p7s +│ ├── identity_ca.cert.pem +│ ├── key.pem +│ ├── permissions_ca.cert.pem +│ └── permissions.p7s +├── cert.pem +├── governance.p7s +├── identity_ca.cert.pem +├── key.pem +├── permissions_ca.cert.pem +└── permissions.p7s +``` + +### Relatively pushed qualified context path + +For nodes with qualified context paths pushed by a namespace, the qualified context directory will subsequently be pushed to the relative sub-folder. + +``` xml + + + + + + +``` + +``` +$ tree --dirsfirst contexts/ +contexts/ +└── foo + └── bar + ├── cert.pem + ├── governance.p7s + ├── identity_ca.cert.pem + ├── key.pem + ├── permissions_ca.cert.pem + └── permissions.p7s +``` + +### Fully qualified context path + +For nodes with absolute context paths, namespaces do not subsequently push the relative sub-folder. + +``` xml + + + + + + +``` + +``` +$ tree --dirsfirst contexts/ +contexts/ +└── bar + ├── cert.pem + ├── governance.p7s + ├── identity_ca.cert.pem + ├── key.pem + ├── permissions_ca.cert.pem + └── permissions.p7s +``` + + +## Alternatives + +### Context path orthogonal to namespace + +An alternative to reusing namespaces to hint the context path could be to completely disassociate the two entirely, treating the context path as it's own unique identifier. +However, having to book keep both identifier spaces simulations may introduce to many degrees of freedom that a human could groc or easily introspect via tooling. + +#### `` + +TODO: Describe added `context` attribute to `push_ros_namespace` element. +Keeps pushing contexts close/readable to pushing of namespaces. + +#### `` + +TODO: Describe added `push_ros_context` element. +Keeps pushing context path independent/flexable from namespaces. + + +## Concerns + +### Multiple namespaces per context + +For circumstances where users may compose multiple nodes of dissimilar namespaces into a single context, the user must subsequently specify a common fully qualified context path for each node to compose, as the varying different namespaces would not push to a common context. +For circumstances where the context path is orthogonal to node namespace, the use of fully qualifying all relevant nodes is could be tedious, but could perhaps could still be parametrized via the use of ``, and `` substitution and expansion. + + +### Modeling permissions of nodes in a process v.s. permission of the middleware ``Participant`` + +Before the use of contexts, multiple nodes composed into a single process where each mapped to a separate ``Participant``. +Each ``Participant`` subsequently load a security identity and access control credential prevalent to its' respective node. +However, all nodes in that process share the same memory space and can thus access data from other nodes. +There is a mismatch between the middleware credentials/permissions loaded and the resources accessible within the process. + +By using contexts, all nodes in a context share the same security identity and access control credentials. +This inevitably means that code compiled to node ``foo`` can access credentials/permissions only trusted to node ``bar``. +This consequence of composition could unintendedly subvert the minimal spanning policy as architected by the policy designer or measured/generated via ROS 2 tooling/IDL. + +With the introduction of contexts, it becomes possible to describe the union of access control permission by defining a collection of SROS 2 policy profiles as element within a specific context. +This would allow for formal analysis tooling [2] to check for potential violations in information flow control given the composing of nodes at runtime. +If a process contains a single context, this reconciles the permissions of a ``Participant`` and the ones of the process. + +However, should multiple contexts be used per process, then such security guaranties are again lost because both contexts will share the same memory space. +Thus it should be asked whether if multiple contexts per process should even be supported. + + +In summary, the distinction here is that before, the composition of multiple permissions could not be conveyed to the tooling. +Whether nodes could gain the permission of others in the same process space is not the hinge point of note; it's the fact that such side effects could not be formally modeled or accounted for by the designer. +It will now be possible with contexts, however allowing for multiple contexts per process will reintroduce and exacerbates the same modeling inaccuracies. + +### Composable launchfile includes + +A particular challenge in using launchfiles with security contexts is that of keeping the include hierarchy composable. +An inherit tradeoff between simplicity and configurability can arise when writing launchfiles for downstream use. +Authors can selectively choose what attributes to expose as input arguments, while users may implicitly override provided defaults. + +In case of contexts, it is not inherently clear what best practices either package authors or users should employ to retain a composable and intuitive launchfile structure. E.g: +Should authors parametrize context paths for each node as input arguments? +Should users push namespaces of included launchfiles to separate contexts? +Should the setting of security environment variables be discouraged from within launchfiles, limiting the use of simple static analysis of launchfiles combined with Node IDL for procedural context generation? + +### Composable nodes in container + +Given that containers can be dynamic, where nodes can be added or removed at runtime, there is perhaps some question as to how containers should integrate with secure contexts. +The most straightforward approach is perhaps only specifying the context wherever the container is first defined/launched, applying to the container participant, thus to all nodes/components inside that container. +This should be further deliberated when eventually extending the launch API for containers. + +### Migration for RMW implementations + +As it may take time before all RMW implementations implement the new system of contexts, a defined fallback behavior should still be designated. +For such implementations, the context security directory determined by RCL should be loaded for the participant as per the priority of context setting specified in the "ROS 2 DDS-Security integration" design doc. +This primarily desists the use of including the node name in the default lookup path, consequently getting users in the habit of creating separate contexts for separate processes, or explicitly specifying unique context names via launchfiles. + +## References + +1. [Procedurally Provisioned Access Control for Robotic Systems](https://doi.org/10.1109/IROS.2018.8594462) + +``` bibtex +@inproceedings{White2018, + title = {Procedurally Provisioned Access Control for Robotic Systems}, + author = {White, Ruffin and Caiazza, Gianluca and Christensen, Henrik and Cortesi, Agostino}, + year = 2018, + booktitle = {2018 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, + doi = {10.1109/IROS.2018.8594462}, + issn = {2153-0866}, + url = {https://arxiv.org/pdf/1810.08125.pdf}} +``` + + +2. [Network Reconnaissance and Vulnerability Excavation of Secure DDS Systems](https://doi.org/10.1109/EuroSPW.2019.00013) + +``` bibtex +@inproceedings{White2019, + title = {Network Reconnaissance and Vulnerability Excavation of Secure DDS Systems}, + author = {White, Ruffin and Caiazza, Gianluca and Jiang, Chenxu and Ou, Xinyue and Yang, Zhiyue and Cortesi, Agostino and Christensen, Henrik}, + year = 2019, + booktitle = {2019 IEEE European Symposium on Security and Privacy Workshops (EuroS PW)}, + doi = {10.1109/EuroSPW.2019.00013}, + pages = {57-66}, + url = {https://arxiv.org/abs/1908.05310.pdf}} +``` From 4dd1ae2448e1adbd0de11f55653e8db1e83ec9c1 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 24 Feb 2020 18:40:43 -0800 Subject: [PATCH 02/49] Update policy schema for contexts --- articles/ros2_access_control_policies.md | 20 ++++++++++++++++++- .../ros2_access_control_policies/policy.xsd | 15 +++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/articles/ros2_access_control_policies.md b/articles/ros2_access_control_policies.md index 948bc5238..6d1914b69 100644 --- a/articles/ros2_access_control_policies.md +++ b/articles/ros2_access_control_policies.md @@ -99,10 +99,28 @@ Attributes: - **version**: declared version of schema version in use - Allows for advancing future revisions of the schema +### `` Tag + +Encapsulates a sequence of unique contexts. +This method of nesting sequences allows for additional tags to be extended to the `` root. + +### `` Tag + +Encapsulates a collection of profiles. +This is specific to a context as determined by associative attributes. + +Attributes: +- **path**: Fully qualified context path + +Given that multiple nodes can be composed into a single process, a context is used to contain the collection of profiles of all respective nodes. +A context may therefor be considered the union of contained profiles. +Note that the union of profiles within a context will result in denied privileges of any profile to supersede all allowed privileges for every profile. +See section `` Tag for more info on MAC is applied. + ### `` Tag Encapsulates a sequence of unique profiles. -This method of nesting sequences allows for additional tags to be extended to the `` root. +This method of nesting sequences allows for additional tags to be extended to the `` root. ### `` Tag diff --git a/articles/ros2_access_control_policies/policy.xsd b/articles/ros2_access_control_policies/policy.xsd index 8086516e9..0e8bf77bf 100644 --- a/articles/ros2_access_control_policies/policy.xsd +++ b/articles/ros2_access_control_policies/policy.xsd @@ -10,11 +10,24 @@ - + + + + + + + + + + + + + + From 78868599df6231f5733e332463643ac92aaa3bbf Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 24 Feb 2020 18:58:57 -0800 Subject: [PATCH 03/49] Update DDS-Security integration for contexts --- articles/ros2_dds_security.md | 57 ++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index ef82e6c71..5250eb802 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -45,7 +45,7 @@ Let's delve a little further into those first three plugins. ## Authentication -The **Authentication** plugin (see section 8.3 of the [DDS-Security spec][dds_security]) is central to the entire SPI architecture, as it provides the concept of a confirmed identity without which further enforcement would be impossible (e.g. it would be awfully hard to make sure a given ROS node could only access specific topics if it was impossible to securely determine which node it was). +The **Authentication** plugin (see section 8.3 of the [DDS-Security spec][dds_security]) is central to the entire SPI architecture, as it provides the concept of a confirmed identity without which further enforcement would be impossible (e.g. it would be awfully hard to make sure a given ROS context could only access specific topics if it was impossible to securely determine which context it was). The SPI architecture allows for a number of potential authentication schemes, but ROS 2 uses the builtin authentication plugin (called "DDS:Auth:PKI-DH", see section 9.3 of the [DDS-Security spec][dds_security]), which uses the proven Public Key Infrastructure (PKI). It requires a public and private key per domain participant, as well as an x.509 certificate that binds the participant's public key to a specific name. @@ -114,7 +114,7 @@ Let's discuss each of these in turn. ### Security files for each domain participant As stated earlier, the DDS-Security plugins require a set of security files (e.g. keys, governance and permissions files, etc.) per domain participant. -Domain participants map to a specific instance of a node in ROS 2, so each node requires a set of these files. +Domain participants map to a specific instance of a context in ROS 2, so each context requires a set of these files. RCL supports being pointed at a directory containing security files in two different ways: - Directory tree of all security files. @@ -125,41 +125,42 @@ Let's delve further into these. #### Directory tree of all security files -RCL supports finding security files in one directory that is the root of a directory structure corresponding to the fully-qualified names of every node instance (i.e. namespace + node name). -For example, for the `/front/camera` node, the directory structure would look like: +RCL supports finding security files in one directory that is the root of a directory structure corresponding to the fully-qualified names of every context (e.g. namespace + context name). +For example, for the `/front/camera` context, the directory structure would look like: - └── front - └── camera - ├── cert.pem - ├── key.pem - ├── ... + └── contexts + └── front + └── camera + ├── cert.pem + ├── key.pem + ├── ... To be clear: this directory structure needs to reflect the state of the running system. -In other words, it does not contain a set of files per node on disk, but per node instance _in the ROS graph_. +In other words, it does not contain a set of files per context on disk, but per context instance _in the ROS graph_. -The set of files expected within each node instance directory are: +The set of files expected within each context instance directory are: - **identity_ca.cert.pem**: The x.509 certificate of the CA trusted by the **Authentication** plugin (the "Identity" CA). -- **cert.pem**: The x.509 certificate of this node instance (signed by the Identity CA). -- **key.pem**: The private key of this node instance. +- **cert.pem**: The x.509 certificate of this context instance (signed by the Identity CA). +- **key.pem**: The private key of this context instance. - **permissions_ca.cert.pem**: The x.509 certificate of the CA trusted by the **Access control** plugin (the "Permissions" CA). - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). -- **permissions.p7s**: The XML document that specifies the permissions of this particular node instance to the **Access control** plugin (also signed by the Permissions CA). +- **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the directory tree. ##### Support security files lookup methods -If using the directory tree approach to organize security files, RCL supports two different methods for looking up a given node instance's security files in the tree: +If using the directory tree approach to organize security files, RCL supports two different methods for looking up a given context instance's security files in the tree: -- **Exact**: Only load security files from a directory exactly matching the fully-qualified name of the node instance. -For example, given a node named "baz_123" within the "/foo/bar/" namespace, only load security files from `/foo/bar/baz_123/`. +- **Exact**: Only load security files from a directory exactly matching the fully-qualified name of the context. +For example, given a context "baz_123" within the "/foo/bar/" namespace, only load security files from `/contexts/foo/bar/baz_123/`. This is the default behavior. -- **Prefix**: Attempt to load the most specific set of security files, but if they can't be found, check for security files under a less-specific node name. -For example, given a node named "baz_123" within the "/foo/bar/" namespace, load security files from `/foo/bar/baz_123/`. -However, if that directory doesn't exist, find the most specific (i.e. longest) node name that _does_ have security files within that namespace (e.g. `/foo/bar/baz_12/`, or `/foo/bar/baz/`, etc.). +- **Prefix**: Attempt to load the most specific set of security files, but if they can't be found, check for security files under a less-specific context path. +For example, given a context "baz_123" within the "/foo/bar/" namespace, load security files from `/contexts/foo/bar/baz_123/`. +However, if that directory doesn't exist, find the most specific (i.e. longest) context path that _does_ have security files within that namespace (e.g. `/contexts/foo/bar/baz_12/`, or `/contexts/foo/bar/baz/`, etc.). Note that it will not search higher in the namespace hierarchy. The desired lookup method can be specified by setting the `$ROS_SECURITY_LOOKUP_TYPE` environment variable to "MATCH_EXACT" (case-sensitive) for the **Exact** method, or "MATCH_PREFIX" (case-sensitive) for the **Prefix** method. @@ -167,20 +168,20 @@ The desired lookup method can be specified by setting the `$ROS_SECURITY_LOOKUP_ #### Manual specification -RCL supports specifying the path to a directory containing the set of security files for the exact node instance that needs to be launched. -The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual node instance directories. +RCL supports specifying the path to a directory containing the set of security files for the exact context instance that needs to be launched. +The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. -This can be specified by setting the `$ROS_SECURITY_NODE_DIRECTORY` environment variable to point to the directory containing the security files. +This can be specified by setting the `$ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY`. ### Support for both permissive and strict enforcement of security -Nodes with the security features enabled will not communicate with nodes that don't, but what should RCL do if one tries to launch a node that has no discernable keys/permissions/etc.? It has two options: +Contexts with the security features enabled will not communicate with contexts that don't, but what should RCL do if one tries to launch a context that has no discernable keys/permissions/etc.? It has two options: -- **Permissive mode**: Try to find security files, and if they can't be found, launch the node without enabling any security features. +- **Permissive mode**: Try to find security files, and if they can't be found, launch the context without enabling any security features. This is the default behavior. -- **Strict mode**: Try to find security files, and if they can't be found, fail to run the node. +- **Strict mode**: Try to find security files, and if they can't be found, fail to run the context. The type of mode desired can be specified by setting the `$ROS_SECURITY_STRATEGY` environment variable to "Enforce" (case-sensitive) for strict mode, and anything else for permissive mode. @@ -202,9 +203,9 @@ However, the [SROS 2 CLI](https://github.com/ros2/sros2) should include a tool ` - Create Identity and Permissions CA. - Create directory tree containing all security files. -- Create a new identity for a given node instance, generating a keypair and signing its x.509 certificate using the Identity CA. +- Create a new identity for a given context instance, generating a keypair and signing its x.509 certificate using the Identity CA. - Create a governance file that will encrypt all DDS traffic by default. -- Support specifying node instance permissions [in familiar ROS terms](/articles/ros2_access_control_policies.html) which are then automatically converted into low-level DDS permissions. +- Support specifying context instance permissions [in familiar ROS terms](/articles/ros2_access_control_policies.html) which are then automatically converted into low-level DDS permissions. - Support automatically discovering required permissions from a running ROS system. From f2a3c2bf0094790ed0cd30c98be39276d94c80a5 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Wed, 26 Feb 2020 22:55:10 -0800 Subject: [PATCH 04/49] Fix typo --- articles/ros2_access_control_policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_access_control_policies.md b/articles/ros2_access_control_policies.md index 6d1914b69..25f256552 100644 --- a/articles/ros2_access_control_policies.md +++ b/articles/ros2_access_control_policies.md @@ -113,7 +113,7 @@ Attributes: - **path**: Fully qualified context path Given that multiple nodes can be composed into a single process, a context is used to contain the collection of profiles of all respective nodes. -A context may therefor be considered the union of contained profiles. +A context may therefore be considered the union of contained profiles. Note that the union of profiles within a context will result in denied privileges of any profile to supersede all allowed privileges for every profile. See section `` Tag for more info on MAC is applied. From 735d278cd481db6e67b670e8caa305efbd7a0e6e Mon Sep 17 00:00:00 2001 From: Ruffin Date: Wed, 26 Feb 2020 22:55:44 -0800 Subject: [PATCH 05/49] Fix typo --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index a8f56431c..09489a73d 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -80,7 +80,7 @@ keystore ### ``public`` -The ``public`` directory contains anything permissable as public, such as public certificates for the identity or permissions certificate authorities. +The ``public`` directory contains anything permissible as public, such as public certificates for the identity or permissions certificate authorities. As such, this can be given read access to all executables. Note that in the default case, both the `identity_ca` and `permissions_ca` are the same CA certificate. From 853c2b346c6f0ebb6c2bbb597441adbdd2f04344 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Wed, 26 Feb 2020 23:31:40 -0800 Subject: [PATCH 06/49] Fix typo --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 09489a73d..e2c9fb671 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -37,7 +37,7 @@ Participant is the object representing a single entity on the network, in the ca ### Namespaces Namespaces are a fundamental design pattern in ROS and are widely used to organize and differentiate many types of resources as to be uniquely identifiable; i.e. for topics, services, actions, and node names. -As such, the concept of namespaceing is well know and understood by current users, as well as strongly supported with the existing tooling. +As such, the concept of namespacing is well know and understood by current users, as well as strongly supported with the existing tooling. Namespaces are often configurable at runtime via command line arguments or statically/programmatically via launch file declarations. Previously, the Fully Qualified Name (FQN) of a node was used directly by a selected security directory lookup strategy to load the necessary key material. From ea11d70708cc094ca1a387e3e54b39a55f24b311 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Thu, 27 Feb 2020 14:29:11 -0800 Subject: [PATCH 07/49] Editorial rephrasing Co-Authored-By: Kyle Fazzari --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index e2c9fb671..70f315f86 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -32,7 +32,7 @@ Before detailing the SROS 2 integration of the contexts, the following concepts ### Participant -Participant is the object representing a single entity on the network, in the case of DDS the ``Participant`` is a DDS DomainParticipant and the object to which a set of access control and security identity apply. +Participant is the object representing a single entity on the network. In the case of DDS, the ``Participant`` is a DDS DomainParticipant, which has both access control permissions and a security identity. ### Namespaces From 1f72771528292126e3ab6fb2832dfb11face7a0a Mon Sep 17 00:00:00 2001 From: Ruffin Date: Thu, 27 Feb 2020 14:29:50 -0800 Subject: [PATCH 08/49] Fix typo Co-Authored-By: Kyle Fazzari --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 70f315f86..bbb802d14 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -37,7 +37,7 @@ Participant is the object representing a single entity on the network. In the ca ### Namespaces Namespaces are a fundamental design pattern in ROS and are widely used to organize and differentiate many types of resources as to be uniquely identifiable; i.e. for topics, services, actions, and node names. -As such, the concept of namespacing is well know and understood by current users, as well as strongly supported with the existing tooling. +As such, the concept of namespacing is well known and understood by current users, as well as strongly supported by the existing tooling. Namespaces are often configurable at runtime via command line arguments or statically/programmatically via launch file declarations. Previously, the Fully Qualified Name (FQN) of a node was used directly by a selected security directory lookup strategy to load the necessary key material. From 9eef58c4ae1cd7d0bdcbb3ed76159264f5b19532 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Thu, 27 Feb 2020 14:31:02 -0800 Subject: [PATCH 09/49] Editorial rephrasing Co-Authored-By: Kyle Fazzari --- articles/ros2_security_contexts.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index bbb802d14..5ab02b109 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -47,8 +47,7 @@ However, with the advent of contexts, such a direct mapping of FQN to security a With the advent of ROS 2, multiple nodes may now be composed into one process for improved performance. Previously however, each node would retain it's one to one mapping to a separate middleware ``Participant``. -Given the non-negligible overhead incurred of multiple ``Participant``s per process, a concept of contexts was introduced. -Contexts permit a many-to-one mapping of nodes to ``Participant`` by grouping many nodes per context, and one ``Participant`` per context. +Given the non-negligible overhead incurred of multiple ``Participant``s per process, a change was introduced to map a single ``Participant`` to a context, and allow for multiple nodes to share that context. Based on the DDS Security specification v1.1, a ``Participant`` can only utilise a single security identity; consequently the access control permissions applicable to every node mapped to a given context must be consolidated and combined into a single set of security artifacts. As such, additional tooling and extensions to SROS 2 are necessary to support this new paradigm. From 8da5c02b2daef48c7791b3bedd82e63a8e844151 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Thu, 27 Feb 2020 14:34:32 -0800 Subject: [PATCH 10/49] Editorial rephrasing --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 5ab02b109..54321ba39 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -41,7 +41,7 @@ As such, the concept of namespacing is well known and understood by current user Namespaces are often configurable at runtime via command line arguments or statically/programmatically via launch file declarations. Previously, the Fully Qualified Name (FQN) of a node was used directly by a selected security directory lookup strategy to load the necessary key material. -However, with the advent of contexts, such a direct mapping of FQN to security artifacts may no longer suffice. +However, now that Participants map to contexts and not nodes, such a direct mapping of node FQN to security artifacts is no longer appropriate. ### Contexts From e387ac17364ef89e90ff7a9e68d475350347b4bf Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 5 Mar 2020 18:10:28 -0800 Subject: [PATCH 11/49] Allow contexts to formalize cross domain bridging --- articles/ros2_access_control_policies.md | 20 +++++++++++++++++-- .../ros2_access_control_policies/policy.xsd | 6 +++++- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/articles/ros2_access_control_policies.md b/articles/ros2_access_control_policies.md index 25f256552..ad9879357 100644 --- a/articles/ros2_access_control_policies.md +++ b/articles/ros2_access_control_policies.md @@ -119,8 +119,11 @@ See section `` Tag for more info on MAC is applied. ### `` Tag -Encapsulates a sequence of unique profiles. -This method of nesting sequences allows for additional tags to be extended to the `` root. +Encapsulates a sequence of unique profiles and designated metadata. +This method of nesting sequences allows for additional tags to be extended to the `` root, as well as associating particular metadata or constraints to the contained profile elements. + +Attributes: +- **type**: Specifies the transport type of profiles and metadata ### `` Tag @@ -137,6 +140,19 @@ That is to say the priority of denied privileges conservatively supersedes allow This method of flatting privileges enables users to provision general access to a larger set of objects, while simultaneously revoking access to a smaller subset of sensitive objects. Although recursion of qualifiers is subsequently prevented, transformations are subsequently simplified, preventing potential for unintended access. +### `` Tag + +Encapsulates arbitrary metadata or constraints. +This could include transport specific permission details applicable to sibling profile elements. +There can only one `metadata` element per `profiles` parent element. + +Attributes: +- To be defined + +Given the use cases for bridge interfaces where a context's credentials may be used to interconnect across multiple transports or to transport specific domains, it may be necessary to qualify certain profile sequences with particular constraints, while doing so multiple times for separate profiles per context. +This allows advanced users to holistically control the intersect of permissions across transport domains, while retaining accurate model fidelity of security permissions. +Given how security sensitive bridge interfaces are and the attack surface they expose, it is vital that information flow control within a bridge remains formally verifiable for safe and secure operation. + #### Privileges Privileges are defined as configuration of rules and permissions for object access. diff --git a/articles/ros2_access_control_policies/policy.xsd b/articles/ros2_access_control_policies/policy.xsd index 0e8bf77bf..6b7906750 100644 --- a/articles/ros2_access_control_policies/policy.xsd +++ b/articles/ros2_access_control_policies/policy.xsd @@ -22,7 +22,7 @@ - + @@ -32,6 +32,10 @@ + + + + From 9099a69d183c5ecb166067d59ed3240e7854edf6 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 9 Mar 2020 15:23:37 -0700 Subject: [PATCH 12/49] Update context vocab --- articles/ros2_dds_security.md | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 5250eb802..052d2f131 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -125,19 +125,15 @@ Let's delve further into these. #### Directory tree of all security files -RCL supports finding security files in one directory that is the root of a directory structure corresponding to the fully-qualified names of every context (e.g. namespace + context name). +RCL supports finding security files in one directory that is within the root context directory structure corresponding to the fully-qualified path of every context. For example, for the `/front/camera` context, the directory structure would look like: - └── contexts - └── front - └── camera - ├── cert.pem - ├── key.pem - ├── ... - -To be clear: this directory structure needs to reflect the state of the running system. -In other words, it does not contain a set of files per context on disk, but per context instance _in the ROS graph_. + └── front + └── camera + ├── cert.pem + ├── key.pem + ├── ... The set of files expected within each context instance directory are: @@ -148,20 +144,20 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the directory tree. +This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree. ##### Support security files lookup methods If using the directory tree approach to organize security files, RCL supports two different methods for looking up a given context instance's security files in the tree: -- **Exact**: Only load security files from a directory exactly matching the fully-qualified name of the context. -For example, given a context "baz_123" within the "/foo/bar/" namespace, only load security files from `/contexts/foo/bar/baz_123/`. +- **Exact**: Only load security files from a directory exactly matching the fully-qualified path of the context. +For example, given a context "baz_123" within the "/foo/bar/" subpath, only load security files from `/foo/bar/baz_123/`. This is the default behavior. - **Prefix**: Attempt to load the most specific set of security files, but if they can't be found, check for security files under a less-specific context path. -For example, given a context "baz_123" within the "/foo/bar/" namespace, load security files from `/contexts/foo/bar/baz_123/`. -However, if that directory doesn't exist, find the most specific (i.e. longest) context path that _does_ have security files within that namespace (e.g. `/contexts/foo/bar/baz_12/`, or `/contexts/foo/bar/baz/`, etc.). -Note that it will not search higher in the namespace hierarchy. +For example, given a context "baz_123" within the "/foo/bar/" subpath, load security files from `/foo/bar/baz_123/`. +However, if that directory doesn't exist, find the most specific (i.e. longest) context path that _does_ have security files within that subpath (e.g. `/foo/bar/baz_12/`, or `/foo/bar/baz/`, etc.). +Note that it will not search higher in the subpath hierarchy. The desired lookup method can be specified by setting the `$ROS_SECURITY_LOOKUP_TYPE` environment variable to "MATCH_EXACT" (case-sensitive) for the **Exact** method, or "MATCH_PREFIX" (case-sensitive) for the **Prefix** method. From 15680ff1ed20be8b4ad107a66f36f4713d749a7b Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 9 Mar 2020 15:41:42 -0700 Subject: [PATCH 13/49] Update desing for runtime argument --- articles/ros2_dds_security.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 052d2f131..79488e41b 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -144,7 +144,12 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree. +This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--contex-path`, e.g.: + +``` shell +export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" +ros2 run --ros-args --contex-path="/front/camera" +``` ##### Support security files lookup methods @@ -168,8 +173,20 @@ RCL supports specifying the path to a directory containing the set of security f The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. This can be specified by setting the `$ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY`. +Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY` with `--contex-path`. + +Note the following two examples load from the same context path as demonstrated prior: + +``` shell +export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" +ros2 run +``` +``` shell +export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" +export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" +ros2 run --ros-args --contex-path="/spam" +``` ### Support for both permissive and strict enforcement of security From 7f6aae85d8fbf279a8def3eeab22634e14619746 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 9 Mar 2020 16:43:39 -0700 Subject: [PATCH 14/49] Fix typo --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 54321ba39..44fac4763 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -209,7 +209,7 @@ contexts/ ### Context path orthogonal to namespace An alternative to reusing namespaces to hint the context path could be to completely disassociate the two entirely, treating the context path as it's own unique identifier. -However, having to book keep both identifier spaces simulations may introduce to many degrees of freedom that a human could groc or easily introspect via tooling. +However, having to book keep both identifier spaces simultaneously may introduce to many degrees of freedom that a human could groc or easily introspect via tooling. #### `` From b3cad7a720b982cb2f7667d9954a9fc69f2bca1e Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 9 Mar 2020 18:03:29 -0700 Subject: [PATCH 15/49] Simplify context arg --- articles/ros2_dds_security.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 79488e41b..424ae8310 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -144,11 +144,11 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--contex-path`, e.g.: +This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--contex`, e.g.: ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" -ros2 run --ros-args --contex-path="/front/camera" +ros2 run --ros-args --contex="/front/camera" ``` @@ -173,7 +173,7 @@ RCL supports specifying the path to a directory containing the set of security f The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. This can be specified by setting the `$ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY` with `--contex-path`. +Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY` with `--contex`. Note the following two examples load from the same context path as demonstrated prior: @@ -185,7 +185,7 @@ ros2 run ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" -ros2 run --ros-args --contex-path="/spam" +ros2 run --ros-args --contex="/spam" ``` ### Support for both permissive and strict enforcement of security From fc40702c6f704e54deae4919937a5312f3ccea26 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 9 Mar 2020 18:04:46 -0700 Subject: [PATCH 16/49] Update doc per feedback --- articles/ros2_security_contexts.md | 43 +++++++++++++++++------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 44fac4763..08c00d029 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -23,8 +23,12 @@ categories: Security Original Author: {{ page.author }} - -TODO: Some concise overview introduction here +This design document formalizes the integration of contexts in ROS2 with security. +In summary, all context's within a process must load a common context path that contains the unique runtime security artifacts. +Multiple context paths can be encapsulated in a single security policy to accurately model the information flow control. +Users can tune the fidelity of such models by controlling at what scope context paths are applied at deployment. +E.g. one unique context path per OS process, or per OS user, or per device/robot, or per swarm, etc. +The rest of this document details how context paths can be organized and used by convention. ## Concepts @@ -32,7 +36,8 @@ Before detailing the SROS 2 integration of the contexts, the following concepts ### Participant -Participant is the object representing a single entity on the network. In the case of DDS, the ``Participant`` is a DDS DomainParticipant, which has both access control permissions and a security identity. +Participant is the object representing a single entity on the network. +In the case of DDS, the ``Participant`` is a DDS DomainParticipant, which has both access control permissions and a security identity. ### Namespaces @@ -52,7 +57,6 @@ Given the non-negligible overhead incurred of multiple ``Participant``s per proc Based on the DDS Security specification v1.1, a ``Participant`` can only utilise a single security identity; consequently the access control permissions applicable to every node mapped to a given context must be consolidated and combined into a single set of security artifacts. As such, additional tooling and extensions to SROS 2 are necessary to support this new paradigm. - ## Keystore With the additional structure of contexts, it’s perhaps best to take the opportunity to restructure the keystore layout as well. @@ -92,15 +96,19 @@ This directory should be redacted before deploying the keystore onto the target The ``contexts`` directory contains the security artifacts associated with individual contexts, and thus node directories are no longer relevant. Similar to node directories however, the `contexts` folder may still recursively nest sub-paths for organizing separate contexts. +The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention point to this directory. ## Runtime -TODO: Some transition paragraph here about ros launch +Given the normative case where a context within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the context. +To highlight this interdependency, and to help avoid context path collisions, a hierarchy borrowing namespaces is appropriate. +By convention, roslaunch could be used to prefix relative context paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized context paths. +Given the runtime command argument for specifying the fully qualified context path, roslaunch would accordly resolve relative context paths for executables, as defined by launch attributes. ### Unqualified context path -For nodes with unqualified context paths, the context directory will subsequently default to the root level context. +For single process nodes with unqualified context paths, the context directory will subsequently default to the root level context. ``` xml @@ -122,7 +130,7 @@ contexts/ ### Pushed unqualified context path -For nodes with unqualified context paths pushed by a namespace, the context directory will subsequently be pushed to the relative sub-folder. +For single process nodes with unqualified context paths pushed by a namespace, the context directory will subsequently be pushed to the relative sub-folder. ``` xml @@ -154,7 +162,7 @@ contexts/ ### Relatively pushed qualified context path -For nodes with qualified context paths pushed by a namespace, the qualified context directory will subsequently be pushed to the relative sub-folder. +For single process nodes with qualified context paths pushed by a namespace, the qualified context directory will subsequently be pushed to the relative sub-folder. ``` xml @@ -180,7 +188,7 @@ contexts/ ### Fully qualified context path -For nodes with absolute context paths, namespaces do not subsequently push the relative sub-folder. +For single process nodes with absolute context paths, namespaces do not subsequently push the relative sub-folder. ``` xml @@ -209,7 +217,8 @@ contexts/ ### Context path orthogonal to namespace An alternative to reusing namespaces to hint the context path could be to completely disassociate the two entirely, treating the context path as it's own unique identifier. -However, having to book keep both identifier spaces simultaneously may introduce to many degrees of freedom that a human could groc or easily introspect via tooling. +Having to book keep both identifier spaces simultaneously may introduce too many degrees of freedom that a human could groc or easily introspect via tooling. +However, doing so would still be possible given such namespacing conventions are bypassable in roslaunch and not implemented directly in RCL. #### `` @@ -221,14 +230,12 @@ Keeps pushing contexts close/readable to pushing of namespaces. TODO: Describe added `push_ros_context` element. Keeps pushing context path independent/flexable from namespaces. - ## Concerns ### Multiple namespaces per context -For circumstances where users may compose multiple nodes of dissimilar namespaces into a single context, the user must subsequently specify a common fully qualified context path for each node to compose, as the varying different namespaces would not push to a common context. -For circumstances where the context path is orthogonal to node namespace, the use of fully qualifying all relevant nodes is could be tedious, but could perhaps could still be parametrized via the use of ``, and `` substitution and expansion. - +For circumstances where users may compose multiple nodes of dissimilar namespaces into a single context, the user must still subsequently specify a common context path that is applicable for all nodes composed. +For circumstances where the context path is orthogonal to node namespace, the use of fully qualifying all relevant context paths could be tedious, but could perhaps could still be parametrized via the use of ``, and `` substitution and expansion. ### Modeling permissions of nodes in a process v.s. permission of the middleware ``Participant`` @@ -248,10 +255,9 @@ If a process contains a single context, this reconciles the permissions of a ``P However, should multiple contexts be used per process, then such security guaranties are again lost because both contexts will share the same memory space. Thus it should be asked whether if multiple contexts per process should even be supported. - In summary, the distinction here is that before, the composition of multiple permissions could not be conveyed to the tooling. Whether nodes could gain the permission of others in the same process space is not the hinge point of note; it's the fact that such side effects could not be formally modeled or accounted for by the designer. -It will now be possible with contexts, however allowing for multiple contexts per process will reintroduce and exacerbates the same modeling inaccuracies. +It will now be possible with contexts, however allowing for multiple contexts per process that load separate credentials would reintroduce and exacerbate the same modeling inaccuracies. ### Composable launchfile includes @@ -262,12 +268,13 @@ Authors can selectively choose what attributes to expose as input arguments, whi In case of contexts, it is not inherently clear what best practices either package authors or users should employ to retain a composable and intuitive launchfile structure. E.g: Should authors parametrize context paths for each node as input arguments? Should users push namespaces of included launchfiles to separate contexts? -Should the setting of security environment variables be discouraged from within launchfiles, limiting the use of simple static analysis of launchfiles combined with Node IDL for procedural context generation? + +To be sure though, the setting of security environment variables from within launchfiles should be discouraged, as this would restrict the use of static analysis of launchfiles combined with Node IDL for procedural context generation. ### Composable nodes in container Given that containers can be dynamic, where nodes can be added or removed at runtime, there is perhaps some question as to how containers should integrate with secure contexts. -The most straightforward approach is perhaps only specifying the context wherever the container is first defined/launched, applying to the container participant, thus to all nodes/components inside that container. +In roslaunch, the namespace in scope at the container's instantiation could be used to resolve the container's specified relative context path, thus to all nodes/components inside that container. This should be further deliberated when eventually extending the launch API for containers. ### Migration for RMW implementations From 4df233b63485ac0b9938de7054c084654c3dff50 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Tue, 10 Mar 2020 10:48:11 -0700 Subject: [PATCH 17/49] Fix typos --- articles/ros2_dds_security.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 424ae8310..b8f448945 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -144,11 +144,11 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--contex`, e.g.: +This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--context`, e.g.: ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" -ros2 run --ros-args --contex="/front/camera" +ros2 run --ros-args --context="/front/camera" ``` @@ -173,7 +173,7 @@ RCL supports specifying the path to a directory containing the set of security f The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. This can be specified by setting the `$ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY` with `--contex`. +Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY` with `--context`. Note the following two examples load from the same context path as demonstrated prior: @@ -185,7 +185,7 @@ ros2 run ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" -ros2 run --ros-args --contex="/spam" +ros2 run --ros-args --context="/spam" ``` ### Support for both permissive and strict enforcement of security From a01de1fce0108c6666154f1d6f35192d63d488aa Mon Sep 17 00:00:00 2001 From: ruffsl Date: Tue, 10 Mar 2020 12:15:31 -0700 Subject: [PATCH 18/49] Removing shell specific $ from variables --- articles/ros2_dds_security.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index b8f448945..3dd2d6922 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -144,7 +144,7 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--context`, e.g.: +This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--context`, e.g.: ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" @@ -164,7 +164,7 @@ For example, given a context "baz_123" within the "/foo/bar/" subpath, load secu However, if that directory doesn't exist, find the most specific (i.e. longest) context path that _does_ have security files within that subpath (e.g. `/foo/bar/baz_12/`, or `/foo/bar/baz/`, etc.). Note that it will not search higher in the subpath hierarchy. -The desired lookup method can be specified by setting the `$ROS_SECURITY_LOOKUP_TYPE` environment variable to "MATCH_EXACT" (case-sensitive) for the **Exact** method, or "MATCH_PREFIX" (case-sensitive) for the **Prefix** method. +The desired lookup method can be specified by setting the `ROS_SECURITY_LOOKUP_TYPE` environment variable to "MATCH_EXACT" (case-sensitive) for the **Exact** method, or "MATCH_PREFIX" (case-sensitive) for the **Prefix** method. #### Manual specification @@ -172,8 +172,8 @@ The desired lookup method can be specified by setting the `$ROS_SECURITY_LOOKUP_ RCL supports specifying the path to a directory containing the set of security files for the exact context instance that needs to be launched. The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. -This can be specified by setting the `$ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY` with `--context`. +This can be specified by setting the `ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. +Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--context`. Note the following two examples load from the same context path as demonstrated prior: @@ -196,7 +196,7 @@ Contexts with the security features enabled will not communicate with contexts t This is the default behavior. - **Strict mode**: Try to find security files, and if they can't be found, fail to run the context. -The type of mode desired can be specified by setting the `$ROS_SECURITY_STRATEGY` environment variable to "Enforce" (case-sensitive) for strict mode, and anything else for permissive mode. +The type of mode desired can be specified by setting the `ROS_SECURITY_STRATEGY` environment variable to "Enforce" (case-sensitive) for strict mode, and anything else for permissive mode. ### Support for a master "on/off" switch for all SROS 2 features @@ -204,7 +204,7 @@ The type of mode desired can be specified by setting the `$ROS_SECURITY_STRATEGY In addition to the supported features just discussed, RCL also supports a master shutoff for security features for easy experimentation. If it's turned off (the default), none of the above security features will be enabled. -In order to enable SROS 2, set the `$ROS_SECURITY_ENABLE` environment variable to "true" (case-sensitive). +In order to enable SROS 2, set the `ROS_SECURITY_ENABLE` environment variable to "true" (case-sensitive). To disable, set to any other value. From 2729121fd69e1cca815557021641caf157d6d89d Mon Sep 17 00:00:00 2001 From: Ruffin Date: Tue, 10 Mar 2020 12:18:31 -0700 Subject: [PATCH 19/49] Fix typo Co-Authored-By: Mikael Arguedas --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 08c00d029..c1a4c1bd2 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -24,7 +24,7 @@ categories: Security Original Author: {{ page.author }} This design document formalizes the integration of contexts in ROS2 with security. -In summary, all context's within a process must load a common context path that contains the unique runtime security artifacts. +In summary, all contexts within a process must load a common context path that contains the unique runtime security artifacts. Multiple context paths can be encapsulated in a single security policy to accurately model the information flow control. Users can tune the fidelity of such models by controlling at what scope context paths are applied at deployment. E.g. one unique context path per OS process, or per OS user, or per device/robot, or per swarm, etc. From 58309cf2d0aad11918824d6ab1130e53e42cf3a4 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Tue, 10 Mar 2020 12:18:48 -0700 Subject: [PATCH 20/49] Editorial rephrasing Co-Authored-By: Mikael Arguedas --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index c1a4c1bd2..aad8fee88 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -23,7 +23,7 @@ categories: Security Original Author: {{ page.author }} -This design document formalizes the integration of contexts in ROS2 with security. +This design document formalizes the integration of contexts in ROS 2 with security. In summary, all contexts within a process must load a common context path that contains the unique runtime security artifacts. Multiple context paths can be encapsulated in a single security policy to accurately model the information flow control. Users can tune the fidelity of such models by controlling at what scope context paths are applied at deployment. From 77ebfbdc45cb90b61d1b158d5e7e174020623c0a Mon Sep 17 00:00:00 2001 From: Ruffin Date: Tue, 10 Mar 2020 12:19:35 -0700 Subject: [PATCH 21/49] Fix typo Co-Authored-By: Mikael Arguedas --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index aad8fee88..1ac476adc 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -104,7 +104,7 @@ The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention poin Given the normative case where a context within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the context. To highlight this interdependency, and to help avoid context path collisions, a hierarchy borrowing namespaces is appropriate. By convention, roslaunch could be used to prefix relative context paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized context paths. -Given the runtime command argument for specifying the fully qualified context path, roslaunch would accordly resolve relative context paths for executables, as defined by launch attributes. +Given the runtime command argument for specifying the fully qualified context path, ros2launch would accordingly resolve relative context paths for executables, as defined by launch attributes. ### Unqualified context path From d7841342d26cc0886d98fd4bc6c7323bb18796f8 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Tue, 10 Mar 2020 12:20:02 -0700 Subject: [PATCH 22/49] Editorial rephrasing Co-Authored-By: Mikael Arguedas --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 1ac476adc..8d42f8f1d 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -274,7 +274,7 @@ To be sure though, the setting of security environment variables from within lau ### Composable nodes in container Given that containers can be dynamic, where nodes can be added or removed at runtime, there is perhaps some question as to how containers should integrate with secure contexts. -In roslaunch, the namespace in scope at the container's instantiation could be used to resolve the container's specified relative context path, thus to all nodes/components inside that container. +In ros2launch, the namespace in scope at the container's instantiation could be used to resolve the container's specified relative context path, thus to all nodes/components inside that container. This should be further deliberated when eventually extending the launch API for containers. ### Migration for RMW implementations From 0d6e8e84e6cdf90f27c7cf652030cf79bd8ab0a8 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Tue, 10 Mar 2020 12:20:25 -0700 Subject: [PATCH 23/49] Editorial rephrasing Co-Authored-By: Mikael Arguedas --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 8d42f8f1d..acb76261f 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -103,7 +103,7 @@ The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention poin Given the normative case where a context within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the context. To highlight this interdependency, and to help avoid context path collisions, a hierarchy borrowing namespaces is appropriate. -By convention, roslaunch could be used to prefix relative context paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized context paths. +By convention, ros2launch could be used to prefix relative context paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized context paths. Given the runtime command argument for specifying the fully qualified context path, ros2launch would accordingly resolve relative context paths for executables, as defined by launch attributes. ### Unqualified context path From 795acf7b1d63da5b000bbd902b2e8dea5146f6c6 Mon Sep 17 00:00:00 2001 From: Ruffin Date: Tue, 10 Mar 2020 12:21:14 -0700 Subject: [PATCH 24/49] Editorial correction Co-Authored-By: Mikael Arguedas --- articles/ros2_dds_security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 3dd2d6922..52aa66c10 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -125,7 +125,7 @@ Let's delve further into these. #### Directory tree of all security files -RCL supports finding security files in one directory that is within the root context directory structure corresponding to the fully-qualified path of every context. +RCL supports finding security files in one directory that is within the root `contexts` directory structure corresponding to the fully-qualified path of every context. For example, for the `/front/camera` context, the directory structure would look like: From a1f3e650f642eef5435a0652048fefb63e6c4967 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Tue, 10 Mar 2020 12:28:45 -0700 Subject: [PATCH 25/49] Restore notes on synlinks --- articles/ros2_security_contexts.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index acb76261f..fd95f07da 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -76,8 +76,8 @@ keystore │ └── ca.key.pem └── public ├── ca.cert.pem - ├── identity_ca.cert.pem - └── permissions_ca.cert.pem + ├── identity_ca.cert.pem -> ca.cert.pem + └── permissions_ca.cert.pem -> ca.cert.pem ``` @@ -85,7 +85,7 @@ keystore The ``public`` directory contains anything permissible as public, such as public certificates for the identity or permissions certificate authorities. As such, this can be given read access to all executables. -Note that in the default case, both the `identity_ca` and `permissions_ca` are the same CA certificate. +Note that in the default case, both the `identity_ca` and `permissions_ca` points to the same CA certificate. ### ``private`` @@ -122,9 +122,9 @@ $ tree contexts/ contexts/ ├── cert.pem ├── governance.p7s -├── identity_ca.cert.pem +├── identity_ca.cert.pem -> ../public/identity_ca.cert.pem ├── key.pem -├── permissions_ca.cert.pem +├── permissions_ca.cert.pem -> ../public/permissions_ca.cert.pem └── permissions.p7s ``` @@ -160,6 +160,8 @@ contexts/ └── permissions.p7s ``` +> Symbolic links suppressed for readability + ### Relatively pushed qualified context path For single process nodes with qualified context paths pushed by a namespace, the qualified context directory will subsequently be pushed to the relative sub-folder. From 2a2122befe145639201628ef6e580ea050fa16cf Mon Sep 17 00:00:00 2001 From: ruffsl Date: Tue, 10 Mar 2020 17:31:49 -0700 Subject: [PATCH 26/49] Remove the use of alternate lookup methods It's now redundan given context paths can be independent of namespace https://github.com/ros2/design/pull/274#discussion_r390656506 --- articles/ros2_dds_security.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 52aa66c10..2a48895aa 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -151,22 +151,6 @@ export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" ros2 run --ros-args --context="/front/camera" ``` - -##### Support security files lookup methods - -If using the directory tree approach to organize security files, RCL supports two different methods for looking up a given context instance's security files in the tree: - -- **Exact**: Only load security files from a directory exactly matching the fully-qualified path of the context. -For example, given a context "baz_123" within the "/foo/bar/" subpath, only load security files from `/foo/bar/baz_123/`. -This is the default behavior. -- **Prefix**: Attempt to load the most specific set of security files, but if they can't be found, check for security files under a less-specific context path. -For example, given a context "baz_123" within the "/foo/bar/" subpath, load security files from `/foo/bar/baz_123/`. -However, if that directory doesn't exist, find the most specific (i.e. longest) context path that _does_ have security files within that subpath (e.g. `/foo/bar/baz_12/`, or `/foo/bar/baz/`, etc.). -Note that it will not search higher in the subpath hierarchy. - -The desired lookup method can be specified by setting the `ROS_SECURITY_LOOKUP_TYPE` environment variable to "MATCH_EXACT" (case-sensitive) for the **Exact** method, or "MATCH_PREFIX" (case-sensitive) for the **Prefix** method. - - #### Manual specification RCL supports specifying the path to a directory containing the set of security files for the exact context instance that needs to be launched. From 7473326b3658e647bd048f742b77a49bf825d5f3 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Tue, 10 Mar 2020 18:33:58 -0700 Subject: [PATCH 27/49] Editorial rephrasing --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index fd95f07da..21b01e680 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -24,7 +24,7 @@ categories: Security Original Author: {{ page.author }} This design document formalizes the integration of contexts in ROS 2 with security. -In summary, all contexts within a process must load a common context path that contains the unique runtime security artifacts. +In summary, all context instances within a process must load a common context path that contains the runtime security artifacts unique to that context path, yet each process may not necessarily have a unique context path. Multiple context paths can be encapsulated in a single security policy to accurately model the information flow control. Users can tune the fidelity of such models by controlling at what scope context paths are applied at deployment. E.g. one unique context path per OS process, or per OS user, or per device/robot, or per swarm, etc. From 8e3fa5630666421e014c223ad1511390b33edac3 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 13:08:34 -0700 Subject: [PATCH 28/49] Update policy schema to match that currently used --- articles/ros2_access_control_policies/policy.xsd | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/articles/ros2_access_control_policies/policy.xsd b/articles/ros2_access_control_policies/policy.xsd index 6b7906750..09a28acbf 100644 --- a/articles/ros2_access_control_policies/policy.xsd +++ b/articles/ros2_access_control_policies/policy.xsd @@ -12,7 +12,7 @@ - + @@ -29,13 +29,15 @@ - - - - - + + + + + + + - + From 1401d5774bcdcf91a9cc334c05f27c1c942860e7 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 13:11:58 -0700 Subject: [PATCH 29/49] Update key argument name for security context --- articles/ros2_dds_security.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 2a48895aa..87dfe4212 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -144,11 +144,11 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--context`, e.g.: +This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--security-context`, e.g.: ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" -ros2 run --ros-args --context="/front/camera" +ros2 run --ros-args --security-context="/front/camera" ``` #### Manual specification @@ -157,7 +157,7 @@ RCL supports specifying the path to a directory containing the set of security f The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. This can be specified by setting the `ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--context`. +Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--security-context`. Note the following two examples load from the same context path as demonstrated prior: @@ -169,7 +169,7 @@ ros2 run ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" -ros2 run --ros-args --context="/spam" +ros2 run --ros-args --security-context="/spam" ``` ### Support for both permissive and strict enforcement of security From f75310f7e658bd6fa9e8b22d5e4a0e37f3498f42 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 13:13:04 -0700 Subject: [PATCH 30/49] Publish Security Contexts document --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 21b01e680..f39165068 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -8,7 +8,7 @@ author: > [Ruffin White](https://github.com/ruffsl), [Mikael Arguedas](https://github.com/mikaelarguedas) -published: false +published: true categories: Security --- From 6315e5bfc34fcc0ddca34a98bace015b6c1e55e6 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 13:22:31 -0700 Subject: [PATCH 31/49] Update context directory overide env name --- articles/ros2_dds_security.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 87dfe4212..e6bb12f1b 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -156,19 +156,19 @@ ros2 run --ros-args --security-context="/front/camera" RCL supports specifying the path to a directory containing the set of security files for the exact context instance that needs to be launched. The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. -This can be specified by setting the `ROS_SECURITY_CONTEXT_DIRECTORY` environment variable to point to the directory containing the security files. +This can be specified by setting the `ROS_SECURITY_DIRECTORY_OVERRIDE` environment variable to point to the directory containing the security files. Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--security-context`. Note the following two examples load from the same context path as demonstrated prior: ``` shell -export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" +export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/contexts/front/camera" ros2 run ``` ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" -export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera" +export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/contexts/front/camera" ros2 run --ros-args --security-context="/spam" ``` From 61ed2f973dec56e1c8152fbca4b5d94cb42fbc98 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 13:38:08 -0700 Subject: [PATCH 32/49] Tuchup grammar --- articles/ros2_security_contexts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index f39165068..a25259be4 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -62,7 +62,7 @@ As such, additional tooling and extensions to SROS 2 are necessary to support th With the additional structure of contexts, it’s perhaps best to take the opportunity to restructure the keystore layout as well. Rather than a flat directory of namespaced node security directories, we can push all such security directories down into a designated `contexts` sub-folder. Similarly, private and public keystore materials can also be pushed down into their own respective sub-folders within the root keystore directory. -This is reminiscent of the pattern used earlier Keymint [1]. +This is reminiscent of the pattern used earlier in Keymint [1]. ``` From b8dc3d50e413f30744de73abbf92b990223c3d25 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 13:38:27 -0700 Subject: [PATCH 33/49] Resolve TODOs --- articles/ros2_security_contexts.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index a25259be4..0f4d73036 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -224,13 +224,13 @@ However, doing so would still be possible given such namespacing conventions are #### `` -TODO: Describe added `context` attribute to `push_ros_namespace` element. -Keeps pushing contexts close/readable to pushing of namespaces. +One such approach could be done by adding a `context` attribute to `push_ros_namespace` element. +This also keeps the pushing of contexts close/readable to pushing of namespaces. #### `` -TODO: Describe added `push_ros_context` element. -Keeps pushing context path independent/flexable from namespaces. +Another alternative approach could be to add an entirely new `push_ros_context` element. +This could ensure the pushing of context path independent/flexable from namespaces. ## Concerns From 09e5c9e3aeca13870e0146a9a511dba767f03ed4 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Fri, 3 Apr 2020 14:19:56 -0700 Subject: [PATCH 34/49] Update story for ROS_SECURITY_ROOT_DIRECTORY --- articles/ros2_dds_security.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index e6bb12f1b..758b3bcdb 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -125,15 +125,18 @@ Let's delve further into these. #### Directory tree of all security files -RCL supports finding security files in one directory that is within the root `contexts` directory structure corresponding to the fully-qualified path of every context. +RCL supports finding security files in one directory that is inside the reserved `contexts` subfolder, within the root keystore, corresponding to the fully-qualified path of every context. For example, for the `/front/camera` context, the directory structure would look like: - └── front - └── camera - ├── cert.pem - ├── key.pem - ├── ... + ├── contexts + │ └── front + │ └── camera + │ ├── cert.pem + │ ├── key.pem + │ ├── ... + └── public + ├── ... The set of files expected within each context instance directory are: @@ -144,10 +147,10 @@ The set of files expected within each context instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the contexts directory tree, and then specifying the context path using the `--ros-args` runtime argument `--security-context`, e.g.: +This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the keystore directory tree, and then specifying the context path using the `--ros-args` runtime argument `--security-context`, e.g.: ``` shell -export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts" +export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore" ros2 run --ros-args --security-context="/front/camera" ``` From 77e64b13891009adfc1c4cb4d37f78d976e1f055 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Wed, 8 Apr 2020 13:54:05 -0700 Subject: [PATCH 35/49] Context -> Enclave --- articles/ros2_access_control_policies/policy.xsd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/ros2_access_control_policies/policy.xsd b/articles/ros2_access_control_policies/policy.xsd index 09a28acbf..da0e7c8fe 100644 --- a/articles/ros2_access_control_policies/policy.xsd +++ b/articles/ros2_access_control_policies/policy.xsd @@ -10,18 +10,18 @@ - + - + - + - + From 41a27659ac5e61e29bf5c9c10e54b382b667e1f8 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Wed, 8 Apr 2020 14:05:34 -0700 Subject: [PATCH 36/49] Context -> Enclave --- articles/ros2_access_control_policies.md | 26 ++++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/articles/ros2_access_control_policies.md b/articles/ros2_access_control_policies.md index ad9879357..c2d91c60d 100644 --- a/articles/ros2_access_control_policies.md +++ b/articles/ros2_access_control_policies.md @@ -32,7 +32,7 @@ A policy serves as a high-level abstraction of privileges associated with attrib ## Concepts Before detailing the SROS 2 policy design of the [access control](https://en.wikipedia.org/wiki/Computer_access_control), by which the system constrains the ability of a subject to access an object, it is important to establish a few concepts useful in formalizing the design approach in terms of security. -In this context, a subject may be thought of as a participant on a distributed data-bus (e.g. a ROS node in the computation graph), whereas an object may be an instance of a particular subsystem (e.g. a ROS topic), and access is defined as the capability to act upon that object (e.g. publish or subscribe). +In this setting, a subject may be thought of as a participant on a distributed data-bus (e.g. a ROS node in the computation graph), whereas an object may be an instance of a particular subsystem (e.g. a ROS topic), and access is defined as the capability to act upon that object (e.g. publish or subscribe). ### Mandatory Access Control @@ -99,28 +99,28 @@ Attributes: - **version**: declared version of schema version in use - Allows for advancing future revisions of the schema -### `` Tag +### `` Tag -Encapsulates a sequence of unique contexts. +Encapsulates a sequence of unique enclaves. This method of nesting sequences allows for additional tags to be extended to the `` root. -### `` Tag +### `` Tag Encapsulates a collection of profiles. -This is specific to a context as determined by associative attributes. +This is specific to a enclave as determined by associative attributes. Attributes: -- **path**: Fully qualified context path +- **path**: Fully qualified enclave path -Given that multiple nodes can be composed into a single process, a context is used to contain the collection of profiles of all respective nodes. -A context may therefore be considered the union of contained profiles. -Note that the union of profiles within a context will result in denied privileges of any profile to supersede all allowed privileges for every profile. +Given that multiple nodes can be composed into a single process, a enclave is used to contain the collection of profiles of all respective nodes. +A enclave may therefore be considered the union of contained profiles. +Note that the union of profiles within a enclave will result in denied privileges of any profile to supersede all allowed privileges for every profile. See section `` Tag for more info on MAC is applied. ### `` Tag Encapsulates a sequence of unique profiles and designated metadata. -This method of nesting sequences allows for additional tags to be extended to the `` root, as well as associating particular metadata or constraints to the contained profile elements. +This method of nesting sequences allows for additional tags to be extended to the `` root, as well as associating particular metadata or constraints to the contained profile elements. Attributes: - **type**: Specifies the transport type of profiles and metadata @@ -149,7 +149,7 @@ There can only one `metadata` element per `profiles` parent element. Attributes: - To be defined -Given the use cases for bridge interfaces where a context's credentials may be used to interconnect across multiple transports or to transport specific domains, it may be necessary to qualify certain profile sequences with particular constraints, while doing so multiple times for separate profiles per context. +Given the use cases for bridge interfaces where a enclave's credentials may be used to interconnect across multiple transports or to transport specific domains, it may be necessary to qualify certain profile sequences with particular constraints, while doing so multiple times for separate profiles per enclave. This allows advanced users to holistically control the intersect of permissions across transport domains, while retaining accurate model fidelity of security permissions. Given how security sensitive bridge interfaces are and the attack surface they expose, it is vital that information flow control within a bridge remains formally verifiable for safe and secure operation. @@ -320,8 +320,8 @@ Yet, if the intended purpose of SROS 2 policy becomes that of an intermediate re ROS 2 allows for the remapping of many namespaced subsystems at runtime, such as when reusing launch files to orchestrate larger applications. While it is perhaps unreasonable to expect this dynamic flexibility from staticky provisioned permissions without allocating such capabilities prior, it should be made possible to infer the necessary capabilities from composed launch files and similar orchestrations. -Static analysis of such remapping in conjunction with the context of the nominal requirements of respective nodes could be used to auto generate the new satisfactory policies. -However, inferring such context from the source code could be equated to the halting problem. +Static analysis of such remapping in conjunction with the setting of the nominal requirements of respective nodes could be used to auto generate the new satisfactory policies. +However, inferring such policies from the source code could be equated to the halting problem. Thus, it stands to reason nodes could instead provide a manifest or IDL defining these nominal requirements so that permission may as easily be remapped, at least at design time. ## References From 036d15ed6f8a4a706487c3e7ebcda8b35f290825 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Wed, 8 Apr 2020 14:34:09 -0700 Subject: [PATCH 37/49] Context -> Enclave --- articles/ros2_dds_security.md | 46 +++++++++++++++++------------------ 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 758b3bcdb..e57ef69aa 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -45,7 +45,7 @@ Let's delve a little further into those first three plugins. ## Authentication -The **Authentication** plugin (see section 8.3 of the [DDS-Security spec][dds_security]) is central to the entire SPI architecture, as it provides the concept of a confirmed identity without which further enforcement would be impossible (e.g. it would be awfully hard to make sure a given ROS context could only access specific topics if it was impossible to securely determine which context it was). +The **Authentication** plugin (see section 8.3 of the [DDS-Security spec][dds_security]) is central to the entire SPI architecture, as it provides the concept of a confirmed identity without which further enforcement would be impossible (e.g. it would be awfully hard to make sure a given ROS identity could only access specific topics if it was impossible to securely determine which identity it was). The SPI architecture allows for a number of potential authentication schemes, but ROS 2 uses the builtin authentication plugin (called "DDS:Auth:PKI-DH", see section 9.3 of the [DDS-Security spec][dds_security]), which uses the proven Public Key Infrastructure (PKI). It requires a public and private key per domain participant, as well as an x.509 certificate that binds the participant's public key to a specific name. @@ -114,7 +114,7 @@ Let's discuss each of these in turn. ### Security files for each domain participant As stated earlier, the DDS-Security plugins require a set of security files (e.g. keys, governance and permissions files, etc.) per domain participant. -Domain participants map to a specific instance of a context in ROS 2, so each context requires a set of these files. +Domain participants map to a process in ROS 2, so each process requires a set of these files. RCL supports being pointed at a directory containing security files in two different ways: - Directory tree of all security files. @@ -125,11 +125,11 @@ Let's delve further into these. #### Directory tree of all security files -RCL supports finding security files in one directory that is inside the reserved `contexts` subfolder, within the root keystore, corresponding to the fully-qualified path of every context. -For example, for the `/front/camera` context, the directory structure would look like: +RCL supports finding security files in one directory that is inside the reserved `enclaves` subfolder, within the root keystore, corresponding to the fully-qualified path of every enclave. +For example, for the `/front/camera` enclave, the directory structure would look like: - ├── contexts + ├── enclaves │ └── front │ └── camera │ ├── cert.pem @@ -138,50 +138,50 @@ For example, for the `/front/camera` context, the directory structure would look └── public ├── ... -The set of files expected within each context instance directory are: +The set of files expected within each enclave instance directory are: - **identity_ca.cert.pem**: The x.509 certificate of the CA trusted by the **Authentication** plugin (the "Identity" CA). -- **cert.pem**: The x.509 certificate of this context instance (signed by the Identity CA). -- **key.pem**: The private key of this context instance. +- **cert.pem**: The x.509 certificate of this enclave instance (signed by the Identity CA). +- **key.pem**: The private key of this enclave instance. - **permissions_ca.cert.pem**: The x.509 certificate of the CA trusted by the **Access control** plugin (the "Permissions" CA). - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). -- **permissions.p7s**: The XML document that specifies the permissions of this particular context instance to the **Access control** plugin (also signed by the Permissions CA). +- **permissions.p7s**: The XML document that specifies the permissions of this particular enclave instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the keystore directory tree, and then specifying the context path using the `--ros-args` runtime argument `--security-context`, e.g.: +This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the keystore directory tree, and then specifying the enclave path using the `--ros-args` runtime argument `--security-enclave`, e.g.: ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore" -ros2 run --ros-args --security-context="/front/camera" +ros2 run --ros-args --security-enclave="/front/camera" ``` #### Manual specification -RCL supports specifying the path to a directory containing the set of security files for the exact context instance that needs to be launched. -The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual context instance directories. +RCL supports specifying the path to a directory containing the set of security files for the process that needs to be launched. +The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual enclave directories. This can be specified by setting the `ROS_SECURITY_DIRECTORY_OVERRIDE` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--security-context`. +Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--security-enclave`. -Note the following two examples load from the same context path as demonstrated prior: +Note the following two examples load from the same enclave path as demonstrated prior: ``` shell -export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/contexts/front/camera" +export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" ros2 run ``` ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" -export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/contexts/front/camera" -ros2 run --ros-args --security-context="/spam" +export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" +ros2 run --ros-args --security-enclave="/spam" ``` ### Support for both permissive and strict enforcement of security -Contexts with the security features enabled will not communicate with contexts that don't, but what should RCL do if one tries to launch a context that has no discernable keys/permissions/etc.? It has two options: +Processes with the security features enabled will not communicate with processes that don't, but what should RCL do if one tries to launch a process that has no discernable enclave with keys/permissions/etc.? It has two options: -- **Permissive mode**: Try to find security files, and if they can't be found, launch the context without enabling any security features. +- **Permissive mode**: Try to find security files, and if they can't be found, launch the process without enabling any security features. This is the default behavior. -- **Strict mode**: Try to find security files, and if they can't be found, fail to run the context. +- **Strict mode**: Try to find security files, and if they can't be found, fail to run the process. The type of mode desired can be specified by setting the `ROS_SECURITY_STRATEGY` environment variable to "Enforce" (case-sensitive) for strict mode, and anything else for permissive mode. @@ -203,9 +203,9 @@ However, the [SROS 2 CLI](https://github.com/ros2/sros2) should include a tool ` - Create Identity and Permissions CA. - Create directory tree containing all security files. -- Create a new identity for a given context instance, generating a keypair and signing its x.509 certificate using the Identity CA. +- Create a new identity for a given enclave, generating a keypair and signing its x.509 certificate using the Identity CA. - Create a governance file that will encrypt all DDS traffic by default. -- Support specifying context instance permissions [in familiar ROS terms](/articles/ros2_access_control_policies.html) which are then automatically converted into low-level DDS permissions. +- Support specifying enclave permissions [in familiar ROS terms](/articles/ros2_access_control_policies.html) which are then automatically converted into low-level DDS permissions. - Support automatically discovering required permissions from a running ROS system. From 987a916db723b88887bc141ee9013acf96ea95c7 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Wed, 8 Apr 2020 15:45:38 -0700 Subject: [PATCH 38/49] Context -> Enclave --- articles/ros2_security_contexts.md | 128 ++++++++++++++--------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_contexts.md index 0f4d73036..93a3b7a44 100644 --- a/articles/ros2_security_contexts.md +++ b/articles/ros2_security_contexts.md @@ -1,9 +1,9 @@ --- layout: default -title: ROS 2 Security Contexts -permalink: articles/ros2_security_contexts.html +title: ROS 2 Security Enclaves +permalink: articles/ros2_security_enclaves.html abstract: - This article specifies the integration between security and contexts. + This article specifies the integration of security enclaves. author: > [Ruffin White](https://github.com/ruffsl), [Mikael Arguedas](https://github.com/mikaelarguedas) @@ -23,16 +23,16 @@ categories: Security Original Author: {{ page.author }} -This design document formalizes the integration of contexts in ROS 2 with security. -In summary, all context instances within a process must load a common context path that contains the runtime security artifacts unique to that context path, yet each process may not necessarily have a unique context path. -Multiple context paths can be encapsulated in a single security policy to accurately model the information flow control. -Users can tune the fidelity of such models by controlling at what scope context paths are applied at deployment. -E.g. one unique context path per OS process, or per OS user, or per device/robot, or per swarm, etc. -The rest of this document details how context paths can be organized and used by convention. +This design document formalizes the integration of ROS 2 with security enclaves. +In summary, all processes must load a common enclave that contains the runtime security artifacts unique to that enclave, yet each process may not necessarily have a unique enclave. +Multiple enclaves can be encapsulated in a single security policy to accurately model the information flow control. +Users can tune the fidelity of such models by controlling at what scope enclaves are applied at deployment. +E.g. one unique enclave per OS process, or per OS user, or per device/robot, or per swarm, etc. +The rest of this document details how enclaves can be organized and used by convention. ## Concepts -Before detailing the SROS 2 integration of the contexts, the following concepts are introduced. +Before detailing the SROS 2 integration of the enclaves, the following concepts are introduced. ### Participant @@ -54,13 +54,13 @@ With the advent of ROS 2, multiple nodes may now be composed into one process fo Previously however, each node would retain it's one to one mapping to a separate middleware ``Participant``. Given the non-negligible overhead incurred of multiple ``Participant``s per process, a change was introduced to map a single ``Participant`` to a context, and allow for multiple nodes to share that context. -Based on the DDS Security specification v1.1, a ``Participant`` can only utilise a single security identity; consequently the access control permissions applicable to every node mapped to a given context must be consolidated and combined into a single set of security artifacts. +Based on the DDS Security specification v1.1, a ``Participant`` can only utilise a single security identity; consequently the access control permissions applicable to every node mapped to a given context must be consolidated and combined into a single set of security artifacts, or enclave. As such, additional tooling and extensions to SROS 2 are necessary to support this new paradigm. ## Keystore -With the additional structure of contexts, it’s perhaps best to take the opportunity to restructure the keystore layout as well. -Rather than a flat directory of namespaced node security directories, we can push all such security directories down into a designated `contexts` sub-folder. +With the addition of contexts, it’s perhaps best to take the opportunity to restructure the keystore layout as well. +Rather than a flat directory of namespaced node security directories, we can push all such security directories down into a designated `enclaves` sub-folder. Similarly, private and public keystore materials can also be pushed down into their own respective sub-folders within the root keystore directory. This is reminiscent of the pattern used earlier in Keymint [1]. @@ -68,7 +68,7 @@ This is reminiscent of the pattern used earlier in Keymint [1]. ``` $ tree keystore/ keystore -├── contexts +├── enclaves │ └── ... │ └── ... ├── private @@ -92,23 +92,23 @@ Note that in the default case, both the `identity_ca` and `permissions_ca` point The ``private`` directory contains anything permissable as private, such as private key material for aforementioned certificate authorities. This directory should be redacted before deploying the keystore onto the target device/robot. -### ``contexts`` +### ``enclaves`` -The ``contexts`` directory contains the security artifacts associated with individual contexts, and thus node directories are no longer relevant. -Similar to node directories however, the `contexts` folder may still recursively nest sub-paths for organizing separate contexts. +The ``enclaves`` directory contains the security artifacts associated with individual enclaves, and thus node directories are no longer relevant. +Similar to node directories however, the `enclaves` folder may still recursively nest sub-paths for organizing separate enclaves. The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention point to this directory. ## Runtime -Given the normative case where a context within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the context. -To highlight this interdependency, and to help avoid context path collisions, a hierarchy borrowing namespaces is appropriate. -By convention, ros2launch could be used to prefix relative context paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized context paths. -Given the runtime command argument for specifying the fully qualified context path, ros2launch would accordingly resolve relative context paths for executables, as defined by launch attributes. +Given the normative case where a enclave within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the enclave. +To highlight this interdependency, and to help avoid enclave path collisions, a hierarchy borrowing namespaces is appropriate. +By convention, ros2launch could be used to prefix relative enclave paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized enclave paths. +Given the runtime command argument for specifying the fully qualified enclave path, ros2launch would accordingly resolve relative enclave paths for executables, as defined by launch attributes. -### Unqualified context path +### Unqualified enclave path -For single process nodes with unqualified context paths, the context directory will subsequently default to the root level context. +For single process nodes with unqualified enclave paths, the enclave directory will subsequently default to the root level enclave. ``` xml @@ -118,8 +118,8 @@ For single process nodes with unqualified context paths, the context directory w ``` ``` -$ tree contexts/ -contexts/ +$ tree enclaves/ +enclaves/ ├── cert.pem ├── governance.p7s ├── identity_ca.cert.pem -> ../public/identity_ca.cert.pem @@ -128,9 +128,9 @@ contexts/ └── permissions.p7s ``` -### Pushed unqualified context path +### Pushed unqualified enclave path -For single process nodes with unqualified context paths pushed by a namespace, the context directory will subsequently be pushed to the relative sub-folder. +For single process nodes with unqualified enclave paths pushed by a namespace, the enclave directory will subsequently be pushed to the relative sub-folder. ``` xml @@ -143,8 +143,8 @@ For single process nodes with unqualified context paths pushed by a namespace, t ``` ``` -$ tree --dirsfirst contexts/ -contexts/ +$ tree --dirsfirst enclaves/ +enclaves/ ├── foo │ ├── cert.pem │ ├── governance.p7s @@ -162,22 +162,22 @@ contexts/ > Symbolic links suppressed for readability -### Relatively pushed qualified context path +### Relatively pushed qualified enclave path -For single process nodes with qualified context paths pushed by a namespace, the qualified context directory will subsequently be pushed to the relative sub-folder. +For single process nodes with qualified enclave paths pushed by a namespace, the qualified enclave directory will subsequently be pushed to the relative sub-folder. ``` xml - + ``` ``` -$ tree --dirsfirst contexts/ -contexts/ +$ tree --dirsfirst enclaves/ +enclaves/ └── foo └── bar ├── cert.pem @@ -188,22 +188,22 @@ contexts/ └── permissions.p7s ``` -### Fully qualified context path +### Fully qualified enclave path -For single process nodes with absolute context paths, namespaces do not subsequently push the relative sub-folder. +For single process nodes with absolute enclave paths, namespaces do not subsequently push the relative sub-folder. ``` xml - + ``` ``` -$ tree --dirsfirst contexts/ -contexts/ +$ tree --dirsfirst enclaves/ +enclaves/ └── bar ├── cert.pem ├── governance.p7s @@ -218,26 +218,26 @@ contexts/ ### Context path orthogonal to namespace -An alternative to reusing namespaces to hint the context path could be to completely disassociate the two entirely, treating the context path as it's own unique identifier. +An alternative to reusing namespaces to hint the enclave path could be to completely disassociate the two entirely, treating the enclave path as it's own unique identifier. Having to book keep both identifier spaces simultaneously may introduce too many degrees of freedom that a human could groc or easily introspect via tooling. However, doing so would still be possible given such namespacing conventions are bypassable in roslaunch and not implemented directly in RCL. -#### `` +#### `` -One such approach could be done by adding a `context` attribute to `push_ros_namespace` element. -This also keeps the pushing of contexts close/readable to pushing of namespaces. +One such approach could be done by adding a `enclave` attribute to `push_ros_namespace` element. +This also keeps the pushing of enclaves close/readable to pushing of namespaces. -#### `` +#### `` -Another alternative approach could be to add an entirely new `push_ros_context` element. -This could ensure the pushing of context path independent/flexable from namespaces. +Another alternative approach could be to add an entirely new `push_ros_enclave` element. +This could ensure the pushing of enclave path independent/flexable from namespaces. ## Concerns ### Multiple namespaces per context -For circumstances where users may compose multiple nodes of dissimilar namespaces into a single context, the user must still subsequently specify a common context path that is applicable for all nodes composed. -For circumstances where the context path is orthogonal to node namespace, the use of fully qualifying all relevant context paths could be tedious, but could perhaps could still be parametrized via the use of ``, and `` substitution and expansion. +For circumstances where users may compose multiple nodes of dissimilar namespaces into a single context, the user must still subsequently specify a common enclave path that is applicable for all nodes composed. +For circumstances where the enclave path is orthogonal to node namespace, the use of fully qualifying all relevant enclave paths could be tedious, but could perhaps could still be parametrized via the use of ``, and `` substitution and expansion. ### Modeling permissions of nodes in a process v.s. permission of the middleware ``Participant`` @@ -246,44 +246,44 @@ Each ``Participant`` subsequently load a security identity and access control cr However, all nodes in that process share the same memory space and can thus access data from other nodes. There is a mismatch between the middleware credentials/permissions loaded and the resources accessible within the process. -By using contexts, all nodes in a context share the same security identity and access control credentials. +By using enclaves, all nodes in a context share the same security identity and access control credentials. This inevitably means that code compiled to node ``foo`` can access credentials/permissions only trusted to node ``bar``. This consequence of composition could unintendedly subvert the minimal spanning policy as architected by the policy designer or measured/generated via ROS 2 tooling/IDL. -With the introduction of contexts, it becomes possible to describe the union of access control permission by defining a collection of SROS 2 policy profiles as element within a specific context. +With the introduction of enclaves, it becomes possible to describe the union of access control permission by defining a collection of SROS 2 policy profiles as element within a specific enclave. This would allow for formal analysis tooling [2] to check for potential violations in information flow control given the composing of nodes at runtime. -If a process contains a single context, this reconciles the permissions of a ``Participant`` and the ones of the process. +If a process loads a single enclave, this reconciles the permissions of a ``Participant`` and the ones of the process. -However, should multiple contexts be used per process, then such security guaranties are again lost because both contexts will share the same memory space. -Thus it should be asked whether if multiple contexts per process should even be supported. +However, should multiple enclaves be loaded per process, then such security guaranties are again lost because of shared same memory space. +Thus it should be asked whether if multiple enclaves per process should even be supported. -In summary, the distinction here is that before, the composition of multiple permissions could not be conveyed to the tooling. +In summary, the distinction here is that before, the composition of multiple node permissions could not be conveyed to the tooling. Whether nodes could gain the permission of others in the same process space is not the hinge point of note; it's the fact that such side effects could not be formally modeled or accounted for by the designer. -It will now be possible with contexts, however allowing for multiple contexts per process that load separate credentials would reintroduce and exacerbate the same modeling inaccuracies. +It will now be possible with enclaves, however allowing for multiple contexts per process that load separate enclaves would reintroduce and exacerbate the same modeling inaccuracies. ### Composable launchfile includes -A particular challenge in using launchfiles with security contexts is that of keeping the include hierarchy composable. +A particular challenge in using launchfiles with security enclaves is that of keeping the include hierarchy composable. An inherit tradeoff between simplicity and configurability can arise when writing launchfiles for downstream use. Authors can selectively choose what attributes to expose as input arguments, while users may implicitly override provided defaults. -In case of contexts, it is not inherently clear what best practices either package authors or users should employ to retain a composable and intuitive launchfile structure. E.g: -Should authors parametrize context paths for each node as input arguments? -Should users push namespaces of included launchfiles to separate contexts? +In case of enclaves, it is not inherently clear what best practices either package authors or users should employ to retain a composable and intuitive launchfile structure. E.g: +Should authors parametrize enclave paths for each node as input arguments? +Should users push namespaces of included launchfiles to unique enclaves? -To be sure though, the setting of security environment variables from within launchfiles should be discouraged, as this would restrict the use of static analysis of launchfiles combined with Node IDL for procedural context generation. +To be sure though, the setting of security environment variables from within launchfiles should be discouraged, as this would restrict the use of static analysis of launchfiles combined with Node IDL for procedural policy generation. ### Composable nodes in container -Given that containers can be dynamic, where nodes can be added or removed at runtime, there is perhaps some question as to how containers should integrate with secure contexts. -In ros2launch, the namespace in scope at the container's instantiation could be used to resolve the container's specified relative context path, thus to all nodes/components inside that container. +Given that containers can be dynamic, where nodes can be added or removed at runtime, there is perhaps some question as to how containers should integrate with secure enclaves. +In ros2launch, the namespace in scope at the container's instantiation could be used to resolve the container's specified relative enclave path, thus to all nodes/components inside that container. This should be further deliberated when eventually extending the launch API for containers. ### Migration for RMW implementations As it may take time before all RMW implementations implement the new system of contexts, a defined fallback behavior should still be designated. -For such implementations, the context security directory determined by RCL should be loaded for the participant as per the priority of context setting specified in the "ROS 2 DDS-Security integration" design doc. -This primarily desists the use of including the node name in the default lookup path, consequently getting users in the habit of creating separate contexts for separate processes, or explicitly specifying unique context names via launchfiles. +For such implementations, the enclave security directory determined by RCL should be loaded for the participant as specified in the "ROS 2 DDS-Security integration" design doc. +This primarily desists the use of including the node name in the default lookup path, consequently getting users in the habit of creating separate enclaves for separate processes, or explicitly specifying unique enclave paths via launchfiles. ## References From 2a711136d9ae629ef19d7c92ce61adfe0fcafc7e Mon Sep 17 00:00:00 2001 From: ruffsl Date: Wed, 8 Apr 2020 15:47:21 -0700 Subject: [PATCH 39/49] Rename for enclave terminology change --- articles/{ros2_security_contexts.md => ros2_security_enclaves.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename articles/{ros2_security_contexts.md => ros2_security_enclaves.md} (100%) diff --git a/articles/ros2_security_contexts.md b/articles/ros2_security_enclaves.md similarity index 100% rename from articles/ros2_security_contexts.md rename to articles/ros2_security_enclaves.md From ec57ca2e0c81ef1d518e625f73502901ae9cb648 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Wed, 8 Apr 2020 23:08:47 -0700 Subject: [PATCH 40/49] Update runtime argument for enclave assignment --- articles/150_ros_command_line_arguments.md | 20 ++++++++++++++++++++ articles/ros2_dds_security.md | 8 ++++---- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/articles/150_ros_command_line_arguments.md b/articles/150_ros_command_line_arguments.md index dc6a5dcda..4428e9d21 100644 --- a/articles/150_ros_command_line_arguments.md +++ b/articles/150_ros_command_line_arguments.md @@ -78,6 +78,7 @@ As a quick summary of ROS command line capabilities: - to `rosout`, use `--enable-rosout-logs` or `--disable-rosout-logs` - to `stdout`, use `--enable-stdout-logs` or `--disable-stdout-logs` - to a external logging library, use `--enable-external-lib-logs` or `--disable-external-lib-logs` +- For enclave assignment, use either `--enclave value` or `-e value` where value is fully qualified enclave path. For name remapping and parameter assignment, specific nodes can be targeted by prepending the option value with the node name followed by a colon `:`, as in `--remap my_node:from:=to` and `--param my_node:name:=value`. @@ -201,6 +202,25 @@ ros2 run some_package some_ros_executable --ros-args --disable-rosout-logs --dis Logging is fully enabled by default, thus `--enable-*` options are usually redundant unless a `--disable-*` option found earlier in the command line is being overridden. +#### Enclave assignments + +Enclave assignment may be achieved using the `--enclave`/`-e` option. +This option takes a single string `value` assignment statement, where `value` is where value is fully qualified enclave path used to locate the respective security artifacts within the configured keystore. + +As an example, to assign a enclave path `/foo/bar` one may execute: + +```sh +ros2 run some_package some_ros_executable --ros-args --enclave="/foo/bar" +``` + +or its shorter equivalent: + +```sh +ros2 run some_package some_ros_executable --ros-args -e "/foo/bar" +``` + +As is, this enclave assignment applies to each and every context that `some_ros_executable` spawns unless explicitly ignored in code or overridden via security environment variables. + ## Implementation ### Extraction diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index e57ef69aa..ff13f3bb4 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -147,11 +147,11 @@ The set of files expected within each enclave instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular enclave instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the keystore directory tree, and then specifying the enclave path using the `--ros-args` runtime argument `--security-enclave`, e.g.: +This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the keystore directory tree, and then specifying the enclave path using the `--ros-args` runtime argument `-e`, `--enclave`, e.g.: ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore" -ros2 run --ros-args --security-enclave="/front/camera" +ros2 run --ros-args --enclave="/front/camera" ``` #### Manual specification @@ -160,7 +160,7 @@ RCL supports specifying the path to a directory containing the set of security f The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual enclave directories. This can be specified by setting the `ROS_SECURITY_DIRECTORY_OVERRIDE` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--security-enclave`. +Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--enclave`. Note the following two examples load from the same enclave path as demonstrated prior: @@ -172,7 +172,7 @@ ros2 run ``` shell export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" -ros2 run --ros-args --security-enclave="/spam" +ros2 run --ros-args --enclave="/spam" ``` ### Support for both permissive and strict enforcement of security From 3e148b2bc513fa8b133fa991a3315e9044b23954 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 13:30:29 -0700 Subject: [PATCH 41/49] Relegate lunch intertraion to future work --- articles/ros2_security_enclaves.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/articles/ros2_security_enclaves.md b/articles/ros2_security_enclaves.md index 93a3b7a44..b58205d49 100644 --- a/articles/ros2_security_enclaves.md +++ b/articles/ros2_security_enclaves.md @@ -98,8 +98,11 @@ The ``enclaves`` directory contains the security artifacts associated with indiv Similar to node directories however, the `enclaves` folder may still recursively nest sub-paths for organizing separate enclaves. The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention point to this directory. +## Future Work -## Runtime +Introspective tooling and launchfile interfaces should be updated to help lessen the complexity introduced with the migration to contexts and enclaves. + +### Runtime Given the normative case where a enclave within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the enclave. To highlight this interdependency, and to help avoid enclave path collisions, a hierarchy borrowing namespaces is appropriate. From e4b4ad43f5cc7303e156f49bf122410d1e667fd7 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 13:32:57 -0700 Subject: [PATCH 42/49] Disassociate context paths from namespaces --- articles/ros2_security_enclaves.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/articles/ros2_security_enclaves.md b/articles/ros2_security_enclaves.md index b58205d49..650339203 100644 --- a/articles/ros2_security_enclaves.md +++ b/articles/ros2_security_enclaves.md @@ -98,6 +98,11 @@ The ``enclaves`` directory contains the security artifacts associated with indiv Similar to node directories however, the `enclaves` folder may still recursively nest sub-paths for organizing separate enclaves. The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention point to this directory. +## Integration + +With the introduction of contexts into rcl, instead of relying on node namespaces to lookup security artifacts from the keystore, the enclave path is now completely disassociated from node namespaces, instead serving as its own unique resource identifier. +Although having to book keep both identifier spaces simultaneously may introduce more degrees of freedom, it should still be possible to organize enclaves within the keystore to mimic node namespace hierarchy for transparent traceability of allocated permissions. + ## Future Work Introspective tooling and launchfile interfaces should be updated to help lessen the complexity introduced with the migration to contexts and enclaves. @@ -219,12 +224,6 @@ enclaves/ ## Alternatives -### Context path orthogonal to namespace - -An alternative to reusing namespaces to hint the enclave path could be to completely disassociate the two entirely, treating the enclave path as it's own unique identifier. -Having to book keep both identifier spaces simultaneously may introduce too many degrees of freedom that a human could groc or easily introspect via tooling. -However, doing so would still be possible given such namespacing conventions are bypassable in roslaunch and not implemented directly in RCL. - #### `` One such approach could be done by adding a `enclave` attribute to `push_ros_namespace` element. From a206b1ac86d7e959e97e24d292444d9bf3b6df91 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 13:35:01 -0700 Subject: [PATCH 43/49] Correct terms --- articles/150_ros_command_line_arguments.md | 2 +- articles/ros2_dds_security.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/150_ros_command_line_arguments.md b/articles/150_ros_command_line_arguments.md index 4428e9d21..92b318649 100644 --- a/articles/150_ros_command_line_arguments.md +++ b/articles/150_ros_command_line_arguments.md @@ -219,7 +219,7 @@ or its shorter equivalent: ros2 run some_package some_ros_executable --ros-args -e "/foo/bar" ``` -As is, this enclave assignment applies to each and every context that `some_ros_executable` spawns unless explicitly ignored in code or overridden via security environment variables. +As is, this enclave assignment applies to each and every Domain Participant that `some_ros_executable` spawns unless explicitly ignored in code or overridden via security environment variables. ## Implementation diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index ff13f3bb4..73f3c357e 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -114,7 +114,7 @@ Let's discuss each of these in turn. ### Security files for each domain participant As stated earlier, the DDS-Security plugins require a set of security files (e.g. keys, governance and permissions files, etc.) per domain participant. -Domain participants map to a process in ROS 2, so each process requires a set of these files. +Domain participants map to a context within process in ROS 2, so each process requires a set of these files. RCL supports being pointed at a directory containing security files in two different ways: - Directory tree of all security files. From 134f3e1a1b17730e70302ab4c073c3c2984bc1ce Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 13:37:11 -0700 Subject: [PATCH 44/49] Fix grammar --- articles/150_ros_command_line_arguments.md | 4 ++-- articles/ros2_access_control_policies.md | 9 +++------ articles/ros2_dds_security.md | 2 +- articles/ros2_security_enclaves.md | 2 +- 4 files changed, 7 insertions(+), 10 deletions(-) diff --git a/articles/150_ros_command_line_arguments.md b/articles/150_ros_command_line_arguments.md index 92b318649..437fa0ec7 100644 --- a/articles/150_ros_command_line_arguments.md +++ b/articles/150_ros_command_line_arguments.md @@ -205,9 +205,9 @@ Logging is fully enabled by default, thus `--enable-*` options are usually redun #### Enclave assignments Enclave assignment may be achieved using the `--enclave`/`-e` option. -This option takes a single string `value` assignment statement, where `value` is where value is fully qualified enclave path used to locate the respective security artifacts within the configured keystore. +This option takes a single string `value` assignment statement, where `value` is a fully qualified enclave path used to locate the respective security artifacts within the configured keystore. -As an example, to assign a enclave path `/foo/bar` one may execute: +As an example, to assign an enclave path `/foo/bar` one may execute: ```sh ros2 run some_package some_ros_executable --ros-args --enclave="/foo/bar" diff --git a/articles/ros2_access_control_policies.md b/articles/ros2_access_control_policies.md index c2d91c60d..74b98a2ac 100644 --- a/articles/ros2_access_control_policies.md +++ b/articles/ros2_access_control_policies.md @@ -107,15 +107,12 @@ This method of nesting sequences allows for additional tags to be extended to th ### `` Tag Encapsulates a collection of profiles. -This is specific to a enclave as determined by associative attributes. +This is specific to an enclave as determined by associative attributes. Attributes: - **path**: Fully qualified enclave path -Given that multiple nodes can be composed into a single process, a enclave is used to contain the collection of profiles of all respective nodes. -A enclave may therefore be considered the union of contained profiles. -Note that the union of profiles within a enclave will result in denied privileges of any profile to supersede all allowed privileges for every profile. -See section `` Tag for more info on MAC is applied. +An enclave may therefore be considered the union of contained profiles. ### `` Tag @@ -149,7 +146,7 @@ There can only one `metadata` element per `profiles` parent element. Attributes: - To be defined -Given the use cases for bridge interfaces where a enclave's credentials may be used to interconnect across multiple transports or to transport specific domains, it may be necessary to qualify certain profile sequences with particular constraints, while doing so multiple times for separate profiles per enclave. +Given the use cases for bridge interfaces where an enclave's credentials may be used to interconnect across multiple transports or to transport specific domains, it may be necessary to qualify certain profile sequences with particular constraints, while doing so multiple times for separate profiles per enclave. This allows advanced users to holistically control the intersect of permissions across transport domains, while retaining accurate model fidelity of security permissions. Given how security sensitive bridge interfaces are and the attack surface they expose, it is vital that information flow control within a bridge remains formally verifiable for safe and secure operation. diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 73f3c357e..52f6824ee 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -162,7 +162,7 @@ The set of files expected within that directory are the same as outlined in the This can be specified by setting the `ROS_SECURITY_DIRECTORY_OVERRIDE` environment variable to point to the directory containing the security files. Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--enclave`. -Note the following two examples load from the same enclave path as demonstrated prior: +Note that the following two examples load from the same enclave path as demonstrated prior: ``` shell export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" diff --git a/articles/ros2_security_enclaves.md b/articles/ros2_security_enclaves.md index 650339203..ee58871c7 100644 --- a/articles/ros2_security_enclaves.md +++ b/articles/ros2_security_enclaves.md @@ -109,7 +109,7 @@ Introspective tooling and launchfile interfaces should be updated to help lessen ### Runtime -Given the normative case where a enclave within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the enclave. +Given the normative case where an enclave within a policy may be specific to a single node/container process, the namespace the node is remapped to will inevitably affect the required security permissions necessary within the enclave. To highlight this interdependency, and to help avoid enclave path collisions, a hierarchy borrowing namespaces is appropriate. By convention, ros2launch could be used to prefix relative enclave paths for single process node or containers using the namespace in scope, to enable a convention of composable launch files with adjustable and parameterized enclave paths. Given the runtime command argument for specifying the fully qualified enclave path, ros2launch would accordingly resolve relative enclave paths for executables, as defined by launch attributes. From 8f7fac98413b00a6148245f764c15ef9b2e73654 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 15:30:03 -0700 Subject: [PATCH 45/49] Editorial rephrasing --- articles/ros2_dds_security.md | 6 +++--- articles/ros2_security_enclaves.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 52f6824ee..5e3a87a70 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -177,11 +177,11 @@ ros2 run --ros-args --enclave="/spam" ### Support for both permissive and strict enforcement of security -Processes with the security features enabled will not communicate with processes that don't, but what should RCL do if one tries to launch a process that has no discernable enclave with keys/permissions/etc.? It has two options: +Participants with the security features enabled will not communicate with participants that don't, but what should RCL do if one tries to launch a participant that has no discernable enclave with keys/permissions/etc.? It has two options: -- **Permissive mode**: Try to find security files, and if they can't be found, launch the process without enabling any security features. +- **Permissive mode**: Try to find security files, and if they can't be found, launch the participant without enabling any security features. This is the default behavior. -- **Strict mode**: Try to find security files, and if they can't be found, fail to run the process. +- **Strict mode**: Try to find security files, and if they can't be found, fail to run the participant. The type of mode desired can be specified by setting the `ROS_SECURITY_STRATEGY` environment variable to "Enforce" (case-sensitive) for strict mode, and anything else for permissive mode. diff --git a/articles/ros2_security_enclaves.md b/articles/ros2_security_enclaves.md index ee58871c7..bb9911c3d 100644 --- a/articles/ros2_security_enclaves.md +++ b/articles/ros2_security_enclaves.md @@ -24,7 +24,7 @@ categories: Security Original Author: {{ page.author }} This design document formalizes the integration of ROS 2 with security enclaves. -In summary, all processes must load a common enclave that contains the runtime security artifacts unique to that enclave, yet each process may not necessarily have a unique enclave. +In summary, all secure processes must use an enclave that contains the runtime security artifacts unique to that enclave, yet each process may not necessarily have a unique enclave. Multiple enclaves can be encapsulated in a single security policy to accurately model the information flow control. Users can tune the fidelity of such models by controlling at what scope enclaves are applied at deployment. E.g. one unique enclave per OS process, or per OS user, or per device/robot, or per swarm, etc. From ea400f66ce4e8d297aa4b9b032c322c357f8f8a5 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 15:34:32 -0700 Subject: [PATCH 46/49] Update override example of root directory and CLA --- articles/ros2_dds_security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 5e3a87a70..62e06ad63 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -165,12 +165,12 @@ Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with Note that the following two examples load from the same enclave path as demonstrated prior: ``` shell +export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" ros2 run ``` ``` shell -export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" ros2 run --ros-args --enclave="/spam" ``` From d29e06a2de3544d904d721f941f5e0adfd3d2317 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Thu, 9 Apr 2020 16:08:34 -0700 Subject: [PATCH 47/49] Editorial clarifications --- articles/ros2_access_control_policies.md | 4 ++++ articles/ros2_security_enclaves.md | 1 + 2 files changed, 5 insertions(+) diff --git a/articles/ros2_access_control_policies.md b/articles/ros2_access_control_policies.md index 74b98a2ac..68513584c 100644 --- a/articles/ros2_access_control_policies.md +++ b/articles/ros2_access_control_policies.md @@ -112,7 +112,11 @@ This is specific to an enclave as determined by associative attributes. Attributes: - **path**: Fully qualified enclave path +Given that multiple nodes can be composed into a single process, an enclave is used to contain the collection of profiles of all respective nodes. An enclave may therefore be considered the union of contained profiles. +Note that the union of profiles within an enclave will result in denied privileges of any profile to supersede all allowed privileges for every profile. +E.g. if a profile asks for a permission but a matching permission has been explicitly denied by another profile in the enclave, the deny rule will take precedence. +See section `` Tag for more info on how MAC is applied. ### `` Tag diff --git a/articles/ros2_security_enclaves.md b/articles/ros2_security_enclaves.md index bb9911c3d..8bd9b367b 100644 --- a/articles/ros2_security_enclaves.md +++ b/articles/ros2_security_enclaves.md @@ -55,6 +55,7 @@ Previously however, each node would retain it's one to one mapping to a separate Given the non-negligible overhead incurred of multiple ``Participant``s per process, a change was introduced to map a single ``Participant`` to a context, and allow for multiple nodes to share that context. Based on the DDS Security specification v1.1, a ``Participant`` can only utilise a single security identity; consequently the access control permissions applicable to every node mapped to a given context must be consolidated and combined into a single set of security artifacts, or enclave. +Thus, all contexts and their respective participants in each process will then use that single enclave. As such, additional tooling and extensions to SROS 2 are necessary to support this new paradigm. ## Keystore From cec67f6eb2cc21ae9b729a933cb440b1d2bc1d05 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 13 Apr 2020 21:34:48 -0700 Subject: [PATCH 48/49] Rename security environment variables --- articles/ros2_dds_security.md | 14 +++++++------- articles/ros2_security_enclaves.md | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 62e06ad63..40346e754 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -147,10 +147,10 @@ The set of files expected within each enclave instance directory are: - **governance.p7s**: The XML document that specifies to the **Access control** plugin how the domain should be secured (signed by the Permissions CA). - **permissions.p7s**: The XML document that specifies the permissions of this particular enclave instance to the **Access control** plugin (also signed by the Permissions CA). -This can be specified by setting the `ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the keystore directory tree, and then specifying the enclave path using the `--ros-args` runtime argument `-e`, `--enclave`, e.g.: +This can be specified by setting the `ROS_SECURITY_KEYSTORE` environment variable to point to the root of the keystore directory tree, and then specifying the enclave path using the `--ros-args` runtime argument `-e`, `--enclave`, e.g.: ``` shell -export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore" +export ROS_SECURITY_KEYSTORE="/home/bob/.ros/sros2_keystore" ros2 run --ros-args --enclave="/front/camera" ``` @@ -159,19 +159,19 @@ ros2 run --ros-args --enclave="/front/camera" RCL supports specifying the path to a directory containing the set of security files for the process that needs to be launched. The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual enclave directories. -This can be specified by setting the `ROS_SECURITY_DIRECTORY_OVERRIDE` environment variable to point to the directory containing the security files. -Note that this setting takes precedence over `ROS_SECURITY_ROOT_DIRECTORY` with `--enclave`. +This can be specified by setting the `ROS_SECURITY_ENCLAVE_OVERRIDE` environment variable to point to the directory containing the security files. +Note that this setting takes precedence over `ROS_SECURITY_KEYSTORE` with `--enclave`. Note that the following two examples load from the same enclave path as demonstrated prior: ``` shell -export ROS_SECURITY_ROOT_DIRECTORY="/dev/null" -export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" +export ROS_SECURITY_KEYSTORE="/dev/null" +export ROS_SECURITY_ENCLAVE_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" ros2 run ``` ``` shell -export ROS_SECURITY_DIRECTORY_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" +export ROS_SECURITY_ENCLAVE_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" ros2 run --ros-args --enclave="/spam" ``` diff --git a/articles/ros2_security_enclaves.md b/articles/ros2_security_enclaves.md index 8bd9b367b..712229ea1 100644 --- a/articles/ros2_security_enclaves.md +++ b/articles/ros2_security_enclaves.md @@ -97,7 +97,7 @@ This directory should be redacted before deploying the keystore onto the target The ``enclaves`` directory contains the security artifacts associated with individual enclaves, and thus node directories are no longer relevant. Similar to node directories however, the `enclaves` folder may still recursively nest sub-paths for organizing separate enclaves. -The `ROS_SECURITY_ROOT_DIRECTORY` environment variable should by convention point to this directory. +The `ROS_SECURITY_KEYSTORE` environment variable should by convention point to this directory. ## Integration From 98200d8e3b273194afc3170f3a9b65eaab689226 Mon Sep 17 00:00:00 2001 From: ruffsl Date: Mon, 13 Apr 2020 21:39:56 -0700 Subject: [PATCH 49/49] Update behavor of ROS_SECURITY_ENCLAVE_OVERRIDE --- articles/ros2_dds_security.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/articles/ros2_dds_security.md b/articles/ros2_dds_security.md index 40346e754..f49dbdd5c 100644 --- a/articles/ros2_dds_security.md +++ b/articles/ros2_dds_security.md @@ -156,22 +156,21 @@ ros2 run --ros-args --enclave="/front/camera" #### Manual specification -RCL supports specifying the path to a directory containing the set of security files for the process that needs to be launched. -The set of files expected within that directory are the same as outlined in the "Directory tree of all security files" section above for individual enclave directories. - -This can be specified by setting the `ROS_SECURITY_ENCLAVE_OVERRIDE` environment variable to point to the directory containing the security files. +RCL also supports specifying the enclave path for the process that needs to be launched using an overriding environmental variable. +This can be done by setting the `ROS_SECURITY_ENCLAVE_OVERRIDE` environment variable to an alternate enclave path within the keystore. Note that this setting takes precedence over `ROS_SECURITY_KEYSTORE` with `--enclave`. Note that the following two examples load from the same enclave path as demonstrated prior: ``` shell -export ROS_SECURITY_KEYSTORE="/dev/null" -export ROS_SECURITY_ENCLAVE_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" +export ROS_SECURITY_KEYSTORE="/home/bob/.ros/sros2_keystore" +export ROS_SECURITY_ENCLAVE_OVERRIDE="/front/camera" ros2 run ``` ``` shell -export ROS_SECURITY_ENCLAVE_OVERRIDE="/home/bob/.ros/sros2_keystore/enclaves/front/camera" +export ROS_SECURITY_KEYSTORE="/home/bob/.ros/sros2_keystore" +export ROS_SECURITY_ENCLAVE_OVERRIDE="/front/camera" ros2 run --ros-args --enclave="/spam" ```