FreeCORE Documentation freecore.org

Storage Encryption

Describes how to encrypt a storage pool in FreeCORE.

FreeCORE supports different encryption options for critical data.

Warning

Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.

Data-at-rest encryption is available with:

The local FreeCORE system manages keys for data-at-rest. The user is responsible for storing and securing their keys.

Encryption Drawbacks and Considerations

Always consider the following drawbacks/considerations when encrypting data:

  • All datasets contained within an encrypted pool inherit encryption.
  • If there is only one pool and it is encrypted, all datasets are also encrypted.
  • If the encryption keys and passwords are lost, encrypted data is unrecoverable.

Unrelated encrypted datasets do not support deduplication.

We do not recommend using GELI or ZFS encryption with deduplication because of the sizable performance impact.

Be cautious when using many encryption and deduplication features at once since they all compete for the same CPU cycles.

Encrypting a Storage Pool

Encrypting the root dataset of a new storage pool further increases data security. All datasets added to a pool with encryption applied inherit encryption. This means all datasets added to a pool with encryption are also encrypted.

Create a new pool and set Encryption in the Pool Manager. FreeCORE shows a warning.

Storage Pools Add Encryption Warning
Figure 1: Storage Pools Add Encryption Warning

Read the warning, select Confirm, and click I Understand.

We recommend using the default encryption in Cipher, but other ciphers are available.

Choosing an encryption cipher
Figure 2: Choosing an encryption cipher
What are these options?

FreeCORE supports AES Galois Counter Mode (GCM) and Counter with CBC-MAC (CCM) algorithms for encryption. These algorithms provide authenticated encryption with block ciphers.

Encrypting a New Dataset

FreeCORE can encrypt new datasets within an existing unencrypted storage pool without having to encrypt the entire pool. To encrypt a single dataset, go to Storage > Pools, open the for an existing dataset, and click Add Dataset.

New Dataset Options
Figure 3: New Dataset Options

In the Encryption Options area, clear the Inherit checkbox, then select Encryption.

Dataset Encryption Options
Figure 4: Dataset Encryption Options

Now select the authentication to use from the two options in Type: either a Key or Passphrase. The remaining options are the same as a new pool. Datasets with encryption enabled show additional icons on the Storage > Pools list.

Locking and Unlocking Datasets

The dataset locked/unlocked status is determined from an icon:

UnecryptedPoolEncryptionDatasetIcon
Figure 16: Unencrypted Storage Pool with an Unencrypted Dataset

Note

NOTE: An unencrypted pool with an encrypted dataset also shows this icon:

UnecryptedPoolEncryptionDatasetIcon
Figure 17: Unencrypted Storage Pool with an Unencrypted Dataset

You can only lock or unlock encrypted datasets when they are secured with a passphrase instead of a key file. Before locking a dataset, verify that it is not currently in use, then click   (Options) and Lock.

Dataset Locking Options
Figure 5: Dataset Locking Options

Use the Force unmount option only if you are certain no one is currently accessing the dataset. After locking a dataset, the unlock icon changes to a locked icon. While the dataset is locked, it is not available for use.

To unlock a dataset, click and Unlock.

Dataset Unlock Options
Figure 6: Dataset Unlock Options

Enter the passphrase and click Submit. To unlock child datasets, select Unlock Children. Child datasets that inherited encryption settings from the parent dataset unlock when the parent unlocks. Users can simultaneously unlock child datasets with different passphrases from the parent by entering their passphrases.

Confirm unlocking the datasets and wait for a dialog to show the unlock is successful.

Dataset Unlock Success
Figure 7: Dataset Unlock Success
Example
Encrypted locked Datasets
Figure 8: Encrypted locked Datasets

The parent dataset is media. It has three child datasets. The documents child dataset inherits the parent encryption settings and password. The other two child datasets (audio and video) have their own passphrases. When you lock the parent dataset all child datasets are also locked.

Password for locked Datasets
Figure 9: Password for locked Datasets

Open the for the parent dataset and select unlock. To unlock all the datasets, select Unlock Children and enter the passphrase for each dataset to unlock.

Successfully unlocked Datasets
Figure 10: Successfully unlocked Datasets

Click the Continue button in the dialog window that confirms that the unlocking was successful. The dataset listing changes to show the unlocked icon.

Encryption Management

There are two ways to manage the encryption credentials, with either key files or passphrases.

Warning

Always back up the key file to a safe and secure location!

Key Files

Creating a new encrypted pool automatically generates a new key file and prompts you to download it.

Encryption Backup Warning
Figure 11: Encryption Backup Warning

Pool Key File

Manually download a copy of the inherited and non-inherited encrypted dataset key files for the pool by opening the pool menu and selecting Export Dataset Keys. Enter the root password and click CONTINUE.

Exporting Key Files
Figure 12: Exporting Key Files

Dataset Key File

To manually download a back up of a single key file for the dataset, click the dataset and select Export Key. Enter the root password and click CONTINUE. Click DOWNLOAD KEY.

To change the key, click the dataset and Encryption Options.

Dataset Options: Encryption Options
Figure 13: Encryption Options

Enter your custom key or click Generate Key.

Editing Encryption Options
Figure 14: Editing Encryption Options

Passphrases

Important

The passphrase is the only means to decrypt the information stored in a dataset using passphrase encryption keys. Be sure to create a memorable passphrase or physically secure the passphrase.

To use a passphrase instead of a key file, click the dataset and Encryption Options. Change the Encryption Type from Key to Passphrase.

Dataset Encryption Passphrase Options
Figure 15: Dataset Encryption Passphrase Options

Set the rest of the options:

Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase

Either replicate the dataset or zvol without properties to disable encryption at the remote end or construct a special json manifest to unlock each child dataset/zvol with a unique key.

Unlocking Methods

Method 1: Construct JSON Manifest
  1. Replicate every encrypted dataset you want to replicate with properties.
  2. Export key for every child dataset which has a unique key.
  3. Construct a proper json for each child dataset with poolname/datasetname of the destination system and key from the source system. For example: {"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
  4. Save this file with the extension .json.
  5. Unlock the dataset(s) on the remote system using properly constructed json files.
Method 2: Replicate Encrypted Dataset/zvol Without Properties

To not encrypt the dataset on the remote side so it does not require a key to unlock, clear properties when replicating.

  1. Go to Tasks > Replication Tasks and click ADD.
  2. Click ADVANCED REPLICATION CREATION.
  3. Fill out the form as needed and do not select Include Dataset Properties.
  4. Click SUBMIT.

Legacy GELI Encryption

FreeCORE no longer supports GELI encryption (deprecated).

Can I directly convert a GELI-encrypted pool to native ZFS encryption?

No. You must migrate data out of the GELI pool and into a ZFS encrypted pool.

GELI Pool Migrations

Data can be migrated from the GELI-encrypted pool to a new ZFS-encrypted pool. Unlock the GELI-encrypted pool before attempting any data migrations. The new ZFS-encrypted pool must be at least the same size as the previous GELI-encrypted pool. Do not delete the GELI dataset until you verify the data migration.

There are a few options to migrate data from a GELI-encrypted pool to a new ZFS-encrypted pool:

Using the Replication Wizard

GELI encrypted pools continue to be detected and supported in the FreeCORE web interface as Legacy Encrypted pools. As of FreeCORE version 12.0-U1, a decrypted GELI pool can migrate data to a new ZFS encrypted pool using the Replication Wizard.

Replication Wizard Method

Start the Replication Wizard, go to Tasks > Replication Task and click ADD.

  1. In Source Location, select On this System, then set the dataset to transfer.

  2. In Destination Location, select On a Different System, then:

    a. Create or select an existing SSH Connection. Either click Create New or select the destination system SSH connection from the list of available connections.

    b. In Destination, select the dataset to replicate files to.

    c. (Optional) Select Encryption to apply encryption to the SSH transfer. Select either PASSPHRASE or HEX as the Encryption Key Format. If you selected PASSPHRASE, enter the passphrase. If you selected HEX, set Generate Encryption Key. Select Store Encryption key in Sending FreeCORE database. Click Next

  3. Select Run Once as the replication schedule.

  4. Clear the Make Destination Dataset Read-Only checkbox.

  5. Click START REPLICATION

File Transfer Method

Important

This method does not preserve file ACLs.

The web interface supports using Tasks > Rsync Tasks to transfer files out of the GELI pool.

File Transfer Method

In the shell, rsync and other file transfer mechanisms (scp, cp, sftp, ftp, rdiff-backup) are available for copying data between pools.

ZFS Send and Receive

Important

These instructions are an example walk-through, and not an exact step-by-step guide for all situations. Research ZFS send/receive before attempting this. A simple example cannot cover every edge case.

ZFS Send and Receive Method

Legend:

  • GELI pool = pool_a
  • Origin dataset = dataset_1
  • Latest snapshot of GELI pool = snapshot_name
  • ZFS native-encrypted pool = pool_b
  • Receiving dataset = dataset_2
  1. Create a new encrypted pool in Storage > Pools.
  2. Open the shell. Make a new snapshot of the GELI pool and dataset with the data to migrate. Enter command: zfs snapshot -r pool_a/dataset_1@snapshot_name.
  3. Create a passphrase: echo passphrase > /tmp/pass.
  4. Use ZFS send/receive to transfer the data between pools. Enter command: zfs send -Rv pool_a/dataset_1@snapshot_name | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///tmp/pass pool_b/dataset_2.
  5. After the transfer completes, go to Storage > Pools and lock the new dataset. After locking the dataset, immediately unlock it. FreeCORE prompts for the passphrase. After entering the passphrase and unlocking the pool, you can delete the /tmp/pass file used for the transfer.
  6. If desired, you can convert the dataset to use a key file instead of a passphrase. To use a key file, click the dataset   (Options) and click Encryption Options. Change the Encryption Type from Passphrase to Key and save. Back up your key file immediately!
  7. Repeat this process for every dataset in the pool that you need to migrate.