mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-10-29 05:40:27 -04:00
doc: revamp the pipewire-access page
Rewording, linking to the various things, etc.
This commit is contained in:
Peter Hutterer
parent
d1c80183d9
commit
4496aed5a6
3 changed files with 84 additions and 99 deletions
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue