From 4496aed5a6166720a4fc881c7a0f892ae6354e8e Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 29 Jul 2021 15:47:22 +1000 Subject: [PATCH] doc: revamp the pipewire-access page Rewording, linking to the various things, etc. --- doc/media-session.dox | 16 ++++ doc/pipewire-access.dox | 161 ++++++++++++++---------------------- src/modules/module-access.c | 6 ++ 3 files changed, 84 insertions(+), 99 deletions(-) diff --git a/doc/media-session.dox b/doc/media-session.dox index f96a3e280..c5a708fe8 100644 --- a/doc/media-session.dox +++ b/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: diff --git a/doc/pipewire-access.dox b/doc/pipewire-access.dox index 21664350c..d999e32a8 100644 --- a/doc/pipewire-access.dox +++ b/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 -receive registry events for the object and can interact with it. - -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. +Clients with all permissions set are referred to as "ALL" in the +documentation. # 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 -permission to avoid this. - -## Flatpaks can't move other streams to different devices +### 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 -be avoided. +on the node id. By not setting the `M` bit on the other objects, this can be +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 -to see. For example, a web browser that was given access to a camera should -not be able to see audio devices. +In general, applications should only be able to see the objects that they are +allowed to see. For example, a web browser that was given access to a camera +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 -access to the PipeWire graph. This includes moving streams -(setting metadata) and modifying properties (volume). +Some applications require full access to the PipeWire graph, including +moving streams between nodes (by setting metadata) and modifying properties +(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 -updates its properties, it will be registered and made visible to other +Immediately after a new client connects to the PipeWire daemon and updates +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 -registered client. +The PipeWire core will emit a `check_access` event in the \ref pw_context_events +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 -with the daemon. Clients without R permissions on the core are suspended +Clients with permission `R` on the core object can continue communicating +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 -manager. +sets the core permissions to `R`. This other client is usually a session +manager, see e.g. \ref page_session_manager. ## The access module -\subpage page_module_access - -The access module hooks into the check_access event when a new client is -registered and will check the permissions of the client. - -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. +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 current permissions on the client are stored in the \ref PW_KEY_ACCESS +property on the client object. If this property is already 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. - If yes, PW_KEY_ACCESS is set to "allowed". +Depending on the value of the \ref PW_KEY_ACCESS property one the following +happens: -- The cmdline of the client is checked against a list of rejected clients. - 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 +- "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 -manager or another client will need to configure permissions on the object +As detailed above, the client may be suspended. In that case the session +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, it will eventually need to set the R permission on the -core object for the client. +To resume a client, the session manager needs to set permission `R` +on the 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 -client completely. - -Manager applications will set the PW_KEY_MEDIA_CATEGORY property -in the client object to "Manager". +session manager. Removing the client core permission `R` will suspend the +client. 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 - -## 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. +For details on the pipewire-media-session implementation of access control, +see \ref page_media_session. */ diff --git a/src/modules/module-access.c b/src/modules/module-access.c index 2be8dae3e..86e3a2774 100644 --- a/src/modules/module-access.c +++ b/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