Master Key Based Encryption

Introduction

With Master Key based encryption, there is only one key (or key pair) and all files are encrypted using that key pair. This is highly recommended for new instances to avoid restrictions in functionality of user key encryption.

Enabling Master Key Based Encryption

There are two steps to be made to enable Master Key based encryption.

We strongly encourage you to put your server in single user mode before setting up encryption.

To do so, run the following command:

sudo -u www-data php occ maintenance:singleuser --on

Enable the Encryption App

To enable the encryption app, run the following command:

sudo -u www-data php occ app:enable encryption

If the encryption app successfully enables, then you should see the following confirmation:

encryption enabled
This should never happen, but the encryption app may not be packaged with your ownCloud installation. If so, you will see the following output when you attempt to enable it:
encryption not found

If that happens, then you need to install it manually. You can do this by cloning the encryption app, using the following command:

git clone https://github.com/owncloud/encryption.git apps/encryption

Enable and Configure Master Key Based Encryption

To enable and configure Master Key based encryption via the command-line, involves several commands.

  1. Enable encryption.

  2. Enable the master key.

    Master Key Mode has to be setup in a newly created instance.
  3. Encrypt all data.

The following example shows how to carry out these steps.

sudo -u www-data php occ encryption:enable
sudo -u www-data php occ encryption:select-encryption-type masterkey
sudo -u www-data php occ encryption:encrypt-all
This command is not typically required, as the master key is often enabled at install time. As a result, when enabling it, there should be no data to encrypt. However, if you have enabled master key encryption post-installation, existing files will not be automatically encrypted; only newly created files. To encrypt existing files use the encrypt-all command as described above. Before doing so, set the instance into single user mode for that task.

View Current Encryption Status

Retrieves the current encryption status and the name of the loaded encryption module.

sudo -u www-data php occ encryption:status

This is equivalent to checking "Enable server-side encryption" on your Admin page:

sudo -u www-data php occ encryption:enable
Encryption enabled

Default module: OC_DEFAULT_MODULE

Recreate an Existing Master Key

If the master key needs replacing, for example, because it has been compromised, an occ command is available. The command is encryption:recreate-master-key. It replaces existing master key with new one and encrypts the files with the new key.

Decrypt Master-Key Based Encryption

You must first put your ownCloud server into single-user mode to prevent any user activity until encryption is completed.

sudo -u www-data php occ maintenance:singleuser --on
Single user mode is currently enabled

Decrypt all user data files, or optionally a single user:

sudo -u www-data php occ encryption:decrypt-all [username]

Disable Encryption

To disable encryption, put your ownCloud server into single-user mode, and then disable your encryption module with these commands:

sudo -u www-data php occ maintenance:singleuser --on
sudo -u www-data php occ encryption:disable

Take it out of single-user mode when you are finished, by using the following command:

sudo -u www-data php occ maintenance:singleuser --off

You may only disable encryption by using the occ Encryption Commands. Make sure you have backups of all encryption keys, including those for all your users.

Sharing Encrypted Files

After encryption is enabled, your users must also log out and log back in to (automatically) generate their personal encryption keys. They will see a yellow warning banner that says

Encryption App is enabled, but your keys are not initialized. Please log-out and log-in again.

Also, share owners may need to re-share files after encryption is enabled. Users who are trying to access the share will see a message advising them to ask the share owner to re-share the file with them.

For individual shares, un-share and re-share the file. For group shares, share with any individuals who can’t access the share. This updates the encryption, and then the share owner can remove the individual shares.