b03ceb500c
GPGME can be relevant for client applications such as Thunderbird. Pinentry can be relevant for the server side, but it is way less tested in split-gpg2 and discouraged to be used. For: https://github.com/ben-grande/qusal/issues/83
sys-pgp
PGP operations through Qrexec in Qubes OS.
Table of Contents
Description
Creates a PGP key holder named "sys-pgp", it will be the default target for split-gpg and split-gpg2 calls for all qubes. Keys are stored in "sys-pgp", and access to them is made from the client through Qrexec.
Installation
- Top:
sudo qubesctl top.enable sys-pgp
sudo qubesctl --targets=tpl-sys-pgp,sys-pgp state.apply
sudo qubesctl top.disable sys-pgp
sudo qubesctl state.apply sys-pgp.prefs
- State:
sudo qubesctl state.apply sys-pgp.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-pgp state.apply sys-pgp.install
sudo qubesctl --skip-dom0 --targets=sys-pgp state.apply sys-pgp.configure
sudo qubesctl state.apply sys-pgp.prefs
Install on the client template:
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client
The client qube requires the split GPG client service to be enabled:
qvm-features QUBE service.split-gpg2-client 1
Passphrase
In case you plan to use passphrase, install a GUI pinentry:
sudo qubesctl --skip-dom0 --targets=tpl-sys-pgp state.apply sys-pgp.install-pinentry
Client API libraries
If you are using an application that interacts using the GnuPG API instead of the command-line such as Thunderbird, you will need to install on the client a GPGME package specific to your client application. This is not covered by default.
Install GPGME C API library on the client template:
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client-gpgme-c
Install GPGME C++ API library on the client template:
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client-gpgme-c++
Install GPGME Qt API library on the client template:
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client-gpgme-qt
Install GPGME Python API library on the client template:
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client-gpgme-python
Access Control
Default policy: any qube can ask via the @default target if you allow
it to use split-gpg in sys-pgp.
Allow the work qubes to access sys-pgp, but not other qubes:
qubes.Gpg2 * work sys-pgp ask default_target=sys-pgp
qubes.Gpg2 * work @default ask target=sys-pgp default_target=sys-pgp
qubes.Gpg2 * @anyvm @anyvm deny
Usage
Consult upstream documentation on how to use split-gpg2.
On the following examples, we will consider dev as the client qube and
ben as the key user ID.
Service activation
On dom0, enabled the service split-gpg2-client for the client qube dev:
qvm-features dev service.split-gpg2-client 1
Key management on the server
Passphrase protection
Save your PGP keys to sys-pgp, using isolated GnuPG home directory per qube
at ~/.gnupg/split-gpg/<QUBE>.
Please note that adding a passphrase brings no additional value:
Having a passphrase on the key is of little value. An adversary who is capable of stealing the key from your vault would almost certainly also be capable of stealing the passphrase as you enter it. An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key.
Generate a private keys without a passphrase, use the following when
generating a key pair: --pinentry-mode loopback --passphrase ""
If you have already set a passphrase for your private key, you can delete it
by providing the current passphrase to unlock the key, confirming and then
clicking OK with an empty passphrase (the dialog might appear twice):
gpg --homedir ~/.gnupg/split-gpg/dev --edit-key ben passwd
Generate new keys
You should use subkeys, but configuring this key type is for advanced users and out of scope for this document. Please refer to an external source.
On the qube sys-pgp, generate keys for the client qube dev:
mkdir -p -- ~/.gnupg/split-gpg/dev
gpg --homedir ~/.gnupg/split-gpg/dev --pinentry-mode loopback --passphrase "" --gen-key
gpg --homedir ~/.gnupg/split-gpg/dev --list-secret-keys
Import existing keys
On the qube sys-pgp, import keys for the client qube dev:
mkdir -p -- ~/.gnupg/split-gpg/dev
gpg --homedir ~/.gnupg/split-gpg/dev --import /path/to/secret.key
gpg --homedir ~/.gnupg/split-gpg/dev --list-secret-keys
Split key usage on the client
On the client qube dev, import the public part of your key:
gpg --import /path/to/public.key
You should now have access to see the secret keys fingerprints:
gpg --list-secret-keys