Installing Encryption For
OwnCloud

The following tutorial explains how you can upgrade your OwnCloud installation with the Web Encryption Extension. I will use the latest version (6.0.4) 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 ownCloud is installed on your server. We assume that the name of this directory is "owncloud". Make sure that all new files are owned by the user that runs the webserver process (usually apache) and that restrictive file permissions (700) are preserved.

Decisions And Setup

Before you use the Web Encryption Extension inside ownCloud, you'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 enabled in the main configuration file "gpgconfig.php" in the following way

$GPGDIR = "/home/gpg";

It's essential that you check carefully that the place you choose for keys is secured. Onwcloud will provide an individual user name, stored in its database. This name will be used to create a separate directory here for every user to store his or her individual 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.

Once your key space is ready you have to decide whether plain text files should be replaced by encrypted files or if you prefer to create separate encrypted files with an ".asc" extension. The default behaviour is not to overwrite (replace) plain text files, because if you select a false public key for encryption the original file will still be there. If you choose to replace the plain text file, you may not be able to recover the plain text, as you don't have the secret key. On the other hand, replacing files works well, if you always select the correct public key, there will be no plain text files lying around after encryption. In case you decide to use separate files, you need to take care of deleting your plain text files yourself, don't forget to delete plain text after encryption. I recommend to replace the plain text.

You can switch on replacing plain text files using the following option:

$REPLACEFILE = "yes";

Note, that if you don't use this option, decrypting a plain text file will just fail, but decrypting a file with the ".asc" extension will overwrite the original plain text file, because the result of a successful decryption will be stored in a file with the ".asc" extension truncated. If the original plain text file does not exist it will be created, but if it exists, its content will be overwritten.

It's a fundamental decision how you'd like to have your files stored and as a global option this decision is valid for all users of your ownCloud installation. In additon to this you have to specify the absolute path to your ownCloud data directory in the configuration file.

Under normal circumstances ownCloud makes copies of files due to the activation of certain apps, the "Versions" and "Deleted files" application, in particular. Both apps should be disabled, if you are interested in not having any copies lying around that may contain unencrypted material. But again, disabling these apps will have the effect, that there is only one file that holds your information. As a result you have to take care of (encryped) backups yourself.

The Path To Your Data

There is a line in the configuration file "gpgconfig.php" that you'll need to modify, in order to make encryption and decryption find your files:

$DATADIR = "/where/ever/your/files/live/data";

Without a proper path to your data directory encryption will always encrypt 0 Bytes.

Placing Buttons in the Code

As a last step you need to place buttons in the code that activate the WEE scripts for encryption and decryption.

There are two files that need to be modified:
version 6.0.4:

  • apps/files/js/fileactions.js
  • core/templates/layout.user.php

version 5.0.4 - 5.0.12:

  • apps/files/js/fileactions.js
  • apps/files/templates/index.php

I have provided directories (5.0.4 to 5.0.12) for the different files that have to be modified. From version 6.0.2 I've decided to put the key management button in a different core file. You may simply use the files in the archive to replace the core files in your installation. Change into the subdirectory (6.0.4) and copy newlayout.user.php into layout.user.php and newfileactions.js into fileactions.js. This will replace the files that come with the original source code. From version 6.0.4 there is a different file "wee-auth.php", which uses a modified version of the core file "./lib/base.php". You'll find a template in this directory as well, that you can copy into the parent directory "./wee". If you use a newer version of ownCloud, please check if the source code files differ from the files newlayout.user.php and newfileactions.js. If they differ you have to apply the modifications by hand.

I have placed the "encrypt" and "decrypt" buttons in the file "fileactions.js". To make the key management tool accessible I've decided to place a "key" in the left side menu in the "layout.user.php" template file.

User Authentication and Key Management

It's absolutely essential that only users who have successfully logged into ownCloud 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 ownCloud code, that makes sure that permission to use the scripts is granted only to users following 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 ownCloud's user name.

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".