# GnuPG support in `SqWebMail`

Table of contents:

- Introduction
- Requirements
- Implementation
- Interoperability
- Using passphrase-protected private keys
- Bugs
- Important note for Linux and other systems that use the `/dev/random` device.

## Introduction

The following functionality is available:

- Create new keypairs
- List public/private keys
- Delete keys
- Sign keys
- Export keys (attach them to the current message)
- Import keys from messages
- Sign outgoing messages
- Encrypt outgoing messages
- Display and verify signed messages
- Decrypt encrypted messages
- Reply and forward encrypted messages. Correctly handle multipart/alternative and multipart/related.

`SqWebMail` creates and manages its own keyrings. `$HOME/.gnupg` is not used. This allows GnuPG functions to work for virtual accounts that have no home directory.

## Requirements

This implementation requires GnuPG, which is used for all of the heavy lifting. No encryption code exists in `SqWebMail` itself. The configuration script searches the current PATH for the `gpg` binary. The final `SqWebMail` binary gets the hardcoded absolute path to the `gpg` binary. If `gpg` is not found in the current PATH, `/usr/bin/gpg` will be used. Therefore, if GnuPG is locally installed in a non-default location, make sure that `gpg` can be found in the current PATH.

## Implementation

`SqWebMail` runs `gpg` automatically to handle all the actual tasks involved in encrypting and decrypting messages. `make install` also installs two more binaries: `reformime` and `mimegpg`. Those binaries do some other things, and nothing really needs to be done about them, or to them, except to know that they're there.

### The `webgpg` script

`make install` automatically installs a shell script, `webgpg`. Encryption/decryption capabilities for all mail accounts are disabled by default. The `webgpg` script takes one argument - the complete pathname to a Maildir. `webgpg` creates a new subdirectory, `Maildir/gpg`, and initializes it. Once that subdirectory is created, encryption/decryption in `SqWebMail` becomes available for that account. Not every mail account has to have encryption/decryption enabled. This functionality can be selectively enabled and disabled for individual accounts.

NOTE: `webgpg` script MUST be executed by the same userid and groupid that owns the `Maildir` directory.

NOTE: The current implementation consists of the bare minimum required to get the overall functionality. As a result, a number of shortcuts are taken with respect to avoiding some hoops that GnuPG occasionally requires to be jumped through. For example, by default GnuPG requires that a public key must be signed before it can be used for encryption. `SqWebMail` will automatically provide the "always-trust" option to bypass the check. Basically, if you have the public key in your keyring, you can use it.

### Updating existing `Maildir/gpg` with `webgpg`

Running `webgpg` installs `gpg.conf` and `gpg-agent.conf` in the new `gpg` subdirectory, or replaces the existing configuration files with the default versions.

Older `gpg` subdirectories had an `options` file instead of `gpg.conf`. `webgpg` removes any existing `options` file before installing `gpg.conf`

### Issues with adding or activating encryption for existing accounts

Obviously, encryption/decryption takes additional server CPU cycles. There is no hard and fast rule for how much additional load is needed. Fortunately, this is not an "all or none" deal. Encryption support can be activated in a controlled manner and phased in gradually, in steps, allowing the impact on the web/mail server to be closely monitored, and controlled.

### Issues with adding or activating encryption for new accounts

The `webgpg` script needs to be used to initialize encryption support for newly-created accounts. Many systems use the `/etc/skel` directory as a template for setting up the initial contents of new accounts. In that case, use run "`webgpg /etc/skel/Maildir`", and all new accounts will have encryption automatically activated.

## Interoperability

The directory `Maildir/gpg` does pretty much what `$HOME/.gnupg` does for the command-line `gpg` tool. `SqWebMail` does not use `$HOME/.gnupg`, it keeps its keyrings and other GnuPG-related stuff in the `Maildir/gpg` directory. That's because `SqWebMail` can be configured to use both physical system accounts and virtual mail accounts, and after authenticating, there is no difference whatsoever between the two. Therefore, `SqWebMail` has no concept of the $HOME directory. Its entire universe consists of the `Maildir` directory, and its contents. `SqWebMail` is completely unaware of the existence of `$HOME/.gnupg`, and will never be aware of it. Any keypairs in `$HOME/.gnupg` will have to be imported into `Maildir/gpg`.

### Importing keys

Since `$HOME/.gnupg` is not used, any existing keys will have to be imported. If shell access is available, the `pubring` and `secring` files can simply be copied to `Maildir/gpg`. The following procedure can be used to import keys in all other circumstances. The following example imports keys from mail account M to `SqWebMail` mail account W.

- Create a temporary keypair in W.
- Create a new message, addressed to M, attach the new public key, and send it.
- In M, take the new public key and import it.
- Export M's secret key. With GnuPG, use the following command:

      gpg --export-secret-key --armor [fingerprint]

  The output from this command looks something like this:

      -----BEGIN PGP PRIVATE KEY BLOCK-----
      Version: GnuPG v1.0.4 (GNU/Linux)
      Comment: For info see http://www.gnupg.org

      +M3OSONvootZCzKXP6VT29Vf+lZLQkjSyuY28PpfflaFKi8YpeCEKo4dDhynxCbV
      NAYk2I6wXguwl4MOT0ebkEWM1WS9lTsto7cCzz0ovSg3xe82PozA/4s6E5UUgl1B

      ...
      RQj/UASJxoPEEDHAhfZ0FYPsDFbo/P///4nDiTQk6Pz///+J2I1l+FteXcOJ9lWJ
      RSBQ/3Uc/3UY/3UU/3UQ/3UM/3UI6GsAAACDxBz/dSxqBf91KGoAicP/dST8McCJ
      -----END PGP PRIVATE KEY BLOCK-----

- Wrap this inside a MIME-formatted mail message. The end result should look something like this:

      Mime-Version: 1.0
      Content-Type: multipart/mixed; boundary="xxx"

      --xxx
      Content-Type: text/plain

      Here's the key

      --xxx
      Content-Type: application/pgp-keys

      -----BEGIN PGP PRIVATE KEY BLOCK-----
      Version: GnuPG v1.0.4 (GNU/Linux)
      Comment: For info see http://www.gnupg.org

      +M3OSONvootZCzKXP6VT29Vf+lZLQkjSyuY28PpfflaFKi8YpeCEKo4dDhynxCbV
      NAYk2I6wXguwl4MOT0ebkEWM1WS9lTsto7cCzz0ovSg3xe82PozA/4s6E5UUgl1B

      ...
      RQj/UASJxoPEEDHAhfZ0FYPsDFbo/P///4nDiTQk6Pz///+J2I1l+FteXcOJ9lWJ
      RSBQ/3Uc/3UY/3UU/3UQ/3UM/3UI6GsAAACDxBz/dSxqBf91KGoAicP/dST8McCJ
      -----END PGP PRIVATE KEY BLOCK-----

      --xxx

- Encrypt the whole message using W's public key. The end result should look something like this:

      Mime-version: 1.0
      Content-Type: multipart/encrypted;
          boundary="yyy";
          protocol="application/pgp-encrypted"

      --yyy
      Content-Type: application/pgp-encrypted
      Content-Transfer-Encoding: 7bit

      Version: 1

      --yyy
      Content-Type: application/octet-stream
      Content-Transfer-Encoding: 7bit

      -----BEGIN PGP MESSAGE-----
      Version: GnuPG v1.0.4 (GNU/Linux)
      Comment: For info see http://www.gnupg.org

      hQIOA8nMaZ+WFjCiEAf+IzymijY0K0ELubJnDuTo0OZg6n8EApLTdwXVZ7sjoWvU
      YbEjfvwBXp+wc7X4lvw3S/AGYe4/mmshgTnRjuDPKsN3zHViYGdGF0UaB40sjUp3

      ...
      U9Qi2kvxRvV0b8nBN1qeFUSSRF8Ncwug1sr/rFVNNWA0yavb5WDFrqRE6WFJU3z3
      p0vPPRbdWCOTP7WGOygpHdRMLQSCxG4m+L9uG3roG5Uu7A==
      =GutI
      -----END PGP MESSAGE-----

      --yyy--

- Mail this message to W. Repeat the procedure with M's public key (`gpg --export-key --armor). If you're handy with composing MIME messages, both keys can be sent in a single encrypted message.
  `
- In `SqWebMail`, you should be able to decrypt the message containing the keys, and import them.

## Using passphrase-protected private keys

SqWebMail can handle passphrase-protected keys only when SSL is used. This is an artificial restriction that prevents passphrases from going over the network, in the clear. When SSL is used, SqWebMail will automatically prompt for a passphrase. Leave the passphrase field empty if the secret key is not protected by a passphrase.

## Bugs

1. Although `SqWebMail` contains mappings for many charsets, GnuPG versions prior to 1.0.6 know only about `iso-8859-1` and `iso-8859-2`. All messages displayed by `SqWebMail` from GnuPG 1.0.5 or earlier will come out in `iso-8859-1`.
2. Currently, there are no command line options in GnuPG for removing key signatures (is that even possible?). You can sign keys, but can't "unsign" them.
3. GnuPG may blather "Warning: secret key NOT protected" when using keys not protected by a passphrase. This whinge is harmless, and can be ignored.
4. The error message from GnuPG for a missing passphrase is not very helpful: "Unable to get tty input", or something similar. This is because SqWebMail runs GnuPG with the --no-tty flag, and provides a passphrase separately, when it's entered. When SqWebMail does not provide a passphrase, GnuPG complains that tty input is disabled.

## Important note for Linux and other systems that use the `/dev/random` device.

If GnuPG is compiled on a system that has a `/dev/random` device, GnuPG will use the `/dev/random` device as a source for random entropy. The `/dev/random` device driver in Linux, and in many other implementations, creates the entropy pool from system device driver background activity. Unfortunately, it's is not a bottomless pit of random entropy. When the random device driver entropy pool is empty, `/dev/random` halts until device drivers create more noise.

That means that when GnuPG is used on Linux, GnuPG may pause for an excessive period of time, and issue its famous "please do something" prompt. Since GnuPG is invoked in automatic mode, there is no other alternative, except to wait until more device driver noise becomes available.

This is more likely to happen when GnuPG is used to create new keypairs, especially ones that are 1024 bits, or longer. Before deploying, extensive testing is recommended to make sure that even an idle system generates sufficient background noise so that the additional wait is not excessive. There are several possible solutions that can also be used:

1. GnuPG can be optionally configured to use a pseudo-random generator that does not use `/dev/random`, but instead uses several alternative sources of random junk. Consult GnuPG's documentation for more information.
2. Many systems also have a `/dev/urandom` device, which automatically generates pseudo-random noise if `/dev/random` runs out of entropy. This makes it possible to simply remove the `/dev/random` device and create a link from `/dev/random` to `/dev/urandom`.

Although - technically - both approaches can theoretically result in slightly less secure keypairs, practically the difference is probably academic in nature.