Petition for a Software Patent Free Europe

Secure Mail with Balsa 2.3 HOWTO


1 Introduction
2 Crypto Support in Balsa 2.3
3 Installation
3.1 Prerequisites for OpenPGP and PGP/MIME Support
3.2 Prerequisites for S/MIME Support
3.3 Building Balsa with Crypto Support
4 Using Balsa's Crypto Support
4.1 Gpg Setup
4.2 Gpg-Agent and Pinentry Setup
4.3 GpgSM Setup
4.4 Sending Messages
4.5 Receiving Messages
5 Customisation
5.1 Identities
5.2 Mailboxes
5.3 Caching Passphrases
6 FAQ's
7 Links

1 Introduction

The privacy of letters as well as the secrecy of post and telecommunication are inviolable.
Article 10(1) of the German Basic Law [Constitution]

In almost every free country in the world similar laws exist to protect the privacy of all your communication, including e-mails. In reality, however, these regulations are violated every day, by snoopy family members, the sys op in your corporate network, or by state-run systems like the notorious US's Echelon interception network. Furthermore, mails can be manipulated on all network nodes between your sending and the receiving machine.

To protect your privacy or your company's secret stuff, you can

Three different Internet Standards have been defined to accomplish these tasks:

The first two standards build on top of the GnuPG (or the commercial well-known PGP) application, which uses pairs of public and private keys for encrypting and signing. Please see the excellent GnuPG MiniHOWTO for further details. The S/MIME standard builds on a chain of certificates like e.g. TLS (RFC2246).

Using RFC 3156, complete messages are put into special "containers" (MIME types multipart/signed or multipart/encrypted) and signed and/or encrypted. This means that even the message structure itself (if the message contains attachments) as well as all attachments are protected and (in the encrypted case) hidden. Mail User Agents (MUAs) which support this standard include Sylpheed, Evolution, KMail, Mutt and Mozilla with the Enigmail plugin.

RFC 2633 or S/MIME basically uses the same MIME structures, although they may be named differently (besides multipart/signed, application/pkcs7-mime is used for encrypted and sometimes for signed messages). The main difference to the GnuPG methods is that you need a certificate which has been signed by a Certificate Authority (CA). When receiving messages, you don't check the key trust itself but whether you trust the signing certificate or not. While for "normal" users the GnuPG/PGP key "web of trust" is usually more efficient, S/MIME is frequently used in big companies or government environments. S/MIME can also be used in conjunction with stuff like smartcards, adding an other layer of security. MUAs supporting S/MIME are inter alia Evolution, Mozilla and all applications supporting the Ägypten Sphinx plugins like KMail and Mutt.

RFC 2440 is an older protocol which uses GnuPG to sign and/or encrypt only a message part. Usually all attachments are transmitted unprotected, and it is not possible to protect the message structure itself. Therefore, this protocol should be used only if necessary, i.e. if the receiving MUA does not understand the more sophisticated modern protocols above. MUAs supporting RFC 2440 include pine with pgp4pine and Micro$oft Outlook with the GData GnuPG Plugin.

At this point it should be noted that the "message envelope" (subject, date etc.) is not protected by any of these protocols. Therefore, they could still be manipulated by an attacker and of course be read by everyone (think of a letter's envelope).

2 Crypto Support in Balsa 2.3

Since the release of Balsa version 2.2.6 which in turn requires gmime version 2.1.9 or newer, crypto support for Balsa is again fully functional. With some additional libraries and applications installed, Balsa 2.3 supports all three aforementioned crypto protocols.

3 Installation

Balsa's support for OpenPGP (RFC 2440) and PGP/MIME (RFC 3156) and for S/MIME (RFC 2633) needs different additional software to be installed on your system, so the installation is split up into an OpenPGP and a S/MIME section. Please read both sections if you plan to use all three protocols as some stuff overlaps. You might also want to skip forward to the section Caching Passphrases below to check if you want to use it (which in turn needs most of the the Prerequisites for S/MIME Support to be installed).

3.1 Prerequisites for OpenPGP and PGP/MIME Support

If you want to sign and/or encrypt messages with GnuPG/PGP keys, you need to install in this order (Note: the versions given reflect the status of May 6th, 2006):

I also recommend to install all additional software needed for gpgsm, as Balsa 2.3 (unlike Balsa 2.0) does not have an internal passphrase cache any more. If you install gpg-agent (which is mandatory for S/MIME support) you get a much more secure cache for all applications using gpg or gpgsm. Please see the S/MIME prerequisites section below for details.

3.2 Prerequisites for S/MIME Support

For S/MIME support, you will need GpgSM which is the S/MIME counterpart to gpg developed in the Ägypten project. It depends on a lot of other applications and libraries, so the installation is not completely trivial. The following list summarises the necessary stuff in the recommended installation order. Remember that you will need additional software if you want to add e.g. Smartcard support (Note: the versions given reflect the status of May 6th, 2006):

3.3 Building Balsa with Crypto Support

To enable the GnuPG crypto support in Balsa, configure it using the command
./configure <your favorite config options> --with-gpgme[=<gpgme configure script>]
If you installed gpgme in a standard path, just giving --with-gpgme should be sufficient. Otherwise, add the full path of the gpgme configure script, like --with-gpgme=/opt/crypto/gpgme-latest/bin/gpgme-config.

If you additionally want to have S/MIME support, add --enable-smime to the configure options. Please note that Balsa's S/MIME support is still experimental.

Then re-build and re-install Balsa as usual.

If you want to add more security to the applications installed above (or earlier), in particular gpg*, gpgsm, gpg-agent, and pinentry*, you may change their permissions to SUID root. In this case, they will use unswappable memory for all sensitive information, thus avoiding traces on swap space.

4 Using Balsa's Crypto Support

4.1 Gpg Setup

Note: you should follow the instructions in this section only if you want to use RFC 2440 or RFC 3156 support in balsa.

The configuration options for gpg are taken from the file ~/.gnupg/gpg.conf (new style, preferred) or ~/.gnupg/options (old style, depracted, and used only if ~/.gnupg/gpg.conf is not present). A reasonable setup which works well with keyservers and uses gpg-agent to ask for passphrases and to cache them (see section Caching Passphrases below) should have the following lines:

keyserver-options honor-http-proxy,auto-key-retrieve
If you don't want to install a passphrase cache remove or comment out the last line. If your machine has no permanent connection to the internet, you might want to remove auto-key-retrieve from keyserver-options to prevent gpg from triggering a dial-in each time it hits an unknown key. Please see the gpg info page for further information about the config options.

Please note that Seahorse tweaks this file directly, so you should avoid changing this file manually if you use Seahorse.

4.2 Gpg-Agent and Pinentry Setup

Note: you must set up gpg-agent and pinentry either when you use either gpgsm or when you use gpg-agent for passphrase chaching (see section Caching Passphrases below). Otherwise, just skip this section.

Gpg-agent and pinentry are controlled by the config file ~/.gnupg/gpg-agent.conf. In this file, you tell them how long they should cache passphrases, which pinentry binary gpg-agent calls, and that it should also manage certificate trusts (please use the right path and pinentry binary):

default-cache-ttl 3600
pinentry-program /usr/bin/pinentry-gtk-2
Please see the gpgsm info pages for details about the options of the agent.

Usually, you want to launch the agent automagically when you log in. To this end, add the statements

eval `gpg-agent --daemon -s`
echo $GPG_AGENT_INFO > $HOME/.gpg-agent-info
to a file Gnome (or X) reads at startup, e.g. $HOME/.xsession (note that this may depend on your distribution). This statement should set and export the environment variable GPG_AGENT_INFO properly and write it's value into a file in the user's home folder. If you want to use the gpg agent also when when running gpg and friends from a terminal or the console, you should add
if [ -z "$GPG_AGENT_INFO" ] ; then
     if [ -f $HOME/.gpg-agent-info ] ; then
         export GPG_AGENT_INFO=$(cat .gpg-agent-info)
export GPG_TTY=$(tty)
to your $HOME/.bashrc which ensures that it will be found and called with the correct tty setting.

Remember that the gpg agent will not be shut down when you exit your Gnome (or other X) session. To kill it automatically in this case, I added to the gdm config file /etc/X11/gdm/PostSession/Default

if [ -f $GPGAGENTINFO ] ; then
     AGENTPID=$(cat $GPGAGENTINFO | sed -e 's/^[^:]*://' -e 's/:.*//')
     if [ -n "$AGENTPID" ] ; then
         kill -TERM $AGENTPID > /dev/null 2>&1
     rm -f $GPGAGENTINFO
Note that you will need to tweak other files when you are using a different dsiplay manager.

Please see also the gpg info page coming with gpg 1.9.x (node "Invoking GPG-AGENT") for further details about the proper installation of the agent.

4.3 GpgSM Setup

Note: this section is relevant only if you built balsa with S/MIME (RFC 2633) support. Otherwise, just skip it.

GpgSM preferences — GpgSM's preferences are taken from the file ~/.gnupg/gpgsm.conf. Usually, the defaults are just fine, but for testing purposes it might be convenient to disable the CRL (Certificate Revocation List) checks. To this end, add the line

to this file. Please remember to remove it again when you use gpgsm in a production environment. Please see the gpg info page coming with gpg 1.9.x for further details.

S/MIME Key — Due to the nature of S/MIME, you can not simply create a key pair and start as you did (did you?) with gpg/pgp keys. You can get a key from several CA's; I got mine for free from Thawte. As they usually provide keys only for e.g. Mozilla, you have to use openssl to insert them into your gpgsm key rings. Matthias Welwarsky wrote a nice Small HowTo on how to import freemail S/MIME certificates into GPGSM about this.

4.4 Sending Messages

[compose options]When sending a message, Signing and Encryption can be activated by checking the respective items in the "Options" menu of the composer window. You can also select if GnuPG MIME mode (RFC 3156), OpenPGP mode (RFC 2440) or S/MIME mode (RFC 2633) shall be used. However, note that some options may not be available if balsa has been configured without support for the respective protocol. To simplify the access to the sign and encrypt options, you can add buttons to the toolbar.

Which mode you should use basically depends on the mail client the recipient uses (balsa, of course, knows about all standards). To check which standard the recipient's mail client supports, you could ask her/him to send you a signed message. If balsa tells you in the signature info box that it is a "PGP signature" the sender used GnuPG MIME mode. If it says that it is a "S/MIME signature" the mode is (surprise) S/MIME. Finally, if it reports that the part is "inline OpenPGP signed" the mode is pure RFC 2440.

You should also keep in mind that both GnuPG MIME mode (RFC 3156) and S/MIME mode (RFC 2633) sign and/or encrypt complete messages including all attachments (all parts are first put into a special MIME structure which is then handled, see the next section for an example). So usually these modes are the preferred standards for the secure exchange of messages.

In OpenPGP mode only the first part of the message will be signed and/or encrypted. All other parts are attached "as is". So, if you want to have signed/encrypted attachments here, you must first process them manually using gpg or Seahorse. Balsa will pop up a warning when you try to send a message with attachments in this mode.

4.5 Receiving Messages

When balsa receives a MIME signed or encrypted message, the status is indicated using "traffic light" icons in the "A" column of the message index: Note that if a messages contains more than one signature (e.g. because a signed messages contains a signed, forwarded message), this icon will will reflect the worst trust/validity level found in the whole message. You can see the individual status of each signature in the part's tree view and of course in the detailed status description for each signature part. Here you can also check whether a signature is "inline" or not. The following image shows the structure of a rather complicated message:

message structure example

The top-level part of the message (1) is a PGP/MIME container, of which the signed matter is again a multipart/mixed container (1.1), and the signature of it is good and trusted (1.2). The message itself (i.e. what Balsa will show you) consists of two "normal" parts (1.1.1 and 1.1.5) and three forwarded messages (1.1.2, 1.1.3 and 1.1.4). The first message is a PGP/MIME signed and encrypted multipart created by Enigmail, using the combined signing and encryption method ( The second message contains a S/MIME signed part ( of which the related certificate is not trusted ( Note that this message also contains a part ( which is not protected by this signature. The third message contains only one OpenPGP signed message part (, whose signature is valid, but the key has expired. Therefore, this part gets a "bad" sign, and the overall signature status is also bad.

If the top-level part of a message or an included (forwarded) message is signed, the short status is also printed in the message's headers box.

Balsa can be configured to decrypt messages and check signatures automatically when a message is opened (see section Mailboxes below). It is however possible to decrypt or validate a message manually using the check crypt button [recheck] in the messages top-level headers box. Note that if a message (like the example above) contains a forwarded encrypted message, re-checking its signature will always fail. This is due to the fact that the signature (1.2) has been calculated over the encrypted message part (, but Balsa uses the decrypted contents upon re-checking. However, this is a very exotic case.

If a message's GPG signature could not be verified due to a missing key, you can run gpg in background to retreive the key from a keyserver. Balsa will report a successful retreival or indicate any error. If the retreival has been successful, use the recheck button as described above.

Pure OpenPGP signed and/or encrypted messages contain no information in the envelope, so it is not possible to display an indicator in the index. When an OpenPGP signed message is opened, the signature status displayed next to the respective message text part.

Balsa can not handle OpenPGP (RFC 2440) encrypted attachments with other content types than "text". To decrypt such attachments, save them to disk and use gpg or seahorse directly.

Some ancient mail clients still send messages with an "application/pgp" content header. This content type has been withdrawn at least since October 1996 when RFC 2015 (which in turn was updated by RFC 3156) was published. It is not and will never be supported by balsa. You should ask the sender of that mail to upgrade to an up-to-date client (balsa, of course ;-)).

5 Customisation

5.1 Identities

If you usually want to sign and/or encrypt all outgoing messages, you can adjust your identity to automatically preset the options in the send message dialog as well as selecting the preferred encryption method. Of course, you can still adjust this for every message using the Options menu or (if configured) the toolbar buttons.

5.2 Mailboxes

In the properties dialog for each mailbox folder, you can select a default crypto checking strategy. Possible options are

5.3 Caching Passphrases

The old code in Balsa 2.0 supporting an internal passphrase cache has been removed. A much better way to cache passphrases is using gpg-agent which comes with the experimental gpg releases. However, all stable up-to-date gpg releases (e.g. 1.2.x and 1.4.x) support using the agent.

If you already have gpg 1.9.x and all supporting packages installed, e.g. because you want to use S/MIME which needs gpgsm included there, balsa should simply use the agent and call pinentry to get a passphrase when necessary. Please see sections Gpg Setup and Gpg-Agent and Pinentry Setup above for details.

If you want to use the agent and pinentry without GpgSM support, please follow the installation instructions in section Prerequisites for S/MIME Support above, with the following two exceptions:

A nice alternative is to install Seahorse which comes with it's own passphrase entry agent and cache. However, this agent can only be used to cache passphrases for gpg. If you ever want to use gpgsm, you must install and use gpg-agent.

6 FAQ's

Q: I installed gnupg, gpgme and balsa, how do I get a GnuPG key?

Please have a look at section 3 of The GnuPG MiniHOWTO which explains working with keys in depth. You should also read the passphrase FAQ to learn how you can generate a really secure passphrase.

Q: I installed gpgsm, gpgme and balsa, how do I get a S/MIME key?

Please see section GpgSM Setup above.

Q: What are keyservers? How can I send/receive keys?

To simplify the exchange of public keys, you can send and receive them from keyservers. Check out for further details. To use keyservers with gnupg, you should configure gpg as described in section Gpg Setup.

Now you can send a key to the keyser using the command

gpg --send-key
or search for public keys using
gpg --search-keys <mail address to search for>
If you are located behind a firewall which blocks port 11371, this method will fail. In this case, you might still use a web interface a import or export keys to/from gpg using the --import or --export --armor options, respectively.

Q: I created a key but balsa never accepts my passphrase?

Probabely you used gpg in command line mode from a terminal to create your key, and the passphrase you gave contains national characters (like äöüàôú). In an xterm, national characters are usually encoded using a character set like ISO8859-1, whereas all Gnome-2 applications encode them as UTF-8. The latter method has the advantage that UTF-8 basically contains all national characters and not only a subset like ISO8859 (it is e.g. not possible to mix west and east european characters using them). The drawback is that gpg when called from balsa simply "sees" a different passphrase and rejects it (the same will happen with all other Gnome-2 applications using gpg).

If you usually use Gnome-2 tools, it might be a good idea to convert the passphrase to UTF-8, using the following method:

The drawback of this method is that now the command line gpg in an xterm will not accept your passphrase any more. It is, however, possible to also change your complete environment and xterm to UTF-8. Please see the Unicode HOWTO for details. If you configured gpg to use gpg-agent and pinentry, you don't have to worry about that as even when you run gpg manually from the command line, the pinentry window (which uses Gtk+-2 and therefore UTF-8 characters) should come up to ask for the passphrase.

Q: Is there a GNOME interface for GnuPG?

Try Seahorse or gpa.

7 Links

Valid HTML 4.01!
Author: Albrecht Dreß
Contact info: Johanna-Kirchner-Straße 13, 53123 Bonn, Germany
albrecht [dot] dress [at] netcologne [dot] de
I prefer GnuPG encrypted messages. Click here to get my GnuPG public key.
Last change: July 5th, 2006