diff --git a/doc/media-session.dox b/doc/media-session.dox index c5a708fe8..e5f5fb07b 100644 --- a/doc/media-session.dox +++ b/doc/media-session.dox @@ -26,6 +26,7 @@ additional checks are performed yet. List of Media Session modules: - \subpage page_media_session_module_access_flatpak +- \subpage page_media_session_module_access_portal */ diff --git a/doc/pipewire-portal.dox b/doc/pipewire-portal.dox index a965263dd..0aafa69df 100644 --- a/doc/pipewire-portal.dox +++ b/doc/pipewire-portal.dox @@ -2,22 +2,23 @@ This document explains how clients from the portal are handled. -The portal is a DBus service that exposes a couple of interfaces to +The portal is a DBus service that exposes interfaces to request access to the PipeWire daemon to perform a certain set of -functions. +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 portal makes it possible to use PipeWire without having to expose -the local PipeWire socket in the sandboxed application. It is the -portal can connects to PipeWire on behalf of the client. The client -becomes a portal managed client. PipeWire can detect and enforce +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 that provides a PipeWire session -to stream video from a camera. +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 +### 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. @@ -25,7 +26,7 @@ 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 +### 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. @@ -33,7 +34,7 @@ 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 +### 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. @@ -47,35 +48,36 @@ where these permissions can be managed. ## The portal -The portal itself will make a connection to the PipeWire daemon to -configure the session. It then hands the file descriptor of the PipeWire -connection to the client. The client can then use the file descriptor -to interface with the PipeWire session. +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 when this connection is the - portal itself and not a client it is managing. - * "pipewire.access.portal.app_id" the application id of the client. - * "pipewire.access.portal.media_roles" media roles of the client. - Currently "Camera" is defined. +- `"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 will configure -minimal permissions on the client. No objects are initialy visible. It is -the task of the session manager to make the objects in the graph -visible, depending on the client media_roles. +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 -\subpage page_module_portal +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)). -The pipewire daemon uses the portal module to find the PID of the -processes that owns the DBus name "org.freedesktop.portal.Desktop". - -It can then detect clients that connect from this PID and tag them -as PW_KEY_ACCESS "portal". It will also set ALL permissions for this -client so that it can resume. See also \ref page_module_access. +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 @@ -92,33 +94,14 @@ will have limited permissions. ## The session manager The session manager listens for new clients to appear. It will use the -PW_KEY_ACCESS property to find portal connections. +\ref PW_KEY_ACCESS property to find portal connections. -Based on the media_roles it will enable or disable access to PipeWire +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 "org.freedesktop.impl.portal.PermissionStore" for this. - -# Implementation - -## pipewire-media-session - -The example media session has an access-portal module that handles the -clients that have a PW_KEY_ACCESS as "portal". Other clients are -ignored. - -It currently only handles the camera media_roles and asks the permission -store for camera device permissions. It receives an array of app_id -and the associated permissions. It enables all camera objects when the -camera permissions is given to the app_id of the client. - -For new nodes that appear, it will check if the client is allowed to -see them or not and set the permissions on the new object accordingly. - -It watches changes in the permission stored and updates the permissions -of the objects of clients accordingly. - +implements support for `org.freedesktop.impl.portal.PermissionStore`, +see for example the \ref page_media_session_module_access_portal. */ diff --git a/src/examples/media-session/access-portal.c b/src/examples/media-session/access-portal.c index bf6c942a6..78036f98b 100644 --- a/src/examples/media-session/access-portal.c +++ b/src/examples/media-session/access-portal.c @@ -40,6 +40,37 @@ #include "media-session.h" +/** \page page_media_session_module_access_portal Media Session Module: Access Portal + * + * The Access Portal module manages media roles for clients + * started through a portal (see \ref page_module_portal). Clients must have a + * \ref PW_KEY_ACCESS or \ref PW_KEY_CLIENT_ACCESS property value of + * `"portal"`, all other clients are ignored. The portal is expected to assign + *`"pipewire.access.portal.media_roles"` to this client, these roles are + * checked against the + * [org.freedesktop.impl.portal.PermissionStore](https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-org.freedesktop.impl.portal.PermissionStore). + * Where permitted, the resulting client media role becomes the permitted + * set of roles. + * + * @note Currently only the "Camera" media role is supported. + * + * The Permission Store entry table used by this module is `"devices"`, the + * resource ID is `"camera"`. + * + * ## Module Properties + * + * This module requires the following properties on the client object: + * + * - `"pipewire.access.portal.is_portal"`: set to `"true"` for the portal + * client itself, empty or `"false"` otherwise + * - `"pipewire.access.portal.app_id"`: the application ID of the client + * - `"pipewire.access.portal.media_roles"` the media roles that should be + * assigned to this client (if permitted by the PermissionStore). + * + * The above properties must be set by the portal initiating the client + * connection. + * + */ #define NAME "access-portal" #define SESSION_KEY "access-portal" diff --git a/src/modules/module-portal.c b/src/modules/module-portal.c index 84c5ae155..576fe1b44 100644 --- a/src/modules/module-portal.c +++ b/src/modules/module-portal.c @@ -46,6 +46,37 @@ #include "pipewire/private.h" /** \page page_module_portal PipeWire Module: Portal + * + * The `portal` module performs access control management for clients started + * inside an XDG portal. + * + * The module connects to the session DBus and subscribes to + * `NameOwnerChanged` signals for the `org.freedesktop.portal.Desktop` name. + * The PID of the DBus name owner is the portal. + * + * A client connection from the portal PID to PipeWire gets assigned a \ref + * PW_KEY_ACCESS of `"portal"` and set to permissions ALL - it is the + * responsibility of the portal to limit the permissions before passing the + * connection on to the client. See \ref page_access for details on + * permissions. + * + * Clients connecting from other PIDs are ignored by this module. + * + * ## Module Options + * + * There are no module-specific options. + * + * ## General options + * + * There are no general options for this module. + * + * ## Example configuration + *\code{.unparsed} + * context.modules = [ + * { name = libpipewire-portal } + * ] + *\endcode + * */ #define NAME "portal"