Add and update security designs for Contexts

articles/ros2_access_control_policies.md

@@ -99,11 +99,32 @@ Attributes:
 - **version**: declared version of schema version in use
   - Allows for advancing future revisions of the schema
 
-### `<profiles>` Tag
+### `<contexts>` Tag
 
-Encapsulates a sequence of unique profiles.
+Encapsulates a sequence of unique contexts.
 This method of nesting sequences allows for additional tags to be extended to the `<policy>` root.
 
+### `<context>` 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 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 `<profile>` Tag for more info on 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 `<context>` 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 +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.
 
+### `<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 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.

articles/ros2_access_control_policies/policy.xsd

@@ -10,15 +10,32 @@
     <xs:element name="policy" type="Policy" />
     <xs:complexType name="Policy">
         <xs:sequence minOccurs="1" maxOccurs="1">
-            <xs:element name="profiles" type="Profiles" />
+            <xs:element name="contexts" type="Contexts" />
         </xs:sequence>
         <xs:attribute name="version" type="xs:string" use="required" />
     </xs:complexType>
 
+    <xs:complexType name="Contexts">
+        <xs:sequence minOccurs="1" maxOccurs="unbounded">
+            <xs:element name="context" type="Context" />
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="Context">
+        <xs:sequence minOccurs="1" maxOccurs="unbounded">
+            <xs:element name="profiles" type="Profiles" />
+        </xs:sequence>
+        <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>
+        <xs:sequence minOccurs="0" maxOccurs="1">
+            <xs:element name="metadata" type="xsd:anyType" />
+        </xs:sequence>
+        <xs:attribute name="type" type="xs:string" use="required" />
     </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 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,8 +125,8 @@ 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 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:
 
     <root>
     └── front
@@ -135,62 +135,60 @@ For example, for the `/front/camera` node, the directory structure would look li
             ├── 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_.
-
-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).
-
-This can be specified by setting the `$ROS_SECURITY_ROOT_DIRECTORY` environment variable to point to the root of the directory tree.
+- **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.:
 
-##### Support security files lookup methods
+``` shell
+export ROS_SECURITY_ROOT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts"
+ros2 run <package> <executable> --ros-args --context="/front/camera"
+```
 
-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.
+#### 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.
 
-#### Manual specification
+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`.
 
-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.
+Note the following two examples load from the same context 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_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera"
+ros2 run <package> <executable>
+```
 
+``` shell
+export ROS_SECURITY_ROOT_DIRECTORY="/dev/null"
+export ROS_SECURITY_CONTEXT_DIRECTORY="/home/bob/.ros/sros2_keystore/contexts/front/camera"
+ros2 run <package> <executable> --ros-args --context="/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:
+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.
+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 +200,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.