Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

USB portal (cont.) #1354

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

USB portal (cont.) #1354

wants to merge 10 commits into from

Commits on Nov 17, 2024

  1. Introduce USB portal 

    The USB portal is the middleman between sandboxed apps, and the
devices connected and available to the host system. This is the
first version of the portal.

Device filtering
================

Sandboxed apps must declare which USB devices they support ahead
of time. This information is read by the XDG Desktop Portal and
used to determine which USB devices will be exposed to requesting
apps. On Flatpak, these enumerable and hidden devices are set by the
"--usb" and "--nousb" arguments against "flatpak build-finish"
and "flatpak run". Neither "--devices=all" nor "--device=usb" do
influence the portal.

Hidding a device always take precedence over making them enumerable,
even when a blanket permission ("--usb=all") is set.

Individual devices are assigned a unique identifier by the portal,
which is used for all further interactions. This unique identifier
is completely random and independent of the device. Permission
checks are in place to not allow apps to try and guess device ids
without having permission to access then.

Permissions
===========

There are 2 dynamic permissions managed by the USB portal in the
permission store:

 1. Blanket USB permission: per-app permission to use any methods
    of the USB portal. Without this permission, apps must not be
    able to do anything - enumerate, monitor, or acquire - with
    the USB portal. [1]

 2. Specific device permission: per-app permission to acquire a
    specific USB device, down to the serial number.

Enumerating devices
===================

There are 2 ways for apps to learn about devices:

 - Apps can call the EnumerateDevices() method, which gives a
   snapshot of the current devices to the app.

 - Apps can create a device monitoring session with CreateSession()
   which sends the list of available devices on creation, and also
   notifies the app about connected and disconnected devices.

Only devices that the app is allowed to see are reported in both
cases.

The udev properties exposed by device enumeration is limited to a
well known subset of properties. [2]

Device acquisition & release
============================

Once an app has determined which devices it wants to access, the
app can call the AcquireDevices() method. This method may prompt
a dialog for the user to allow or deny the app from accessing
specific devices.

If permission is granted, XDG Desktop Portal tries to open the
device file on the behalf of the requesting app, and pass down
the file descriptor to that file. [3]

---

[1] Exceptionally, apps can release previously acquired devices,
even when this permission is disabled. This is so because we
don't yet have kernel-sided USB revoking. With USB revoking in
place, it would be possible to hard-cut app access right when
the app permission changes.

[2] This patch uses a hardcoded list. There is no mechanism for
apps to influence which other udev properties are fetched. This
approach is open to suggestions - it may be necessary to expose
more information more liberally through the portal.

[3] This is clearly not ideal. The ideal approach is to go through
logind's TakeDevice() method. However, that will add significant
complexity to the portal, since this logind method can only be
called by the session controller (i.e. the only executable capable
of calling TakeControl() in the session - usually the compositor).
This can and probably should be implemented in a subsequent round
of improvements to the USB portal.

Co-Authored By: Georges Basile Stavracas Neto <[email protected]>
Co-Authored-By: Ryan Gonzalez <[email protected]>

Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    628ed43 View commit details
    Browse the repository at this point in the history

  2. usb: If not sandboxed, assume all devices 

    Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    9b8a6a8 View commit details
    Browse the repository at this point in the history

  3. usb: Allow multiple pending devices acquisitions 

    Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    7c1aba8 View commit details
    Browse the repository at this point in the history

  4. usb: Remove the sender_state for device acquisition 

    Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    df70309 View commit details
    Browse the repository at this point in the history

  5. usb: Fix device insertion / removal handled 

    Don't assert on is_udev_device_suitable()

Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    68ba73b View commit details
    Browse the repository at this point in the history

  6. app-info/test: Allow passing USB queries via env 

    We want to test the USB portal which requires USB queries to determine
which USB devices should be enumerable and could potentially be
acquired. This adds an environment variable similar to the one for the
app id that the test harness can set.
    @swick @hfiguiere
    swick authored and hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    ecd0de7 View commit details
    Browse the repository at this point in the history

  7. tests/py: Allow setting usb_queries for AppInfoTest via fixture 

    This lets us control which USB devices are enumerable by setting the
fixture to valid xdp USB query.
    @swick @hfiguiere
    swick authored and hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    7408866 View commit details
    Browse the repository at this point in the history

  8. tests/usb: Test the USB portal via pytest, dbusmock and umockdev

    @swick @hfiguiere
    swick authored and hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    7289c68 View commit details
    Browse the repository at this point in the history

  9. usb: Check the token for AcquireFinish is valid 

    Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    b70b738 View commit details
    Browse the repository at this point in the history

  10. test: Disable USB removal test in a container 

    This is because it fails as we never get the removal event. In both podman and docker

Signed-off-by: Hubert Figuière <[email protected]>
    @hfiguiere
    hfiguiere committed Nov 17, 2024
    Configuration menu
    Copy the full SHA
    d2e1553 View commit details
    Browse the repository at this point in the history