diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/pipewire-portal.dox | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/doc/pipewire-portal.dox b/doc/pipewire-portal.dox new file mode 100644 index 0000000..721d981 --- /dev/null +++ b/doc/pipewire-portal.dox @@ -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. + +*/ |