Add and update security designs for Contexts

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 a fully qualified enclave path used to locate the respective security artifacts within the configured keystore.
+
+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"
+```
+
+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 Domain Participant that `some_ros_executable` spawns unless explicitly ignored in code or overridden via security environment variables.  
+
 ## Implementation
 
 ### Extraction

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,11 +99,33 @@ Attributes:
 - **version**: declared version of schema version in use
   - Allows for advancing future revisions of the schema
 
-### `<profiles>` Tag
+### `<enclaves>` Tag
 
-Encapsulates a sequence of unique profiles.
+Encapsulates a sequence of unique enclaves.
 This method of nesting sequences allows for additional tags to be extended to the `<policy>` root.
 
+### `<enclave>` Tag
+
+Encapsulates a collection of profiles.
+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 `<profile>` Tag for more info on how MAC is applied. 
+
+### `<profiles>` Tag
+
+Encapsulates a sequence of unique profiles and designated metadata.
+This method of nesting sequences allows for additional tags to be extended to the `<enclave>` root, as well as associating particular metadata or constraints to the contained profile elements. 
+
+Attributes:
+- **type**: Specifies the transport type of profiles and metadata
+
 ### `<profile>` Tag
 
 Encapsulates a collection of subject privileges.
@@ -119,6 +141,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.
 
+### `<metadata>` 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 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.
+
 #### Privileges
 
 Privileges are defined as configuration of rules and permissions for object access.
@@ -286,8 +321,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

articles/ros2_access_control_policies/policy.xsd

@@ -10,15 +10,34 @@
     <xs:element name="policy" type="Policy" />
     <xs:complexType name="Policy">
         <xs:sequence minOccurs="1" maxOccurs="1">
+            <xs:element name="enclaves" type="Enclaves" />
+        </xs:sequence>
+        <xs:attribute name="version" type="xs:string" use="required" fixed="0.2.0"/>
+    </xs:complexType>
+
+    <xs:complexType name="Enclaves">
+        <xs:sequence minOccurs="1" maxOccurs="unbounded">
+            <xs:element name="enclave" type="Enclave" />
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="Enclave">
+        <xs:sequence minOccurs="1" maxOccurs="unbounded">
             <xs:element name="profiles" type="Profiles" />
         </xs:sequence>
-        <xs:attribute name="version" type="xs:string" use="required" />
+        <xs:attribute name="path" type="xs:string" use="required" />
     </xs:complexType>
 
     <xs:complexType name="Profiles">
-        <xs:sequence minOccurs="1" maxOccurs="unbounded">
-            <xs:element name="profile" type="Profile" />
+        <xs:sequence minOccurs="1" maxOccurs="1">
+            <xs:sequence minOccurs="1" maxOccurs="unbounded">
+                <xs:element name="profile" type="Profile" />
+            </xs:sequence>
+            <xs:sequence minOccurs="0" maxOccurs="1">
+                <xs:element name="metadata" type="xs:anyType" />
+            </xs:sequence>
         </xs:sequence>
+        <xs:attribute name="type" type="xs:string" use="optional" />
     </xs:complexType>
 
     <xs:complexType name="Profile">

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 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 node in ROS 2, so each node 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.
@@ -125,72 +125,72 @@ 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 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:
 
     <root>
-    └── front
-        └── camera
-            ├── cert.pem
-            ├── key.pem
-            ├── ...
+    ├── enclaves
+    │   └── front
+    │       └── camera
+    │           ├── cert.pem
+    │           ├── key.pem
+    │           ├── ...
+    └── public
+        ├── ...
 
-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_.
-
-The set of files expected within each node 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 node instance (signed by the Identity CA).
-- **key.pem**: The private key of this node 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 node 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
+- **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).
 
-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:
-
-- **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 `<root>/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 `<root>/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. `<root>/foo/bar/baz_12/`, or `<root>/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.
+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_KEYSTORE="/home/bob/.ros/sros2_keystore"
+ros2 run <package> <executable> --ros-args --enclave="/front/camera"
+```
 
 #### 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 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:
 
-This can be specified by setting the `$ROS_SECURITY_NODE_DIRECTORY` environment variable to point to the directory containing the security files.
-Note that this setting takes precedence over `$ROS_SECURITY_ROOT_DIRECTORY`.
+``` shell
+export ROS_SECURITY_KEYSTORE="/home/bob/.ros/sros2_keystore"
+export ROS_SECURITY_ENCLAVE_OVERRIDE="/front/camera"
+ros2 run <package> <executable>
+```
 
+``` shell
+export ROS_SECURITY_KEYSTORE="/home/bob/.ros/sros2_keystore"
+export ROS_SECURITY_ENCLAVE_OVERRIDE="/front/camera"
+ros2 run <package> <executable> --ros-args --enclave="/spam"
+```
 
 ### 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:
+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 node 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 node.
+- **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.
+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
 
 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.
 
 
@@ -202,9 +202,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 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 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 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.