elaborate the page on sandboxing

docs/working-with-the-sandbox.rst

@@ -1,7 +1,7 @@
 Working with the Sandbox
 ========================
 
-By default, a flatpak has extremely limited access to the host environment. This includes:
+One of Flatpak's main goals is to increase the security of desktop systems by isolating applications from one-another. This is done using sandboxing and it means that, by default, a Flatpak has extremely limited access to the host environment. This includes:
 
 * No access to any host files except the runtime, the app and ``~/.var/app/$APPID``. Only the last of these is writable.
 * No access to the network.
@@ -11,11 +11,16 @@ By default, a flatpak has extremely limited access to the host environment. This
 * Limited access to the session D-Bus instance - an app can only own its own name on the bus.
 * No access to host services like X, system D-Bus, or PulseAudio.
 
-Most applications will need access to some of these resources in order to be useful, and flatpak provides a number of ways to give an application access to them. The ``build-finish`` command is the simplest of these. As was seen in a previous example, this can be used to add access to graphics sockets and network resources::
+Most applications will need access to some of these resources in order to be useful, and Flatpak provides a number of ways to give an application access to them. While there are no restrictions on which sandbox permissions an application can use, as good practice, it is recommended to use the minimum number of as permissions possible. Certain permissions, such as blanket access to the system bus (using the ``--socket=system-bus`` option) are strongly discouraged.
+
+Configuring sandbox permissions
+-------------------------------
+
+Using the ``build-finish`` command is the simplest way to configure sandbox permissions. As was seen in a previous example, this can be used to add access to graphics sockets and network::
 
   $ flatpak build-finish dictionary2 --socket=x11 --share=network --command=gnome-dictionary
 
-These arguments translate into several properties in the application metadata file::
+These arguments translate into several properties in the application's metadata file::
 
   [Application]
   name=org.gnome.Dictionary
@@ -26,14 +31,36 @@ These arguments translate into several properties in the application metadata fi
   [Context]
   shared=network;
   sockets=x11;
+  
+build-finish allows a whole range of resources to be added to an application. The table at the bottom of this page provides an overview of many of them. The full list can also be viewed using ``flatpak build-finish --help``. These options can also be passed to flatpak-builder as ``finish-args`` properties.
 
-Note that in this example access to the filesystem wasn't granted. This can be tested by installing the resulting application and running::
+.. note::
+  Until a sandbox-compatible backend is available, access to dconf needs to be enabled using the following options::
 
-  $ flatpak run --command=ls org.gnome.Dictionary ~/
-  
-build-finish allows a whole range of resources to be added to an application. Run ``flatpak build-finish --help`` to view the full list.
+    --filesystem=xdg-run/dconf
+    --filesystem=~/.config/dconf:ro
+    --talk-name=ca.desrt.dconf
+    --env=DCONF_USER_CONFIG_DIR=.config/dconf
+
+Portals
+-------
+
+Portals are the mechanism through which applications can interact with the host environment from within a sandbox. In this way, they give additional abilities to interact with data, files and services without the need to add sandbox permissions. Interface toolkits can implement transparent support for portals. If an application is using one of these toolkits, there is no additional work required to use them.
+
+Examples of capabilities that can be accessed through portals include:
+
+* Sending an item to be printed
+* Taking a screenshot
+* Showing a notification
+* Finding out network status
+* Opening a file using a native file chooser dialog
+
+Applications that aren't using a toolkit with support for portals can refer to the `xdg-desktop-portal API documentation <http://flatpak.org/xdg-desktop-portal/portal-docs.html>`_ for information on how to access them.
+
+Overriding sandbox permissions
+------------------------------
 
-There are several ways to override the permissions that are set in an application's metadata file. One of these is to override them using flatpak run, which accepts the same parameters as ``build-finish``. For example, this will let the Dictionary application see your home directory::
+When developing an application, it can sometimes be useful to temporarily override a Flatpak's sandbox configuration. There are several ways to do this. One is to override them using ``flatpak run``, which accepts the same parameters as ``build-finish``. For example, this will let the Dictionary application see your home directory::
 
   $ flatpak run --filesystem=home --command=ls org.gnome.Dictionary ~/
   
@@ -49,7 +76,7 @@ It is also possible to remove permissions using the same method. You can use the
 Useful sandbox permissions
 --------------------------
 
-Flatpak provides an array of options for controlling sandbox permissions. The following are some of the most useful.
+Flatpak provides an array of options for controlling sandbox permissions. The following are some of the most useful:
 
 ===============================================  ===========================================
 --filesystem=host                                Access all files
@@ -65,7 +92,7 @@ Flatpak provides an array of options for controlling sandbox permissions. The fo
 --share=network                                  Access the network [#f2]_
 --talk-name=org.freedesktop.secrets              Talk to a named service on the session bus
 --system-talk-name=org.freedesktop.GeoClue2      Talk to a named service on the system bus
---socket=system-bus --socket=session-bus         Unlimited access to all of D-Bus
+--socket=system-bus                              Unlimited access to all of D-Bus
 ===============================================  ===========================================
 
 .. rubric:: Footnotes