Simplify Split GPG-2

I came across the diataxis approach and used it to get a better understanding
of this page. Additionnaly, I did this:

* move instructions to edit a policy and to enable a service qube to the
  related pages
* clean the structure of the server options and make them
  cross-referenceable using `:confval:` role

Author: parulin

attachment/split-gpg2/client-qube-settings.png

@@ -2,128 +2,76 @@
 Split GPG-2
 ===========
 
-Split GPG-2 allows less trusted qubes to delegate GPG operations to another trusted qube (i.e. a network-isolated qube). The encryption, decryption and signing operations are handled by the trusted qube.
+Qubes OS allows you to split the management and usage of GPG keys. You can store your secret keys in one trusted qube and use them in another less trusted qube.
 
-With Split GPG-2, you can use the Thunderbird mail client in one qube, and hold your GPG secret keys in another qube. This way the compromise of your qube where Thunderbird is running does not allow the attacker to automatically also steal all your keys.
+This way the compromise of your less trusted qube does not allow the attacker to automatically also steal all your keys.
 
-.. figure:: /attachment/doc/split-gpg-diagram.png
-   :alt:
-
-   Example of the Split GPG-2 architecture
-
-   In a qube called *work-email* (with a green level of trust), ``qubes-gpg-client`` pretends to be a standard ``/usr/bin/gpg`` to other apps, here with Thunderbird.
-
-   In the *work-email* qube, ``qubes-gpg-client`` is communicating with ``qubes-gpg-server`` located in the *work-gpg* qube (with a black level of trust). The communication is made through the ``qubes.Gpg2`` remote procedure call using the ``qrexec`` protocol.
+How-to split your GPG keys between two qubes
+--------------------------------------------
 
-   Inside the *work-gpg* qube, ``qubes-gpg-server`` has access to the GPG key, through ``/usr/bin/gpg``.
-
-The following page will setup Split GPG-2 with two qubes:
-
-* one qube holding the private keys, called **server-qube** (in the previous example, it is the role of *work-gpg*)
-* the other qube using the keys, called **client-qube** (in the previous example, it *work-email*, where Thunderbird is used)
-
-Installation of Split GPG-2
----------------------------
-
-In the template(s) qube(s) used by *server-qube* and *client-qube*, install ``split-gpg2``:
-
-* **with Fedora**:
-
-   .. code:: console
+The following how-to will setup Split GPG-2 with two qubes:
 
-      [root@fedora-template] # dnf install split-gpg2
+* one qube holding the private keys, called **server-qube**. This qube is offline and should be trusted.
+* the other qube using the keys, called **client-qube**. This qube doesn't have to be trusted as much as the server.
 
-* **with Debian**:
+Each time you want to do something with a GPG key, the *client-qube* will delegate the operation to the *server-qube*. This qube will ask you to confirm the operation.
 
-   .. code:: console
+Install Split GPG-2
+^^^^^^^^^^^^^^^^^^^
 
-      [root@debian-template] # apt install split-gpg2
+In the template(s) qube(s) used by *server-qube* and *client-qube*, :ref:`install the split-gpg2 package <user/how-to-guides/how-to-install-software:installing software from default repositories>`.
 
 .. note:: If you use a minimal template, make sure to install ``zenity``
 
-Configuration of Split GPG-2
-----------------------------
-
-Create a new policy in dom0
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create a policy for Split GPG-2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**In dom0**, create or edit a RPC policy. Use either the *Qubes OS Policy Editor* program or the ``qubes-policy-editor`` command. You can call is :file:`{30-user-gpg2}.policy` or something else. Add a line like the following and make sure to replace :samp:`{client-qube}` and :samp:`{server-qube}` by the appropriate values.
+**In dom0**, :doc:`create or edit a RPC policy </user/how-to-guides/how-to-edit-a-policy>`. Add a line like the following and make sure to replace :samp:`{client-qube}` and :samp:`{server-qube}` by the appropriate values.
 
 .. code:: text
 
       qubes.Gpg2 + client-qube @default allow target=server-qube
 
 Generate or import the secret keys in the server qube
-"""""""""""""""""""""""""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**In server-qube**:
+**In server-qube**, you have two options:
 
-* generate your secret keys, like this:
+* either generate your secret keys, like this:
 
    .. code:: console
 
          [user@server-qube] $ gpg --gen-key
 
-   In that case, you have to export the public part of your keys and the "ownertrust" values in the client qube:
-
-   .. code:: console
-
-         [user@server-qube] $ gpg --export > public-keys-export
-         [user@server-qube] $ gpg --export-ownertrust > ownertrust-export
-         [user@server-qube] $ qvm-copy public-keys-export ownertrust-export
-
-   .. warning:: do not export the private keys !
-
-* or import your secret keys, like the following example. Make sure to replace :file:`/path/to/my/{name-of-the-file}` by the path of the expected file:
+* or, if you want to use some old keys, previously generated in an other qube, import them and the ownertrust. Make sure to replace :file:`/home/user/QubesIncoming/{<SOME_OTHER_QUBE>}/{[...]}` by the path of the expected file:
 
    .. code:: console
 
-         [user@server-qube] $ gpg --import /path/to/my/secret-keys-export
-         [user@server-qube] $ gpg --import-ownertrust /path/to/my/ownertrust-export
-
-Set up the client qube
-^^^^^^^^^^^^^^^^^^^^^^
-
-The first step is to enable the ``split-gpg2-client`` service. There is two options to do it, with the client qube's settings or with the ``qvm-service`` command.
-
-Enable ``split-gpg2-client`` with the qube's settings
-"""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-Follow these steps:
-
-1. Open the *client-qube*'s settings
-2. Select the :guilabel:`Services` tab
-3. At the top, in :guilabel:`Select a service`, select :guilabel:`split-gpg2-client`
-4. Click on the :guilabel:`Add` button
-5. Click on :guilabel:`Apply` or :guilabel:`Ok` to validate
-
-.. figure:: /attachment/split-gpg2/client-qube-settings.png
-   :alt:
+         [user@server-qube] $ gpg --import /home/user/QubesIncoming/<SOME_OTHER_QUBE>/secret-keys-export
+         [user@server-qube] $ gpg --import-ownertrust /home/user/QubesIncoming/<SOME_OTHER_QUBE>/ownertrust-export
 
-   :guilabel:`split-gpg2-client` should be listed and the checkbox in front of this service should be checked.
-
-Enable ``split-gpg2-client`` with ``qvm-service``
-"""""""""""""""""""""""""""""""""""""""""""""""""
-
-Enable the service in the *client-qube*:
+In both situations, you have to export the public part of your keys and the "ownertrust" values in the client qube:
 
 .. code:: console
 
-      [user@dom0] $ qvm-service client-qube split-gpg2-client on
+ [user@server-qube] $ gpg --export > public-keys-export
+ [user@server-qube] $ gpg --export-ownertrust > ownertrust-export
+ [user@server-qube] $ qvm-copy public-keys-export ownertrust-export
 
-To verify if this was done correctly type the following command and check that the output on the second line is ``on``:
+.. warning:: do not export the private keys !
 
-.. code:: console
+Set up the *client qube*
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-      [user@dom0] $ qvm-service client-qube split-gpg2-client
-      on
+Enable ``split-gpg2-client`` service in *client qube*
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-If *client-qube* is running, restart it.
+The first step is to :doc:`enable the qube service </user/how-to-guides/how-to-enable-a-service>` called ``split-gpg2-client``.
 
 Import the public keys and ownertrust
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""""
 
-You have previously exported the public keys and the "ownertrust" values from *server-qube*. Now, you have to import them in the client qube. Replace the following paths by the correct values.
+If you have previously exported the public keys and the "ownertrust" values from *server-qube*. Now, you have to import them in the client qube. Replace the following paths by the correct values.
 
 .. code:: console
 
@@ -133,7 +81,7 @@ You have previously exported the public keys and the "ownertrust" values from *s
 Check that Split GPG-2 works
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This should be enough to have it running:
+You should be able to run ``gpg -K`` in the *client qube*:
 
 .. code:: console
 
@@ -146,24 +94,24 @@ This should be enough to have it running:
       ssb#  rsa2048 2019-12-18 [E]
 
 Troubleshooting
----------------
+^^^^^^^^^^^^^^^
 
 ``gpg-agent`` only shows the "keygrip"
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""""""
 
 If you have a passphrase on your keys and ``gpg-agent`` only shows the “keygrip” (something like the fingerprint of the private key) when asking for the passphrase, then make sure that you have imported the public key part in the server domain.
 
 Subkeys vs primary keys
-^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""
 
 Split GPG-2 only knows a hash of the data being signed. Therefore, it cannot differentiate between e.g. signatures of a piece of data or signatures of another key. This means that a client can use Split GPG-2 to sign other keys, which :doc:`split-gpg` did not allow.
 
 To prevent this, Split GPG-2 creates a new GnuPG home directory and imports the secret subkeys (**not** the primary key!) to it. Clients will be able to use the secret parts of the subkeys, but not of the primary key. If your primary key is able to sign data and certify other keys, and your only subkey can only perform encryption, this means that all signing will fail. To make signing work again, generate a subkey that is capable of signing but **not** certification. Split GPG-2 does not generate this key for you, so you need to generate it yourself. If you want to generate a key in software, use the ``addkey`` command of ``gpg2 --edit-key``. If you want to generate a key on a smartcard or other hardware token, use ``addcardkey`` instead. You will need to import your public keys again.
 
-Advanced usage
+Server options
 --------------
 
-If you want change some server option copy :file:`/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to :file:`/home/user/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix ``.conf`` in `/home/user/.config/qubes-split-gpg2/conf.d/`.
+If you want change some server option, copy :file:`/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to :file:`/home/user/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix ``.conf`` in `/home/user/.config/qubes-split-gpg2/conf.d/`.
 
 By setting up some values in the configuration file, you can change some parameters. The configurations files are INI files, you can set global options in the ``DEFAULT`` section, or provide some client specific options in their own :samp:`client:{QUBE_NAME}` section (where ``QUBE_NAME`` is the name of the client). The following configuration is an example where no qube is automatically accepted besides *personal* qube:
 
@@ -175,52 +123,88 @@ By setting up some values in the configuration file, you can change some paramet
    [client:personal]
    autoaccept = yes
 
-Automatically accept requests
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. confval:: autoaccept
 
-By default, all requests made to the *server-qube* need to be confirmed. If you already use a RPC policy to ask confirmation, you can tell Split GPG-2 to automatically accept all requests, always or during a period of time after a successful request. You have to put something like this in you configuration file:
+   :type: text
+   :default: ``no``
+   :allowed values: ``no``, ``yes`` or any integer
 
-.. code:: ini
+   By default, all requests made to the *server-qube* need to be confirmed. You can tell Split GPG-2 to accept requests: never (``no``), always (``yes``) or during a period of time after a successful request. To accept all requests following a successful one during one minute, use a value of ``60`` seconds.
 
-   autoaccept = yes
+This option has two alternatives:
 
-To accept all requests following a successful one during one minute (60 seconds), use this:
+.. confval:: pksign_autoaccept
 
-.. code:: ini
+   :type: boolean or integer
+   :default: ``no``
+   :allowed values: ``no``, ``yes`` or any integer
 
-   autoaccept = 60
+   same as :confval:`autoaccept` but only for signing requests
 
-This option has two alternatives:
+.. confval:: pkdecrypt_autoaccept
 
-``pksign_autoaccept``
-   same as ``autoaccept`` but only for signing requests
+   :type: boolean or integer
+   :default: ``no``
+   :allowed values: ``no``, ``yes`` or any integer
 
-``pkdecrypt_autoaccept``
-   same as ``autoaccept`` but only for decrypt requests
+   same as :confval:`autoaccept` but only for decrypt requests
 
-Notifications
-^^^^^^^^^^^^^
+.. confval:: verbose_notifications
 
-Setting ``verbose_notifications`` to ``yes`` will provide more notifications.
+   :type: boolean
+   :default: ``no``
+   :allowed values: ``no`` or ``yes``
 
-Edit GnuPG home
-^^^^^^^^^^^^^^^
+   Setting ``verbose_notifications`` to ``yes`` will provide more notifications.
+
+.. confval:: allow_keygen
+
+   :type: boolean
+   :default: ``no``
+   :allowed values: ``no`` or ``yes``
+
+   .. warning:: This feature is new and not much tested. Therefore it’s not security supported!
+
+   By setting :confval:`allow_keygen` to ``yes``, you can allow the client to generate new keys. Normal usage should not need this.
+
+.. confval:: gnupghome
 
-You can set up a different GnuPG home from the default :file:`/home/user/gpg-home`, using ``gnupghome``.
+   :type: full path
+   :default: empty
 
-If you store different keys for different client qubes in the same server qube, you can isolate each GnuPG home, by setting ``isolated_gnupghome``. The value points at a directory where each client will get its own subdirectory. For example when this option is set to :file:`/home/user/gpg-home`, then the qube *personal* will use :file:`/home/user/gpg-home/{personal}` as GnuPG home.
+   You can set up a different GnuPG home from the default :file:`/home/user/gpg-home`, using :confval:`gnupghome`.
 
-If you do this, don't forget to use the option ``--gnupg-home`` or the environment variable ``GNUPGHOME`` when using ``gpg`` commands.
+.. confval:: isolated_gnupghome
 
-Allow key generation
-^^^^^^^^^^^^^^^^^^^^
+   :type: full path
+   :default: empty
 
-.. warning:: This feature is new and not much tested. Therefore it’s not security supported!
+   If you store different keys for different client qubes in the same server qube, you can isolate each GnuPG home, by setting :confval:`isolated_gnupghome`. The value points at a directory where each client will get its own subdirectory. For example, when this option is set to :file:`/home/user/gpg-home`, then the qube *personal* will use :file:`/home/user/gpg-home/{personal}` as GnuPG home.
 
-By setting ``allow_keygen = yes`` in ``qubes-split-gpg2.conf`` you can allow the client to generate new keys. Normal usage should not need this.
+   If you do this, don't forget to use the option ``--gnupg-home`` or the environment variable ``GNUPGHOME`` when using :program:`gpg` commands.
 
-Notes
------
+.. confval:: debug_log
+
+   :type: path
+   :default: empty
+
+   Enable debug logging and set the debug log path.
+
+   .. warning:: This is for debugging purpose only, **everything will be logged** including potentially confidential data/keys/etc
+
+Notes about Split GPG-2
+-----------------------
+
+.. figure:: /attachment/doc/split-gpg-diagram.png
+   :alt:
+
+   Example of the Split GPG-2 architecture
+
+   In a qube called *work-email* (with a green level of trust), ``qubes-gpg-client`` pretends to be a standard ``/usr/bin/gpg`` to other apps, here with Thunderbird.
+
+   In the *work-email* qube, ``qubes-gpg-client`` is communicating with ``qubes-gpg-server`` located in the *work-gpg* qube (with a black level of trust). The communication is made through the ``qubes.Gpg2`` remote procedure call using the ``qrexec`` protocol.
+
+   Inside the *work-gpg* qube, ``qubes-gpg-server`` has access to the GPG key, through ``/usr/bin/gpg``.
 
 Using Split GPG-2 with Split GPG-1
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -230,7 +214,7 @@ Using Split GPG-2 as the “backend” for :doc:`split-gpg` is known to work.
 Advanced usage: checking what is signed, etc.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Similar to a smartcard, Split GPG-2 only tries to protect the private key. For advanced usages, consider if a specialized RPC service would be better. It could do things like checking what data is singed, detailed logging, exposing the encrypted content only to a VM without network, etc.
+Similar to a smartcard, Split GPG-2 only tries to protect the private key. For advanced usages, consider if a specialized RPC service would be better. It could do things like checking what data is signed, detailed logging, exposing the encrypted content only to a VM without network, etc.
 
 Advantages of Split GPG vs. traditional GPG with a smart card
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^