User-Key Based Encryption


  • Users added to groups cannot decrypt files on existing shares.

  • OnlyOffice will not work.

  • Impersonate will not work.

  • OAuth2 does will not work.

  • Elasticsearch will not work.

  • Users getting access to an external storage which already contains existing encrypted files cannot get access to said files for reasons such as the group case above.

  • When having data shared with a group and group membership changes after the share is established, subsequently added users will not be able to open the shared data unless the owner will share it again.

Enable User-Key Based Encryption

To enable User-Key based encryption requires two steps:

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 apps/encryption

Enable and Configure User-Key Based Encryption

To enable and configure User-Key based encryption, you need to:

  1. Enable the default encryption module app

  2. Enable encryption

  3. Enable the user-key, using the following command:

  4. Encrypt all data

  5. Turn off the single user mode

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 user-keys
sudo -u www-data php occ encryption:encrypt-all --yes
sudo -u www-data php occ maintenance:singleuser --off

How To Enable Users File Recovery Keys

Once a user has encrypted their files, if they lose their ownCloud password, then they lose access to their encrypted files, as their files will be unrecoverable. It is not possible, when user files are encrypted, to reset a user’s password using the standard reset process. If so, you’ll see a yellow banner warning:

Please provide an admin recovery password; otherwise, all user data will be lost.

To avoid all this, create a recovery key. To do so, go to Settings  Admin  encryption and set a recovery key password.


You then need to ask your users to opt-in to the Recovery Key. For the users to do this, they need to go to the ''Personal'' page and enable the recovery key. This signals that they accept that the admin might have a way to decrypt their data for recovery reasons. If they do not do this, then the recovery key won’t work for them.


For users who have enabled password recovery, give them a new password and recover access to their encrypted files, by supplying the Recovery Key on the Users page.


Because the recovery key is password protected, you may change its password now.


Sharing a recovery key with a user group is not supported. This is only supported with the master key.

Changing The Recovery Key Password

If you have misplaced your recovery key password and need to replace it, here’s what you need to do:

  1. Delete the recovery key from both data/owncloud_private_keys and data/public-keys

  2. Edit your database table oc_appconfig and remove the rows with the config keys recoveryKeyId and recoveryAdminEnabled for the appid files_encryption

  3. Login as admin and activate the recovery key again with a new password. This will generate a new key pair

  4. All users who used the original recovery key will need to disable it and enable it again. This deletes the old recovery share keys from their files and encrypts their files with the new recovery key

You can only change the recovery key password if you know the original. This is by design, as only admins who know the recovery key password should be able to change it. If not, admins could hijack the recovery key from each other
Replacing the recovery key will mean that all users will lose the possibility to recover their files until they have applied the new recovery key.

Decrypt User-Key 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

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.