Installing Encryption For
VTiger CRM

The following tutorial explains how you can upgrade VTigerCRM with the Web Encryption Extension. I'm using the latest version 5.3.0 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 VTigerCRM 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 VTigerCRM, you 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. VTigerCRM 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 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.

VTigerCRM creates text input in the FCKeditor, a graphical HTML editor that opens up with the compose window. That's why the default configuration uses the HTML editor setting for encryption and signing. It is much more difficult to read the content of incoming mail as the email bodies are presented in an iframe html element containing div elements without name or id. As a consequence, I've decided to modify the code to give the relevant div element an id=messagearea identification, so that the software can use this id to read the email message body from the code.

A similar approach will use a textarea to frame the output of a signature, so that the verification code can read it from this textarea again. Another complication that comes with displaying email message bodies is the insertion of additional <br> tags by the software, which can be bypassed using the directive $REMOVEBR = "yes" in the configuration file. If you agree with these decisions, you can simply use the configuration file "gpgconfig.php" as provided with the archive.

Placing Buttons in the Code

As a last step you need to place buttons in the code that activate the five WEE scripts. Changes to the code will only apply to some of the template files to make the buttons available but one core file needs to be updated, too.

There are four files that need to be modified:

  • ./Smarty/templates/ComposeEmail.tpl
  • ./Smarty/templates/Webmails.tpl
  • ./modules/Webmails/body.php
  • ./modules/Emails/mail.php
You may simply use the files in the archive to replace these template files, if you wish to add new buttons to the code using version 5.3.0, or you can inspect the template files to find the code for the buttons to update any other version you may use. I have placed the "encrypt" and "sign" buttons in ComposeEmail.tpl and the "decrypt" and "verify" button in body.php. To make the key management tool accessible I've decided to place a "key" button at the top in Webmails.tpl.

We've modified lines 112 to 117 of the file body.php:

if(!$_REQUEST['fullview']) echo '<div id=messagearea style="overflow:auto;height:386px;width:737px;padding:5;">'; else echo '<div id=messagearea style="padding:5;">'; $content['body'] = preg_replace('/-----BEGIN PGP MESSAGE/', "\n-----BEGIN PGP MESSAGE", $content['body']);

Essentially, these lines provide for a textarea id and make sure that signatures always start on a new line to make them accessible for verification. Another necessary modification is line 29 in the file mail.php, which serves a similar purpose.

User Authentication and Key Management

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

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