README.md
1gnome-desktop
2=============
3
4gnome-desktop contains the libgnome-desktop library as well as a data
5file that exports the "GNOME" version to the Settings Details panel.
6
7The libgnome-desktop library provides API shared by several applications
8on the desktop, but that cannot live in the platform for various
9reasons. There is no API or ABI guarantee, although we are doing our
10best to provide stability. Documentation for the API is available with
11gtk-doc.
12
13You may download updates to the package from [download.gnome.org](https://download.gnome.org/sources/gnome-desktop/).
14
15To discuss gnome-desktop, you may use the Platform group of [GNOME's
16Discourse instance](https://discourse.gnome.org/c/platform/5).
17
18Installation
19============
20
21gnome-desktop uses [meson](https://mesonbuild.com/Quick-guide.html#compiling-a-meson-project) to build its sources.
22
23[Bubblewrap](https://github.com/containers/bubblewrap), installed as the
24bwrap binary, is a non-optional dependency on platforms where it is
25supported and thumbnailing will silently fail when it is not installed
26at runtime.
27
28[flatpak-xdg-utils](https://github.com/flatpak/flatpak-xdg-utils/)'s `flatpak-spawn`
29helper is a non-optional dependency for using gnome-desktop's thumbnailer
30when the app is being run within Flatpak >= 1.5.1.
31
32How to report bugs
33==================
34
35Bugs should be reported to the [Issues section of gnome-desktop repository](https://gitlab.gnome.org/GNOME/gnome-desktop/-/issues).
36Due to very high numbers of misdirected gnome-shell bugs, the issue tracker has
37unfortunately been restricted to GNOME developers only. If you have found a bug in
38this library, feel free to contact any GNOME developer and ask for your report to be
39forwarded here.
40
41Thumbnailing sandboxing
42=======================
43
44The thumbnailer sandboxing was built to prevent a number of different
45potential attack vectors.
46
47- The attacker wants to steal arbitrary secrets from your machine (a
48 confidentiality failure), or overwrite arbitrary files (an integrity
49 failure).
50- The attacker is assumed to be capable of inducing you to download a
51 crafted thumbnailable object (picture, video, ROM) that will crash a
52 thumbnailer and get arbitrary code execution.
53- Stealing your secrets is prevented by:
54 - only giving the thumbnailer access to the file it's thumbnailing,
55 plus public files from `/usr`-equivalent places, so that it can't
56 leak the content of a secret file into the thumbnail of a less-secret
57 file.
58 - not giving it internet access, so that it can't upload the file it's
59 thumbnailing to Wikileaks.
60- Overwriting arbitrary files is prevented by making the output of the
61 thumbnailer the only thing that can be written from inside the sandbox.
62- Subverting other programs to do one of those is (hopefully) prevented by only
63 allowing it to output PNG thumbnails, because we hope PNG reader libraries are
64 a lot more secure than libraries to read exotic image formats.
65