TrueNAS SCALETrueNAS SCALE Version Documentation
This content follows the TrueNAS SCALE 23.10 (Cobia) releases. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

Encryption Settings

  6 minute read.

Last Modified 2024-03-19 08:38 EDT

Datasets, root, non-root parent, and child, or zvols with encryption include the ZFS Encryption widget in the set of dataset widgets displayed on the Datasets screen.

Dataset Tree Table Encryption Icons
Figure 1: Dataset Tree Table Encryption Icons

The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.

IconStateDescription
DatasetLockedEncryptionIconLockedDisplays for locked encrypted root, non-root parent and child datasets.
DatasetUnlockedEncryptionIconUnlockedDisplays for unlocked encrypted root, non-root parent and child datasets.
DatasetLockedByAncestorEncryptionIconLocked by ancestorDisplays for locked datasets that inherit encryption properties from the parent.
DatasetUnlockedbyAncestorEncryptIconUnlocked by ancestorDisplays for unlocked datasets that inherit encryption properties from the parent.

Pool Encryption

The Encryption option on the Pool Manager screen sets encryption for the pool and root dataset. The Download Encryption Key warning window displays when you create the pool. It downloads a JSON file to your downloads folder.

Download Pool Encryption Key
Figure 2: Download Pool Encryption Key

Export Key Options

The ZFS Encryption widget for root datasets with encryption includes the Export All Keys and Export Key options but does not include the Lock option.

If a dataset is encrypted using a key, the ZFS Encryption widget for that dataset includes the Export Key option.

Export All Keys Dialog

Export All Keys opens a confirmation dialog with the Download Keys option that exports a JSON file of all encryption keys to the system download folder.

Export All Keys
Figure 3: Export All Keys

Export Key Dialog

Export Key opens a dialog with the key for the selected dataset and the Download Key option that exports a JSON file with the encryption key to your system download folder.

Export Key
Figure 4: Export Key

Edit Encryption Options Window

Encryption type and options are set for a dataset when it is first created and are inherited from the root dataset. The Edit Encryption Options for datasetname displays the current encryption option settings for the selected encrypted dataset. Use to change the encryption type from or to key or passphrase, and the related settings.

The Edit Encryption Options for datasetname window opens with the current dataset encryption settings displayed. The encryption setting options are the same as those found on Add Dataset > Encryption Options.

SettingDescription
Encryption TypeSelect the option for the type of encryption to secure the dataset from the dropdown list. Select Key to use key-based encryption and display the Generate Key option. Select Passphrase to enter a user-defined passphrase to secure the dataset. This displays two additional Passphrase fields to enter and confirm the passphrase and the pbkdf2iters field.
Generate keySelected by default to have the system randomly generate an encryption key for securing this dataset. Clearing the checkbox displays the Key field and requires you to enter an encryption key you define. Warning! The encryption key is the only means to decrypt the information stored in this dataset. Store encryption keys in a secure location! Creating a new key file invalidates any previously downloaded key file for this dataset. Delete any previous key file backups and back up the new key file.
KeyEnter or paste a string to use as the encryption key for this dataset.
AlgorithmDisplays for both key and passphrase encryption types. Select the mathematical instruction set that determines how plaintext converts into ciphertext from the dropdown list of options. See Advanced Encryption Standard (AES) for more details.
Passphrase
Confirm Passphrase
Enter the alpha-numeric string or phrase you want to use to secure the dataset.
pbkdf2itersEnter the number of password-based key deviation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.

Lock Dataset Dialog

Lock displays on encrypted non-root parent or child datasets ZFS Encryption widgets. An encrypted child that inherits encryption from a non-root parent does not see the Lock option on its ZFS Encryption widget because the lock state is controlled by the parent dataset for that child dataset. The locked icon for child datasets that inherit encryption is the locked by ancestor icon.

Lock opens the Lock Dataset confirmation dialog with the option to Force unmount and Lock the dataset. Force unmount disconnects any client system that is accessing the dataset via sharing protocol. Do not select this option unless you are certain the dataset is not used or accessed by a share, application, or other system services.

After locking a dataset, the ZFS Encryption screen displays Locked as the Current State and adds the Unlock option.

Unlock Datasets Screen

Unlock on the ZFS Encryption widget displays for locked datasets that are not child datasets that inherit encryption from the parent dataset. Unlock opens the Unlock Datasets screen that allows you to unlock the selected dataset, and the child datasets at the same time.

If you select a non-root parent dataset, the unlock screen includes two Dataset Passphrase fields for two datasets, the non-root parent and the child of that non-root parent, and the option to Unlock Child Encrypted Roots pre-selected.

If you select a child dataset of the root dataset or of a non-root parent, the screen includes only the one Dataset Passphrase field, and the option to Unlock Child Encrypted Roots pre-selected.

SettingDescription
Unlock Child Encrypted RootsSelect to inlock any encrypted dataset stored within this dataset.
Dataset Passphrase
Dataset Key
Enter the user-defined string (passphrase) or system-generated or user-created alpha-numeric key you entered at the time you created the dataset.
ForceSelect to add a force flag to the operation. In some cases it is possible that the provided key/passphrase is valid but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, unlock operation fails. Adding the force flag can override this and when selected, the system renames the existing dataset mount directory/file path and it unlocks the dataset.
SaveStarts the unlock process, fetch data, and displays the Unlock Datasets dialog with the dataset mount path. Click Continue to unlock the dataset.

Related Content

Related Dataset Articles