KMail: PGP/MIME

OpenPGP/MIME is the successor to the deprecated, non-MIME OpenPGP method of signing emails commonly called "inline OpenPGP". It allows to sign and encrypt attachments, and has less interoperability issues.

KMail 1.5 (which was part of KDE 3.1) and the Ägypten Project made OpenPGP/MIME available the first time to KMail users in the KDE 3.1 release.

This document updates the older version that is still valid for KMail 1.5 and 1.6 (from KDE 3.1 and 3.2) to the new, more integrated approach taken for the KMail 1.7 (KDE 3.3) or later, which is another leap ahead in terms of usability of the cryptograpic message support.

Prerequisites

You need KDE 3.3 or better and GnuPG (1.2.5 <= version <= 1.4.x) You should be able to get those in pre-compiled form from your distribution vendor.

The KDEPIM package should depend on libgpgme >= 0.4.7. If it does not, complain to the packager. This library is now required to build KMail, not the least of reasons being that you, the user, don't need to bother with compiling that yourself anymore. If KDEPIM does not depend on GpgME, there are two alternatives the packager may have taken, both of which are not supported by the KDE project:

The packager uses gpgme-copy in kdepim, which is a statically built GpgME, provided for the convenience of the developers and only compiled if no suitable GpgME is found on the system. This is not meant to be used in packaging, but this howto still applies to this alternative.
The packager has shipped a patched version of KMail that does not require GpgME to build. Needless to say that in this case, this howto won't be of any use for you, since such a stripped-down KMail won't support cryptography anyway.

The KDEPIM package should suggest pinentry (>= 0.7.1). If it does not, complain to the packager. Pinentry comes in different flavours. E.g. in Debian, apt-get install pinentry-qt is recommended if you run a KDE desktop, and apt-get install pinentry-gtk if you run Gnome. If your distribution does not yet provide packages for pinentry, you have to compile it yourself. You can find a tarballs at ftp://ftp.gnupg.org/gcrypt/pinentry/.

You also need the header files for a few libraries:

Pth (>= 1.3.7), usually packaged as libpth-devel (libpth-dev on Debian)
gpg-error (>= 0.7), usually packaged as libgpg-error-devel (libgpg-error-dev on Debian)
libgcrypt (>= 1.1.94), usually packaged as libgcrypt-devel (libgcrypt11-dev in Debian)
libassuan (>= 0.6.6), usually packaged as libassuan-devel (libassuan-dev in Debian)

You should be familiar with KMail's "traditional" GnuPG support as you find it in KDE versions <= 3.0.x (and KMail <= 3.2.x when not using CryptPlugs) as well as with GnuPG itself.

Installing Ägypten II

You'll find all the gory details on the development page of the Ägypten II Project. Here, we concentrate on a minimal install that gives you only the OpenPGP part of Ägypten II.

First, get the following packages:

and unpack them in a directory with tar xfz file.tar.gz.

Now, compile and install them:

cd libksba && ./configure && make && make check && su root -c "make install"
cd gnupg && ./configure --enable-agent-only && make && make check && su root -c "make install"

This builds only the new utility programs (e.g. gpg-agent, watchgnupg, gpgconf) that come with GnuPG 1.9.x, but also work with 1.2.x in most cases (gpgconf needs 1.2.5), and that certain KMail functions rely on (see the KMail and KWatchGnuPG handbooks for more).

Since the library install doesn't call ldconfig, you may need to call it manually when later packages don't find their required libraries!

That's it!

Configure GnuPG to use gpg-agent

If you updated gpg from 1.0.6 or earlier, please make sure to set your own key to ultimate trust yourself, to move the old options file ~/.gnupg/options to the new location ~/.gnupg/gpg.conf and to run

gpg --rebuild-keydb-caches

once. In all cases, add this to your ~/.gnupg/gpg.conf:

use-agent

Add a file ~/.gnupg/gpg-agent.conf with the following contents:

pinentry-program /usr/local/bin/pinentry-qt
no-grab
default-cache-ttl 1800

(replace the path to pinentry-qt depending on where the distribution installed it).

Before using gpg, you need to start gpg-agent:

eval "$(gpg-agent --daemon)"

(gpg-agent outputs a little shell script that sets the environment variable GNUPG_AGENT_INFO). You may want to add this to your ~/.xsession or startkde so that all programs see the environment variable.

Starting with KDE-3.3 you can add the gpg-agent command in ~/.kde/env/gpgagent.sh (the filename doesn't matter). The contents of ~/.kde/env/ is sourced by startkde.

Before you start to configure KMail, please do a short test if GnuPG is working together with the agent.

For this, use a simple command in the shell:

echo "test" | gpg -ase -r 0xDEADBEEF | gpg

Of course, 0xDEADBEAF must be replaced with your own key ID. While running this command the agent should open a graphical password dialog two times. First for signing (gpg -ase) and then for decryption (| gpg).

Starting with gpg 1.2.5, you can use KMail to configure most of the options found in ~/.gnupg/gpg.conf through gpgconf, which was installed along with a few other utilities by the gnupg package in agent-only mode. See KMail's handbook for more info on this.

Check it Works in KMail

Make sure you can work with gpg on the command line that you started gpg-agent in (should use gpg-agent and pinentry-qt).

Start KMail from that terminal and go to Settings->Configure KMail->Security->Crypto Backends. The gpgme-based backend should be auto-detected like this:

(click to enlarge)