(408) 943-4100               V   Commercial Support Toggle between Light and Dark mode
TrueNAS.com Software Systems Company Community Security iX Portal Download
  1. Documentation Hub
  2. /
  3. TrueNAS CORE and Enterprise
  4. /
  5. Storage
  6. /
  7. Pools
  8. /
  9. Storage Encryption
Edit this page

Storage Encryption

  8 minute read.

Last Modified 2021-09-30 10:50 EDT

TrueNAS supports different encryption options for critical data.

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 TrueNAS system manages keys for data-at-rest. The user is responsible for storing and securing their keys. The Key Management Interface Protocol (KMIP) is included in TrueNAS 12.0.

Always consider the following drawbacks/considerations when encrypting data:

  • Losing encryption keys and passwords means losing your data.
  • 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 will all compete for the same CPU cycles.

Encrypting a Storage Pool

Encrypting the root dataset of a new storage pool further increases data security. Create a new pool and set Encryption in the Pool Manager. TrueNAS shows a warning.

Storage Pools Add Encryption Warning

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

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

StoragePoolsAddCreateEncryptionCipher

TrueNAS 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

TrueNAS 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.

StoragePoolsDatasetAdd

In the Encryption Options area, unset Inherit and check Encryption.

StoragePoolsCreateDatasetEncryptionOptions

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

Locking and Unlocking Datasets

The dataset status is determined from an icon:

  • The dataset unlocked icon: .
  • The dataset locked icon: .
  • A Dataset on an encrypted pool with encryption properties that don’t match the root dataset have this icon: UnecryptedPoolEncryptionDatasetIcon.

NOTE: An unencrypted pool with an encrypted dataset will also show this icon: UnecryptedPoolEncryptionDatasetIcon
.

Encrypted datasets can only be locked and unlocked when secured with a passphrase instead of a keyfile. Before locking a dataset, verify that it is not currently in use, then click   (Options) and Lock.

StoragePoolsDatasetLockOptions

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.

StoragePoolsDatasetUnlockOptions

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

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

StoragePoolsDatasetUnlockSuccess

Example:

StoragePoolsDatasetUnlockexample1

The parent dataset is media. It has three child datasets. The documents child dataset has “inherited” the parent encryption settings and its password. The other two child datasets (audio and video) have their own passphrases. When the parent dataset is locked, all child datasets lock too.

StoragePoolsDatasetUnlockexample2

Open the for the parent dataset and select unlock. To unlock all the datasets, check the Unlock Children and enter the passphrase for each dataset that needs to be unlocked.

StoragePoolsDatasetUnlockexample3

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 Key Files or Passphrases:

Key Files

Creating a new encrypted pool automatically generates a new key file and prompts you to download it. Always back up the key file to a safe and secure location.

EncryptionKeyBackupWarning

Manually download a copy of the pool’s inherited and non-inherited encrypted dataset keyfiles by opening the pool menu and selecting Export Dataset Keys. Enter the root password and click the CONTINUE button.

StoragePoolsEncryptionActionsExportKeys

To manually download a back up of a single dataset’s keyfile, click the dataset and select Export Key. Enter the root password and click the CONTINUE button. Click the DOWNLOAD KEY button.

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

StoragePoolsEncryptedDataset

Enter your custom key or click Generate Key.

StoragePoolsEncryptedDatasetOptions

Passphrases

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

Storage Pools Dataset Encryption Passphrase

Set the rest of the options:

  • Passphrase : User-defined string used to decrypt the dataset. Can be used instead of an encryption key. Must be longer than 8 characters.
    The passphrase is the only means to decrypt the information stored in this dataset. Be sure to create a memorable passphrase or physically secure the passphrase.
  • pbkdf2iters : Number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number greater than 100000 is required.

Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase

TrueNAS Enterprise users may connect a Key Management Interoperability Protocol (KMIP) server to centralize keys when they are not using passphrases to unlock a dataset or zvol.

Users with TrueNAS CORE or Enterprise installations without KMIP should 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.

  1. Replicate every encrypted dataset you want to replicate with properties.
  2. Export key for every child dataset which has a unique key.
  3. For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this: {"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
  4. Save this file with the extension .json.
  5. On remote system unlock the dataset(s) using properly constructed json files.

Uncheck properties when replicating so that the destination dataset will not be encrypted on the remote side and will not require a key to unlock.

  1. Go to Tasks > Replication Tasks and click ADD.
  2. Click ADVANCED REPLICATION CREATION.
  3. Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
  4. Click SUBMIT.
NOTE: This does not affect TrueNAS Enterprise installs with KMIP.

Legacy GELI Encryption

TrueNAS no longer supports GELI encryption (deprecated).

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. Be sure to 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 have verified the data migration.

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

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

Start the Replication Wizard by selecting Tasks -> Replication Task -> ADD

Source Location:

  • Select On this System.
  • Set the dataset to transfer.

Destination Location:

  • Select On a Different System.

SSH Connection:

  • Either Created the ssh connection by clicking Create New or select the destination system’s ssh connection.
  • In Destination, select the dataset to replicate the files to.
  • Set Encryption.
  • Choose either PASSPHRASE or HEX for the Encryption Key Format.
  • If you selected PASSPHRASE, enter the passphrase. If you selected HEX, set Generate Encryption Key.
  • Set Store Encryption key in Sending TrueNAS database.
  • Click Next

Replication Schedule:

  • Set Run Once in Replication Schedule.

  • Unset Make Destination Dataset Read-Only.

  • Click START REPLICATION

This method does not preserve file ACLs.

The web interface supports using Tasks > Rsync Tasks to transfer files out of the GELI pool. In the Shell, rsync and other file transfer mechanisms (scp, cp, sftp, ftp, rdiff-backup) are available for copying data between pools.

These instructions are an example walkthrough. It is 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.

Legend:

GELI Pool = pool_a
Origin Dataset = dataset_1
Latest Snapshot of GELI Pool = snapshot_name
ZFS Native Encrypted Pool = pool_b
Receieving 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 be migrated: 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: 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. When the transfer is complete, go to Storage > Pools and lock the new dataset. After locking the dataset, immediately unlock it. TrueNAS 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 keyfile 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.