Installing Encryption For
Roundcube Webmail

The following tutorial explains how you can upgrade roundcube webmail with the Web Encryption Extension. While I've started with version 0.7.1 years ago there's an update for the the latest version 1.0.3. I will use this newer version for this explanation.

Download

To make things as easy as possible for you we 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 roundcube 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 roundcube, 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. Roundcube will assign an individual number to every user, stored in the database. This number will be used to create a separate directory here for every user to store his or her 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.

Inside the archive, you'll find two files ready to be used as the main configuration file. The one already installed is used for roundcube's text editor, the other for the HTML editor. I have decided to make the text editor configuration the default because in text mode, signing texts works just fine, while using the HTML editor for signature input leads to all kinds of problems with the signature verification as roundcube adds additional HTML and quotings that destroy the signature.

I don't recommend the HTML mode, but if you decide to make encryption and decryption available for the HTML editor, you can use the supplied config file as a template but be aware that signature is available only for text editor input. Simply overwrite the file "gpgconfig.php" with the content of "gpgconfig-html.php" and set the key directory to the path you are actually using on your server. Using HTML mode will cause another problem as roundcube does not insert a newline before the GPG message block. In order to provide the block on a new line you have to insert the following lines of code in line 1207 in the file "./program/steps/mail/func.inc".

$body = preg_replace('/-----BEGIN PGP SIGNED/', "\n-----BEGIN PGP SIGNED", $body);
$body = preg_replace('/-----BEGIN PGP MESSAGE/', "\n-----BEGIN PGP MESSAGE", $body);

You'll find a working file "func.inc" in the directory for version 1.0

Placing Buttons in the Code

As a last step you need to place buttons in the code that activate the five WEE scripts. If you are using the text mode and not the HTML editor changes to the code will only apply to files that define the skin, not to core files of the roundcube code.

In version 1.0.x there are modified skin files for both LARRY and CLASSIC skins. Change into the directory "wee/1.0.x/larry" or "wee/1.0.x/classic" and then copy the new skin files to the active source code files which are visible inside the directory as a link. Don't forget to use the gpgconfig.php for text or html mode which is different for both skins. You have to copy one of these into the main roundcube directory as "gpgconfig.php".

For older versions there are three skin files (LARRY) that need to be modified:
version 0.9.4 to 0.8.4:

  • ./skins/larry/templates/compose.html
  • ./skins/larry/templates/message.html
  • ./skins/larry/includes/header.html

version 0.7.1

  • ./skins/default/templates/compose.html
  • ./skins/default/templates/message.html
  • ./skins/default/includes/taskbar.html
I have provided the directories (0.8.4 to 0.9.4) for the different skin files You may simply use the files in the archive to replace the skin files in your installation. I have placed the "encrypt" and "sign" buttons in compose.html and the "decrypt" and "verify" button in message.html. To make the key management tool accessible I've decided to place a "key" button at the top in header.html.

User Authentication and Key Management

It's absolutely essential that only users who have successfully logged into roundcube 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 roundcube 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 roundcube identification number.

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

Troubleshooting

If you're running a Ubuntu server, the webserver process is owned by user ID 33 (www-data). In order to make the key directories accessible to the webserver process all key directories must be owned by UID 33 and you have to place a line

$APACHE = 33;

into the central configuration file "gpgconfig.php". (updated on 12 November 2014)