Encryption

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

Status

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 occ encryption:enable:

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

Encrypt the Users Home Storage

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 0 and 1

config:app:set encryption encryptHomeStorage --value '1'

Change Key Storage Root

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/)

List Modules

encryption:list-modules displays your available encryption modules. You will see a list of modules only if you have enabled the Encryption app. Use encryption:set-default-module [module name] to set your desired module.

Encrypt All

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.

Arguments

-y or --yes

Answer yes to all questions. This argument automatically answers, potential, questions with "yes", which is particularly important for automated deployments with Ansible or similar tools.

Decrypt All

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.

Arguments

-m=[METHOD]

Accepts the methods:
recovery or password
If the recovery method is chosen, then the recovery password will be used to decrypt files.
If the password method is chosen, then individual user passwords will be used to decrypt files.

-c=[COMMAND]

Accepts the commands:
yes or no

This lets the command know whether to ask for permission to continue or not.

Fix Encrypted Version

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.

Background: the 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.

Arguments

user

The id of the user whose files need fixing.

Method Descriptions

Recovery method

This method reads the value from the environment variable OC_RECOVERY_PASSWORD. 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.

Password method

This method reads the value from the environment variable OC_PASSWORD. This variable bounds the value of user password. The password which user uses to login to oC account. When password method is opted the user needs to set this variable in the shell.

Continue Option Description

The continue option can be used to by pass the permissions asked like yes or 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. If -c no is passed to the command, then permissions would be asked to the user. It becomes interactive.

Use 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. The -y switch can be supplied to automate acceptance of user input.

Export or Import the Masterkey

sudo -u www-data php occ encryption:hsmdaemon [options]

Options

--export-masterkey

Export the private master key in base64

--import-masterkey=
IMPORT-MASTERKEY

Import a base64 encoded private masterkey.

--export-masterkey prints the base64_encode of the file data/files_encryption/OC_DEFAULT_MODULE/master_*.privateKey.

The private key file in the directory may named like master_08ea43b7.privateKey.

Test to Decrypt a String

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>

Arguments

decrypt

The string to decrypt

Options

--username[=USERNAME]

The name of the user who is able to decrypt the provided string

--keyId[=KEYID]

The keyId which was used to encrypt the provided string

Set the HSM URL

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'

Set the JSON Web Token Secret

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'

Set the JWT Clockskew

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'