FreeNAS, TrueNAS, GELI, and native ZFS encryption

The fine details and combinations of encryption modes, keys, and passwords in FreeNAS, TrueNAS Core, and TrueNAS Scale are pretty labyrinthine. There are two different encryption mechanisms - native ZFS encryption and GELI encryption, each using a specific key material format. So if you need to recover an encrypted TrueNAS/FreeNAS system, you must sort out the keys and the encryption methods.

Native ZFS encryption vs. GELI encryption

Native ZFS encryption

• Applies to ZFS datasets.
• You can have different passwords, key files, or unencrypted data on different datasets within the same ZFS pool.
• Uses a passphrase or a 32-byte binary key file.
• First available in TrueNAS version 12.0.

GELI encryption

• Applies to ZFS pools. Technically, it applies to partitions, but FreeNAS/TrueNAS implementation applies the same key file to all disks in the pool. If you expand the pool by adding more disks, the system encrypts the new disks with the same key.
• Uses a 64-byte binary key file. Additionally, you can configure a passphrase to protect the key file, but the passphrase alone is not enough for recovery.
• You can ask the FreeNAS system for an additional "recovery key", another 64-bit binary key file.
• Available in FreeNAS and TrueNAS before version 12.0. After TrueNAS 12.0, TrueNAS Core can read GELI-encrypted pools but does not allow the creation of new ones. TrueNAS Scale does not support GELI at all.

Recovery process

There are differences depending on if the damaged pool used GELI or native ZFS encryption.

• Decrypting GELI requires precise knowledge of the partition layout, while decrypting ZFS native encryption does not. If the partition tables are damaged, this may become a problem.
• Only one copy of GELI metadata is stored for each encrypted partition, occupying its last 512 bytes. If this metadata is damaged or overwritten, recovery is not possible.
• GELI encryption is more apparent. Its metadata is readily accessible and can be readily verified against the key files, even before the scan starts. With ZFS encryption, the near-complete reconstruction of the filesystem is required to find the metadata and verify if the keys are valid.

The process outline is as follows:

1. Collect all the key material available, both key files and passphrases.
2. Start Klennet ZFS Recovery, select the pool member partitions, then click "Proceed".
   1. If there is only one partition on each disk, select this one partition.
   2. If there are multiple partitions, select the largest one unless you know otherwise.
   3. If there are no partitions at all, select physical disks.
3. GELI encryption
   1. If GELI encryption is detected, the number of partitions remaining to unlock is displayed in red.
   2. Load whatever GELI key files you have available. You can load all the key files you have because ZFS Recovery rejects the wrong ones anyway.
   3. Once all partitions are unlocked, Klennet ZFS Recovery stops accepting additional GELI key files.
   4. Something is wrong if you have tried all your key files and not all the partitions are unlocked. Consider filing a support request.
4. Native ZFS encryption
   1. ZFS Recovery cannot detect native ZFS encryption before starting the scan.
   2. Upload all the key files you have, then enter all the passphrases.
   3. If copy-pasting the passphrases, avoid including extra trailing or leading spaces.
   4. ZFS Recovery checks that the key files match the size requirement. Something is probably mixed up if you have key files of the wrong size. Consider filing a support request.
5. When done adding encryption keys, start the scan.

If the key files and passphrases are good, the only difference between scanning an encrypted pool and a regular one is speed and CPU usage. You may want to use more cores or a higher-end CPU while recovering an encrypted pool.

Filed under: Encryption, NAS.

Created Tuesday, February 22, 2022