Gentoo Wiki



K Desktop Environment

Location: KMail

KDE Pages









KMail is the internet mail client that comes shipped with KDE in its kdepim package. It offers IMAP (disconnected and live), POP3, mbox and Maildir support. It also has advanced configuration options for handling mailing lists, including automatic addressing of replies, subscription management, incoming filtering, and automatic selection of sending profile. It also, as of version 1.7 (shipped with KDE 3.3.0) has support for MIME-encapsulated GPG, PGP and S/MIME emails. Prior to version 1.7, only inline support was available. This functionality is what this HOWTO covers. More information about KMail can be found at However, the documentation hasn't been updated since the release of KDE 3.3.0.


How to set up gpg-agent for use with KDE and KMail


What is gpg?

GnuPG is commonly called gpg. GnuPG stands for GNU Privacy Guard. It's a complete and free replacement for PGP. In short, it's a public key encryption scheme that is fully RFC 2440 compliant. For more information about GnuPG, please visit its website at

What is gpg-agent?

gpg-agent is a program that caches your private key passphrases for a period of time. Without gpg-agent you'd have to type your passphrase every time you wanted to decrypt an email or file. Since it is recommended that your passphrase be very long, and hard to guess, this can become cumbersome.

Package Requirements

This HOWTO covers using KMail and gpg-agent in conjunction with the KDE Desktop Environment.

The first you'll want to do is install KMail. KMail is part of the kdepim package, which requires most of the rest of KDE, so you may be compiling for a while.

First, make sure you have crypt ( It worked without this flag for me, see discussion... ) and qt3 ( Without this, kmail won't be able to open the pinentry password dialog. ) in your USE flags, and then:

$ emerge kdepim-meta gnupg pinentry

Optionally, if you'd like to have a gui for setting up your keys and such, you can use gpa or kgpg.

Please see this guide for instructions on how to generate and publish your GPG key.


Setting up gpg-agent with KDE

In order to use the gpg-agent with KDE, you'll want it to start up and have its environment variables added to KDE's environment before KDE starts. Thankfully, KDE allows us to do this quite easily. You can enable gpg-agent for use system-wide or on a per-user basis.

System-wide setup
  1. Uncomment the lines pertaining to gpg-agent in /usr/kde/*/env/
  2. Restart your KDE session, if applicable.
  3. Uncomment the lines pertaining to GPG_AGENT_INFO in /usr/kde/*/shutdown/
Per-user setup
  1. Create the directory ~/.kde/env
  2. Create a file in the directory called (the actual filename is irrelevant, so long as it ends in .sh) like so:
File: ~/.kde/env/
eval `gpg-agent --daemon`
  1. Make the file executable (doubt this is necessary as it's probably sourced rather than executed)
  2. Log out of KDE if you're in KDE and log back in.

  1. Create the directory ~/.kde/shutdown
  2. Create a file in the directory called (again the filename is irrelevant) like so:
File: ~/.kde/shutdown/
# the second field of the GPG_AGENT_INFO variable is the
# process ID of the gpg-agent active in the current session
# so we'll just kill that, rather than all of them :)
[ -n "${GPG_AGENT_INFO}" ] && kill `echo "${GPG_AGENT_INFO}" | cut -d ':' -f 2`
  1. Make the file executable, as KDE executes this file when you shut down.

Setting up gpg-agent with keychain

Alternatively you can set up gpg-agent to work with keychain so you will have passphrase caching independent of KDE.

emerge keychain

Add the following snippet to your ~/.bash_profile (see man keychain for other shells), replacing XXXXXXXX with your key ID:

File: ~/.bash_profile
keychain id_rsa id_dsa XXXXXXXX
[[ -f $HOME/.keychain/$HOSTNAME-sh ]] && \
 source $HOME/.keychain/$HOSTNAME-sh
[[ -f $HOME/.keychain/$HOSTNAME-sh-gpg ]] && \
 source $HOME/.keychain/$HOSTNAME-sh-gpg

Setting up KMail to use GnuPG to sign/encrypt messages

KMail needs some minor menu/dialog based configuration to be able to sign and encrypt messages using GnuPG.

  1. Start up KMail
  2. Go to the Settings menu and select Configure KMail...
  3. Select the Security icon on the left hand side
  4. Select the Crypto Backends tab
  5. Make sure OpenPGP (gpg) is in the list, and check the box next to it.
  6. Select the Identities Icon on the left hand side
  7. If you haven't already created an identity for yourself, create one now.
  8. Select your identity and click the Modify... button
  9. Select the Cryptography tab
  10. Click on Change... next to OpenPGP signing key and select your preferred key from the list.
  11. Repeat for OpenPGP encryption key if you want to encrypt messages
  12. Make sure the Preferred crypto message format is either Any or OpenPGP/MIME. The inline format is deprecated, and highly annoying to users of mail client software that doesn't support this standard. This is the "old" way of doing things, and the OpenPGP/MIME format is the preferred method.
  13. Click OK in the edit identity window and in the preferences window.

Now, when you go to send an email you'll have to click on the toolbar button in the compose window that looks like a fountain pen drawing a spiral. The lock just to the right of it is to encrypt the message, and the dropdown box to the right of that is to select the encapsulation type. It should normally say OpenPGP/MIME, but it's there so you can change it on the fly if need be.

Send yourself an email to test! Feel free to email if you would like to report success. Try sending yourself an email to make sure it's signed before you send me an email ;)

If all went well, when you send yourself an email, and open it, it should look something like this:

If you selected a key to use to encrypt messages you can try to send yourself an encrypted message. Compose a new message and make sure to click on the lock in the toolbar. If you wish to encrypt an email to someone else you must have their public key. My public key is at Once again, feel free to send me an encrypted message to report success, however, please test on yourself before flooding my inbox with test messages :)

After sending yourself an encrypted message, if all went well, KMail should display it like this: (note: you may be prompted for a password to decrypt the message if your gpg-agent has expired your passphrase from its cache)

Now you're successfully using KMail to send and receive signed and encrypted messages. Remember that the more people use tools like PGP and GnuPG, the safer the internet can become. You can sincerely tell someone you never sent an email they said you sent because it wasn't signed with your key, and you can send sensitive information safely between your peers with encrypted messages!

Tips and Tricks

gpg-agent, by default, uses ~/.gnupg/gpg-agent.conf as its configuration file. In this file you can specify any option you can on the command line (for information on command line options, type gpg-agent --help or info gpg-agent).

gpg-agent, by default, will cache your passphrase for 600 seconds (10 minutes). If you want, you can increase or decrease this value, either in your gpg-agent startup command line, or (preferably) in ~/.gnupg/gpg-agent.conf. Just add 'default-cache-ttl XXXX', where XXXX is a number of seconds you want it to cache your passphrase (I use 3600) to it and the next time you log in you'll be able to go longer between entering your passphrase!

This will only work for a cache limit below 7200 (two hours). if you want to set a higher default-cache-ttl you need to change the max-cache-ttl also. For example if you want to set the timeout to 1 day add the following two lines in your ~/.gnupg/gpg-agent.conf:

File: ~/.gnupg/gpg-agent.conf
default-cache-ttl 86400
max-cache-ttl 86400

If kmails fails decrypting with the following message:

Encrypted message (decryption not possible)
Reason: Crypto plug-in "openpgp" could not decrypt the data.
Error: Bad passphrase
Encrypted data not shown.
End of encrypted message

Make sure you wrote everything correct and make a symlink to gpg-agent:

$ ln -s /usr/bin/gpg-agent /usr/bin/gnupg-agent

(at least this worked for me(nochnamenlos))

Comments, questions, flames, and suggestions always welcome in my inbox. Feel free to email me or contact me in #gentoo on EFNet IRC. :)

Kitchen 05:47, 17 Sep 2004 (GMT)

S/MIME support

In this example, I created a Thawte "Personal E-mail Certificates", but it should work with any other provider.

Here are the operations :

  1. Check that you have the needed packages installed :
    • emerge -av pinentry gnupg gpgme
  2. Get your certificate from
    • Go to Thawte[] web site. This is important that you use Firefox because the keys are generated by the browser. (This does not work with Konqueror)
    • In the menu, choose Products -> Free Personal E-mail Certificates.
    • Click here to get your Personal E-mail Certificate now! Register and validate your email...
    • When the certificate will be available (less than 5 minutes for me), you will receive an email. You can go to the web site, and chose Fetch certificate. ( In certificates -> view certificate status, you will see the list of certificates, under the Type column, you can click on the link (Navigator) in order to access the fetch page. ) Chose the Firefox PKCS#12 format. The certificate will automatically be imported in Firefox without notice.
  3. In Firefox, Edit -> Preferences -> Advanced -> Security, you can "Display certificates" and check that it's well there.
  4. From there, you can export it. (I chose certbundle.p12 as filename )
  5. Follow informations here :

Common Problems

I've been unable to import my p12 file as described : pivert@pivert ~ $ gpgsm --call-protect-tool --p12-import --store certkey.p12 gpg-protect-tool: problem with the agent gpg-protect-tool: error while asking for the passphrase: Invalid public key algorithm Solution : Be sure that you have the right pinentry in your .gnupg/gpg-agent.conf In my case, I had to install the pinentry with qt3 flag :

pivert portage # emerge -av pinentry

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild   R   ] app-crypt/pinentry-0.7.2-r2  USE="gtk ncurses qt3" 0 kB

I did have pinetry installed, but got the same error until I started up gpg-agent. See HOWTO KMail gpg-agent kde for info on this.

Retrieved from ""

Last modified: Sat, 06 Sep 2008 15:51:00 +0000 Hits: 3,531