doc: revamp the pipewire-access page

Rewording, linking to the various things, etc.

doc/media-session.dox

@@ -5,6 +5,22 @@
 PipeWire Media Session is the reference/example session manager provided by
 the PipeWire project.
 
+# Access management
+
+The \ref page_media_session_module_access_flatpak module handles clients
+that have \ref PW_KEY_ACCESS set to "flatpak". Other clients are
+ignored.
+
+The module sets the permissions of all objects to `RX`. This limits the
+flatpaks from doing modifications to other objects.
+
+Because this will also set the core object permission `R`, the client will
+resume with the new permissions.
+
+`pipewire-media-session` implements \ref PW_KEY_MEDIA_CATEGORY type
+"Manager" applications by simply setting the client permissions to ALL. No
+additional checks are performed yet.
+
 # Modules
 
 List of Media Session modules:

doc/pipewire-access.dox

@@ -3,140 +3,115 @@
 This document explains how access control is designed implemented.
 
 PipeWire implements per client permissions on the objects in the graph.
+Permissions include `R` (read), `W` (write), `X` (execute) and `M` (metadata).
 
-Permissions include R (read), W (write), X (execute) and M (metadata).
+- `R`: An object with permission `R` is visible to the client. The client will receive
+  registry events for the object and can interact with it.
+- `W`: An object with permisson `W` can be modified. This is usually done
+  through a method that modifies the state of the object. The `W` permission
+  usually implies the `X` permission.
+- `X`: An object with permission `X` allows invoking methods on the object.
+  Some of those methods will only query state, others will modify the object.
+  As said above, modifying the object through one of these methods requires
+  the `W` permission.
+- `M`: An object with M permission can be used as the subject in metadata.
 
-An object with R permissions is visible to the client. The client will
+Clients with all permissions set are referred to as "ALL" in the
-receive registry events for the object and can interact with it.
+documentation.
-
-Methods can be called on an object with X permissions. Some of those
-methods will only query state, others will modify the object.
-
-An object with W permission can be modified. This is usually done with
-a method that modifies the state of the object. The W permission usually
-implies the X permission.
-
-An object with M permission can be used as the subject in metadata.
 
 # Use cases
 
-## new clients need their permissions configured
+### New clients need their permissions configured
 
 A new client is not allowed to communicate with the PipeWire daemon until
 it has been configured with permissions.
 
-## Flatpaks can't modify other stream/device volumes
+### Flatpaks can't modify other stream/device volumes
 
-Flatpaks should not be able to modify the state of certain objects.
+An application running as Flatpak should not be able to modify the state of
+certain objects. Permissions of the relevant PipeWire objects should not have
+the `W` permission to avoid this.
 
-Permissions of the relevant PipeWire objects should not have the W
+### Flatpaks can't move other streams to different devices
-permission to avoid this.
-
-## Flatpaks can't move other streams to different devices
 
 Streams are moved to another device by setting the "target.node" metadata
-on the node id. By not setting the M bit on the other objects, this can
+on the node id. By not setting the `M` bit on the other objects, this can be
-be avoided.
+avoided.
 
-## Some application should be restricted in what they can see
+### Application should be restricted in what they can see
 
-Application should only be able to see the objects that they are allowed
+In general, applications should only be able to see the objects that they are
-to see. For example, a web browser that was given access to a camera should
+allowed to see. For example, a web browser that was given access to a camera
-not be able to see audio devices.
+should not be able to see (and thus receive input data from) audio devices.
 
-## Manager applications
+### "Manager" applications require full access
 
-Some applications might be shipped in a flatpak but really require full
+Some applications require full access to the PipeWire graph, including
-access to the PipeWire graph. This includes moving streams
+moving streams between nodes (by setting metadata) and modifying properties
-(setting metadata) and modifying properties (volume).
+(e.g. volume). These applications must work even when running as Flatpak.
 
 
 # Design
 
 ## The PipeWire daemon
 
-When a new client connects to the PipeWire daemon and right after it
+Immediately after a new client connects to the PipeWire daemon and updates
-updates its properties, it will be registered and made visible to other
+its properties, the client will be registered and made visible to other
 clients.
 
-The PipeWire core will emit a context check_access event for the newly
+The PipeWire core will emit a `check_access` event in the \ref pw_context_events
-registered client.
+context for the the new client. The implementer of this event is responsible
+for assigning permissions to the client.
 
-Clients with R permissions on the core object can continue communicating
+Clients with permission `R` on the core object can continue communicating
-with the daemon. Clients without R permissions on the core are suspended
+with the daemon. Clients without permission `R` on the core are suspended
 and are not able to send more messages.
 
 A suspended client can only resume processing after some other client
-sets the core permissions to R. This other client is usually a session
+sets the core permissions to `R`. This other client is usually a session
-manager.
+manager, see e.g. \ref page_session_manager.
 
 
 ## The access module
 
-\subpage page_module_access
+The \ref page_module_access hooks into the `check_access` event when a new
-
+client is registered and will check the permissions of the client.
-The access module hooks into the check_access event when a new client is
+The current permissions on the client are stored in the \ref PW_KEY_ACCESS
-registered and will check the permissions of the client.
+property on the client object. If this property is already set, the access
-
+module does nothing.
-The current permissions on the client are stored in the PW_KEY_ACCESS
-property on the client object. If this property is set, the access module
-does nothing.
 
 If the property is not set, it will go through a set of checks to determine
-the allows access for a client:
+the permissions for a client, see the \ref page_module_access documentation
+for details.
 
-- The cmdline of the client is checked against a list of allowed clients.
+Depending on the value of the \ref PW_KEY_ACCESS property one the following
-  If yes, PW_KEY_ACCESS is set to "allowed".
+happens:
 
-- The cmdline of the client is checked against a list of rejected clients.
+- "allowed", "unrestricted" :  ALL permissions are set on the core
-  If yes, PW_KEY_ACCESS is set to "rejected".
-
-- The cmdline of the client is checked against a list of restricted clients.
-  If yes, PW_KEY_ACCESS is set to "restricted".
-
-- If the client has the "access.force" property, it is set as the
-  PW_KEY_ACCESS property.
-
-- A check is performed if the application is a flatpak. If yes,
-  PW_KEY_ACCESS is set to "flatpak".
-
-- If PW_KEY_CLIENT_ACCESS is set, it is copied to PW_KEY_ACCESS.
-
-- If no other value is set, PW_KEY_ACCESS is set to "unrestricted".
-
-Depending on the value of the PW_KEY_ACCESS one the following happens:
-
- * "allowed", "unrestricted" :  ALL permissions are set on the core
     object and the client will be able to resume.
-
+- "restricted", "flatpak", "$access.force" :  no permissions are set on
- * "restricted", "flatpak", "$access.force" :  no permissions are set on
     the core object and the client will be suspended.
-
+- "rejected" : an error is sent to the client and the client is
- * "rejected" : an error is sent to the client and the client is
     suspended.
 
-In some cases the client will be suspended. This is where the session
+As detailed above, the client may be suspended. In that case the session
-manager or another client will need to configure permissions on the object
+manager or another client is required to configure permissions on the object
 for it to resume.
 
 ## The session manager
 
 The session manager listens for new clients to appear. It will use the
-PW_KEY_ACCESS property to determine what to do.
+\ref PW_KEY_ACCESS property to determine what to do.
 
-For clients that are blocked with "restricted", "flatpak" or "$access.force"
+For clients that are suspended with "restricted", "flatpak" or "$access.force"
 access, the session manager needs to set permissions on the client for the
 various PipeWire objects in the graph that it is allowed to interact with.
-
+To resume a client, the session manager needs to set permission `R`
-To resume a client, it will eventually need to set the R permission on the
+on the core object for the client.
-core object for the client.
 
 Permissions of objects for a client can be changed at any time by the
-session manager. Removing the client core R permission will suspend the
+session manager. Removing the client core permission `R` will suspend the
-client completely.
+client.
-
-Manager applications will set the PW_KEY_MEDIA_CATEGORY property
-in the client object to "Manager".
 
 The session manager needs to do additional checks to determine if the
 manager permissions can be given to the particular client and then
@@ -144,22 +119,10 @@ configure ALL permissions on the client. Possible checks include
 permission store checks or ask the user if the application is allowed
 full access.
 
+Manager applications (i.e. applications that need to modify the graph) will
+set the \ref PW_KEY_MEDIA_CATEGORY property in the client object to "Manager".
 
-# Implementation
+For details on the pipewire-media-session implementation of access control,
-
+see \ref page_media_session.
-## pipewire-media-session
-
-The example media session has an access-flatpak module that handles the
-clients that have a PW_KEY_ACCESS as "flatpak". Other clients are
-ignored.
-
-It sets the permissions of all objects to RX. This limits the flatpaks
-from doing modifications to other objects.
-
-Because this will also set the core object R permissions, the client will
-resume with the new permissions.
-
-pipewire-media-session implements Manager applications by simply setting
-the client permissions to ALL. No additional checks are performed yet.
 
 */

src/modules/module-access.c

@@ -53,6 +53,10 @@
  * is only performed once per client, subsequent checks return the same
  * resolution.
  *
+ * Permissions assigned to a client are configured as arguments to this
+ * module, see the example configuration below. A special use-case is Flatpak
+ * where the permission management is delegated.
+ *
  * This module sets the \ref PW_KEY_ACCESS property to one of
  * - `allowed`: the client is explicitly allowed to access all resources
  * - `rejected`: the client does not have access to any resources and a
@@ -60,6 +64,8 @@
  * - `restricted`: the client is restricted, see note below
  * - `flatpak`: restricted, special case for clients running inside flatpak,
  *   see note below
+ * - `$access.force`: the value of the `access.force` argument given in the
+ *   module configuration.
  * - `unrestricted`: the client is allowed to access all resources. This is the
  *   default for clients not listed in any of the `access.*` options
  *   unless the client requested reduced permissions in \ref