mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-12-23 08:56:47 -05:00
doc: reorganize files
Separate various autogen files from the documentation .dox files. Rename .dox files to match the intended tree structure.
This commit is contained in:
Pauli Virtanen
Wim Taymans
parent
eca773fc12
commit
77fad4ee13
41 changed files with 60 additions and 59 deletions
215
doc/dox/internals/portal.dox
Normal file
215
doc/dox/internals/portal.dox
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
/** \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.
|
||||
|
||||
\dot
|
||||
digraph pw {
|
||||
compound=true;
|
||||
node [shape="box"];
|
||||
rankdir="TB";
|
||||
|
||||
dbus [label="org.freedesktop.portal.Desktop"];
|
||||
|
||||
portal_access [label="PipeWire (mod: Portal Access)"];
|
||||
portal [label="xdg-desktop-portal"];
|
||||
|
||||
dbus -> portal_access [arrowhead="dot"];
|
||||
dbus -> portal [arrowhead="dot"];
|
||||
|
||||
portal_access -> portal [label="pipewire.access = portal"];
|
||||
|
||||
{ rank="same"; portal_access; portal}
|
||||
}
|
||||
\enddot
|
||||
|
||||
## The Client
|
||||
|
||||
A client can ask the portal for a connection to the PipeWire daemon.
|
||||
|
||||
\dot
|
||||
digraph pw {
|
||||
compound=true;
|
||||
node [shape="box"];
|
||||
rankdir="LR";
|
||||
|
||||
pw [label="PipeWire"];
|
||||
portal [label="xdg-desktop-portal"];
|
||||
client [label="client"];
|
||||
|
||||
client -> portal;
|
||||
portal -> pw [label="portal.is_portal=true", arrowhead="none"]
|
||||
|
||||
{rank="min"; pw};
|
||||
{rank="max"; client};
|
||||
}
|
||||
\enddot
|
||||
|
||||
The portal maintains an (unrestricted) connection to the PipeWire daemon with
|
||||
`"pipewire.access.portal.is_portal" = true` to identify the nodes the client
|
||||
needs access to. It then creates a new restricted connection for the client,
|
||||
tagged with additional information.
|
||||
|
||||
\dot
|
||||
digraph pw {
|
||||
compound=true;
|
||||
node [shape="box"];
|
||||
rankdir="LR";
|
||||
|
||||
pw [label="PipeWire"];
|
||||
portal [label="xdg-desktop-portal"];
|
||||
client [label="client"];
|
||||
|
||||
client -> portal [arrowhead="none"];
|
||||
portal -> pw [label="portal.is_portal=true", arrowhead="none"]
|
||||
portal -> pw [label="portal.app_id = $appid"]
|
||||
|
||||
{rank="min"; pw};
|
||||
{rank="max"; client};
|
||||
}
|
||||
\enddot
|
||||
|
||||
The file descriptor for this restricted connection is passed back to the
|
||||
client which can now make use of the resources it has been permitted to
|
||||
access.
|
||||
|
||||
\dot
|
||||
digraph pw {
|
||||
compound=true;
|
||||
node [shape="box"];
|
||||
rankdir="LR";
|
||||
|
||||
pw [label="PipeWire"];
|
||||
portal [label="xdg-desktop-portal"];
|
||||
client [label="client"];
|
||||
|
||||
portal -> pw [label="portal.is_portal=true", arrowhead="none"]
|
||||
|
||||
pw->client [label="restricted connection"];
|
||||
|
||||
{rank="min"; pw};
|
||||
{rank="max"; client};
|
||||
}
|
||||
\enddot
|
||||
|
||||
## 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. For client connections
|
||||
from the portal the session manager checks the requested `media_roles` and
|
||||
enables or disables access to the respective PipeWire objects.
|
||||
It might have to consult a database to decide what is allowed, for example the
|
||||
[org.freedesktop.impl.portal.PermissionStore](https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-org.freedesktop.impl.portal.PermissionStore).
|
||||
|
||||
\dot
|
||||
strict digraph pw {
|
||||
compound=true;
|
||||
node [shape="box"];
|
||||
rankdir="LR";
|
||||
|
||||
portal [label="xdg-desktop-portal"];
|
||||
client [label="client"];
|
||||
|
||||
|
||||
subgraph {
|
||||
rankdir="TB";
|
||||
permissions [label="PermissionStore"];
|
||||
|
||||
sm->permissions;
|
||||
|
||||
sm [label="Session Manager"];
|
||||
pw [label="PipeWire"];
|
||||
sm -> pw [headlabel="allow $media.roles"];
|
||||
pw -> sm;
|
||||
portal -> pw [label="portal.app_id = $appid"];
|
||||
}
|
||||
|
||||
client -> portal [arrowhead="none"];
|
||||
|
||||
{rank="min"; sm, pw};
|
||||
{rank="max"; client};
|
||||
}
|
||||
\enddot
|
||||
|
||||
In the case of the [XDG Desktop
|
||||
Portal](https://github.com/flatpak/xdg-desktop-portal), the portal itself
|
||||
queries the PermissionStore directly.
|
||||
|
||||
*/
|
||||
Loading…
Add table
Add a link
Reference in a new issue