occ includes a complete set of commands for managing encryption. When using a HSM (Hardware Security Module, can also be emulated by software), additional occ encryption-related commands can be used.
encryption config:app:set encryption encryptHomeStorage Encrypt the users home storage encryption:change-key-storage-root Change key storage root encryption:decrypt-all Disable server-side encryption and decrypt all files encryption:disable Disable encryption encryption:enable Enable encryption encryption:encrypt-all Encrypt all files for all users encryption:fix-encrypted-version Fix the encrypted version if the encrypted file(s) are not downloadable. encryption:list-modules List all available encryption modules encryption:migrate Initial migration to encryption 2.0 encryption:recreate-master-key Replace existing master key with new one. Encrypt the file system with newly created master key encryption:select-encryption-type Select the encryption type. The encryption types available are: masterkey and user-keys. There is also no way to disable it again. encryption:set-default-module Set the encryption default module encryption:show-key-storage-root Show current key storage root encryption:status Lists the current status of encryption
When using a HSM (Hardware Security Module, additional occ encryption-related commands can be used, see the HSM occ documentation below. The occ commands can also be used when HSM is initiated via software emulation like SoftHSM2.
encryption encryption:hsmdaemon Export or Import the Masterkey encryption:hsmdaemon:decrypt Decrypt a String config:app:set encryption Various encryption configuration commands for HSM
occ encryption:status shows whether you have active encryption and your default encryption module.
To enable encryption you must first enable the Encryption app and then run
sudo -u www-data php occ app:enable encryption sudo -u www-data php occ encryption:enable sudo -u www-data php occ encryption:status - enabled: true - defaultModule: OC_DEFAULT_MODULE
Server-side encryption for local storage like the users home and remote storages like Google Drive can operate independently of each other. By doing so, you can encrypt a remote storage without also having to encrypt the users home storage on your ownCloud server. Possible values are
config:app:set encryption encryptHomeStorage --value '1'
encryption:change-key-storage-root is for moving your encryption keys to a different folder.
It takes one argument,
newRoot, which defines your new root folder.
The folder must exist, and the path is relative to your root ownCloud directory.
sudo -u www-data php occ encryption:change-key-storage-root ../../etc/oc-keys
You can see the current location of your keys folder:
sudo -u www-data php occ encryption:show-key-storage-root Current key storage root: default storage location (data/)
encryption:list-modules displays your available encryption modules.
You will see a list of modules only if you have enabled the Encryption app.
encryption:set-default-module [module name] to set your desired module.
encryption:encrypt-all encrypts all data files for all users.
You must first put your ownCloud server into single-user mode to prevent any user activity until encryption is completed.
encryption:decrypt-all decrypts all user data files, or optionally a single user:
sudo -u www-data php occ encryption:decrypt freda
Users must have enabled recovery keys on their Personal pages. You must first put your ownCloud server into single-user mode, using the maintenance commands, to prevent any user activity until decryption is completed.
Accepts the methods:
Accepts the commands:
This lets the command know whether to ask for permission to continue or not.
encryption:fix-encrypted-version fixes the encrypted version of files if the encrypted file(s) are not downloadable for a given user. You only need this command if you get an "Invalid Signature" message in the browser or the clients.
oc_filecache database table contains the integer columns "version" and "encryptedVersion" which start with 1 and are incremented on every file modification. When using encryption, those values are used together with the ciphertext to generate a cryptographic signature for the file. The version value is required to verify the signature. In some very rare cases like timeouts or bugs etc, the value might not get updated accordingly or get lost. The brute-force approach is to use the
fix:encrypted:version command until the file can be decrypted. Starting with ownCloud 10.8, the behavior of the command got improved so that the encryptedVersion value is reset to its original value if no correct version was found. Before that fix, the last tried value was stored in the database thus modifying the state of the system and making further rescue attempts non-deterministic.
This method reads the value from the environment variable
This variable bounds the value of recovery password set in the encryption page.
If this variable is not set the recovery process will be halted.
This has to be used for decrypting all users.
While opting recovery method user should not forget to set
OC_RECOVERY_PASSWORD in the shell.
The continue option can be used to by pass the permissions asked like
no while decrypting the file system.
If the user is sure about what he/she is doing with the command and would like to proceed, then
-c yes when provided to the command would not ask permissions.
-c no is passed to the command, then permissions would be asked to the user. It becomes interactive.
encryption:disable to disable your encryption module.
You must first put your ownCloud server into single-user mode to prevent any user activity.
encryption:migrate migrates encryption keys after a major ownCloud version upgrade.
You may optionally specify individual users in a space-delimited list.
See encryption configuration to learn more.
encryption:recreate-master-key decrypts the ownCloud file system, replaces the existing master key with a new one, and encrypts the entire ownCloud file system with the new master key.
Given the size of your ownCloud filesystem, this may take some time to complete.
However, if your filesystem is quite small, then it will complete quite quickly.
-y switch can be supplied to automate acceptance of user input.
Export the private master key in base64
Import a base64 encoded private masterkey.
--export-masterkey prints the base64_encode of the file
The private key file in the directory may named like
Allows to test the
hsmdaemon setup by providing an encrypted string to ownCloud and test if it can be decrypted.
sudo -u www-data php occ encryption:hsmdaemon:decrypt [options] [--] <decrypt>
The name of the user who is able to decrypt the provided string
The keyId which was used to encrypt the provided string
Set the url on which the
hsmdaemon REST-API is reachable.
sudo -u www-data php occ config:app:set encryption hsm.url --value 'http://127.0.0.1:8513'
To access the
hsmdaemon API, ownCloud must authenticate with a JWT (JSON Web Token). The given secret is shared between the
hsdmdaemon (see the hsmdaemon.toml configuration file) and ownCloud to sign the JWT. See the HSM documentation for an example how to generate a secret.
sudo -u www-data php occ config:app:set encryption hsm.jwt.secret --value '7a7d1826-b514-4d9f-afc7-a7485084e8de'
The JWT described above has an expiry timestamp. In case the time clocks on ownCloud and hsmdaemon system drift or skew appart, additional time is added to the expiry time to counteract this situation. Set or change the clockskew only if ownCloud advises to do so. Defaults to 120, value is in seconds.
sudo -u www-data php occ config:app:set encryption hsm.jwt.clockskew --value '120'