"Fossies" - the Fresh Open Source Software Archive

Member "courier-1.2.2/libs/gpglib/README.html" (20 Jan 2022, 14029 Bytes) of package /linux/misc/courier-1.2.2.tar.bz2:

Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the courier-1.2.2.tar.bz2 project site itself.

GnuPG support in SqWebMail

Table of contents:

Introduction

The following functionality is available:

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.

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.