mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-09-06 00:40:34 +00:00
108 lines
4 KiB
Plaintext
108 lines
4 KiB
Plaintext
/** \page page_portal Portal Access Control
|
|
|
|
This document explains how clients from the portal are handled.
|
|
|
|
The portal is a DBus service that exposes interfaces to
|
|
request access to the PipeWire daemon to perform a certain set of
|
|
functions. The PipeWire daemon runs outside the sandbox, the portal is a way
|
|
for clients inside the sandbox to connect to and use PipeWire.
|
|
|
|
The PipeWire socket is not exposed in the sandbox. Instead, The portal
|
|
connects to PipeWire on behalf of the client, informing PipeWire that this
|
|
client is a portal-managed client. PipeWire can detect and enforce
|
|
extra permission checks on the portal managed clients.
|
|
|
|
Once such portal is the [Camera
|
|
portal](https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-org.freedesktop.portal.Camera)
|
|
that provides a PipeWire session to stream video from a camera.
|
|
|
|
# Use cases
|
|
|
|
### new portal managed clients need device permissions configured
|
|
|
|
When a new client is detected, the available objects need to be
|
|
scanned and permissions configured for each of them.
|
|
|
|
Only the devices belonging to the media_roles given by the
|
|
portal are considered.
|
|
|
|
### new devices need to be made visible to portal managed clients
|
|
|
|
Newly created objects are made visible to a client when the client
|
|
is allowed to interact with it.
|
|
|
|
Only the devices belonging to the media_roles given by the
|
|
portal are considered.
|
|
|
|
### permissions for a device need to be revoked
|
|
|
|
The session manager listens to changes in the permissions of devices
|
|
and will remove the client permissions accordingly.
|
|
|
|
Usually this is implemented by listening to the permission store
|
|
DBus object. The desktop environment might provide a configuration panel
|
|
where these permissions can be managed.
|
|
|
|
|
|
# Design
|
|
|
|
## The portal
|
|
|
|
A sandboxed client cannot connect to PipeWire directly. Instead, it connects
|
|
to the sandbox side of the portal which then connects the PipeWire daemon to
|
|
configure the session. The portal then hands the file descriptor of the
|
|
PipeWire connection to the client and the client can use this file descriptor
|
|
to interface with the PipeWire session directly.
|
|
|
|
When the portal connects, it will set the following properties on the
|
|
client object:
|
|
|
|
- `"pipewire.access.portal.is_portal" = true` for the connection of the
|
|
portal itself (as opposed to a client managed by the portal).
|
|
- `"pipewire.access.portal.app_id"` the [application id](https://docs.flatpak.org/en/latest/conventions.html#application-ids) of the client.
|
|
- `"pipewire.access.portal.media_roles"` media roles of the client.
|
|
Currently only `"Camera"` is defined.
|
|
|
|
Before returning the connection to a client, the portal configures
|
|
minimal permissions on the client. No objects are initially visible. It is
|
|
the task of the \ref page_session_manager to make the objects in the graph
|
|
visible, depending on the client's `media_roles` (see also \ref
|
|
PW_KEY_MEDIA_ROLE).
|
|
|
|
## The PipeWire portal module
|
|
|
|
The pipewire daemon uses the \ref page_module_portal to find the PID of the
|
|
processes that owns the DBus name `org.freedesktop.portal.Desktop`
|
|
(see the [XDG Desktop Portal](https://github.com/flatpak/xdg-desktop-portal)).
|
|
|
|
Client connections from this PID are tagged as \ref PW_KEY_ACCESS
|
|
`"portal"` (see \ref page_module_access). It will also set ALL permissions for
|
|
this client so that it can resume.
|
|
|
|
|
|
## The client
|
|
|
|
A client can ask the portal for a connection to the PipeWire daemon.
|
|
|
|
It receives a file descriptor that can then be used to interface with
|
|
the PipeWire daemon.
|
|
|
|
The connection will have been tagged by the portal as shown above and
|
|
will have limited permissions.
|
|
|
|
|
|
## The session manager
|
|
|
|
The session manager listens for new clients to appear. It will use the
|
|
\ref PW_KEY_ACCESS property to find portal connections.
|
|
|
|
Based on the `media_roles` it will enable or disable access to PipeWire
|
|
objects. It might have to consult a database to decide what is
|
|
allowed.
|
|
|
|
The permission store can be used for this. Usually the portal also
|
|
implements support for `org.freedesktop.impl.portal.PermissionStore`,
|
|
see for example the \ref page_media_session_module_access_portal.
|
|
|
|
*/
|