Migrating User Key Encryption to Master Key Encryption

Introduction

User Key Encryption has been deprecated with ownCloud Server 10.7, see the corresponding release notes for details. Though you can continue to use this solution, it is no longer selectable and existing User Key Encryption must be migrated to Master Key Encryption.

The reason disabling User key-based encryption is because of 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. Master-key-based encryption is therefore now the recommended and only available setup for all new installations.

Pre-Conditions

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:

  1. Disable User Key-based encryption

  2. Remove the encryption records from the ownCloud database

  3. Remove the files_encryption directory

  4. Encrypt the filesystem using Master Key-based encryption

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:

  1. occ encryption:decrypt-all,

  2. occ encryption:disable and

  3. occ app:disable.

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';
encryption|recoveryKeyId|recoveryKey_73facda6
encryption|publicShareKeyId|pubShare_73facda6
encryption|masterKeyId|master_73facda6
encryption|installed_version|1.3.1
encryption|types|filesystem
encryption|enabled|yes
encryption|useMasterKey|1

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.