Installing Encryption for
Atmail Open Webmail

The following tutorial explains how you can upgrade Atmail Open webmail with the Web Encryption Extension. I'm using the latest version 1.04 for this explanation.

Download

To make things as easy as possible for you I have bundled a tar archive that contains everything you'll need in one single download. After downloading the archive extract it in a directory and upload all files into the top level directory where Atmail Open is installed on your server. Make sure that all new files are owned by the user that runs the webserver process and that restrictive file permissions (700) are preserved.

Decisions And Setup

Before you decide about how to use the Web Encryption Extension inside Atmail Open, youi'll need to provide a directory outside the webserver tree where WEE can store public keys for users. This directory must be writeable by the webserver process and access permissions need to be set to 700 for this directory. Make sure that this directory (i.e. /home/gpg) is set in the main configuration file "gpgconfig.php" in the following way

$GPGDIR = "/home/gpg";

It's essential that you check carefully that your place for keys is secured. Atmail Open will use a user's email address to create a separate directory here for every user to store his or her own keys.

If you encounter difficulties trying to use this directory outside the web server's root directory, chances are that SELinux is responsible for this misbehaviour and you may have to teach SELinux to play nicely with the Web Encryption Extension.

You may consider that the key directory becomes part of a regular backup, but be careful not to expose the content of this directory to any backup unprotected.

Atmail Open is not the most friendly environment for WEE because at the moment it will only work with the text editor and not with the HTML editor. The reason for this is simply that the Atmail Open code provides the text inputs in iframes, and that the iframes change their numbers rapidly and unpredictably while the HTML editor is in use. So the text editor has to be set as the default in the user settings section. The main configuration file "gpgconfig.php" is already prepared for the default text editor and should be usable straight away.

Placing Buttons in the Code

As a last step you need to place buttons in the code that activate the five WEE scripts. Fortunately changes to the code will only apply to one single file of the Atmail Open code.

Simply replace the file "./html/english/simple/showmail_interface.html" with the content of the file from the archive. The buttons will appear on top of the mail compose window and at the bottom of the inbox index. You'll find the code in lines 181 to 188 of this file.

User Authentication and Key Management

It's absolutely essential that only users who have successfully logged into Atmail Open are able to use the additional encryption scripts and that every user has access only to his own key files. Nobody should be able to call the new scripts directly without authentication. All scripts make use of the file "wee-auth.php", which controls access to the scripts. Proper user authentication is performed here, based on calls to Atmail Open code, that makes sure that permission to use the scripts is granted only to users with a successful login. This file also assigns the right key directory by overwriting the variable $GPGDIR with the proper path to a user's key directory based on his email address.

Changing the entire look and feel of the script's popup windows is also possible by adapting the stylesheet file "gpgstyle.css".