Migrating User Key Encryption to Master Key Encryption


Why should you move away from User Key-based encryption?

While it is a bit more secure than a central encryption approach, User key-based encryption has some disadvantages. It blocks some additional functions such as the integration of an online editor like LibreOffice or OnlyOffice into ownCloud and can cause problems when sharing files with groups. See Limitations of User-Key Based Encryption for more details. Therefore Master-key-based encryption is now the recommended setup for all new installations.

User key-based encryption is planned to be removed from ownCloud in the near future. As an existing customer, you will be able to continue to use this solution as long as ownCloud 10.x is supported.


The decryption workflow described here will only work with the following pre-conditions:

  • The admin recovery key password is activated and available to the ownCloud administrator

  • Users have opted-in to enable the admin recovery key password

  • The recovery key password has been supplied by the admin on the users page

Please see How To Enable Users File Recovery Keys for more details.

A notification to the users (e.g. through the announcement app) prior to the migration process is recommended, as the instance will not be available during this task.

Steps to Migrate from User Key-based to Master Key-based Encryption

There are several steps you need to follow to ensure a smooth and complete transition:

Disable User Key-based Encryption

The first part of the migration process is to decrypt all files and to disable encryption in ownCloud, which requires three commands to be executed. These commands are:

You can see an example of calling the commands listed below, configured to require no user interaction.

sudo -u www-data ./occ encryption:decrypt-all --continue=yes && \
  sudo -u www-data ./occ encryption:disable --no-interaction && \
  sudo -u www-data ./occ app:disable --no-interaction encryption
The decryption of the files by the ownCloud administrator requires the current passwords of all users! This only works when users have enabled password recovery and if an admin recovery password is available.

Remove the Encryption Records from the ownCloud Database

Once your ownCloud files are unencrypted, and encryption has been disabled, you need to remove the encryption records from the database. There is, currently, no occ command to handle this, so it has to be done manually. Specifically, you need to remove all records from the oc_appconfig table where the appid column is set to encryption.

In the examples below, you can see how to do this using MySQL. If you are not using MySQL, please use the commands specific to your database vendor.

SELECT * FROM `oc_appconfig` WHERE `appid` LIKE 'encryption'

Remove the files_encryption Directory

With the database updated, next, the files_encryption directory needs to be removed. Below is an example of how to do so, to save you time.

cd <your owncloud root directory>
find ./data* -name files_encryption -exec rm -rvf {} \;

Encrypt the Filesystem Using Master Key-based Encryption

Now, your ownCloud files can be encrypted using Master Key-based encryption. This requires the following steps:

  1. The encryption app needs to be enabled

  2. Encryption needs to be enabled

  3. The encryption type needs to be set to Master Key

  4. Re-encryption of the ownCloud filesystem.

The following example shows how to do this on the command line.

sudo -u www-data ./occ app:enable encryption && \
  sudo -u www-data ./occ encryption:enable && \
  sudo -u www-data ./occ encryption:select-encryption-type masterkey -y && \
  sudo -u www-data ./occ encryption:encrypt-all --yes

Verify the Encrypted Files

With the files encrypted using Master Key-based encryption, you should now verify that everything worked properly. To do so, run a SELECT query in your database which returns all files from the oc_appconfig table where the appid column is set to encryption. You should see a number of records, as in the output of the example below.

select * from `oc_appconfig` where appid='encryption';

Disable Single User Mode

With encryption migrated from User Key-based encryption to Master Key-based, disable single user mode, if you enabled it before beginning the migration.

sudo -u www-data ./occ maintenance:singleuser --off

Post Note

It is possible, that after migration, some or all users see a re-synchronisation of their data from the server to the desktop client - especially for shared folders.