As part of updating docs for
NAS-102362, I discovered the new UI and docs are out of sync with the apparent behavior of geli and FreeNAS when creating/modifying encrypted pools. I'm opening this epic to track any/all subissues related to getting UI and Docs back in sync and pasting my research and notes from discussing this with Engineering and Support.
After discussing the issues with a few people in the office and looking at a few online resources, I've arrived at this understanding of how we're using GELI:
- GELI "Master Key": Randomized and encrypted AES key that is generated on each provider(disk) when the pool is created. This is stored in each provider's GELI metadata. This is completely invisible in the FreeNAS UI.
- GELI "User Key": Decrypts the Master Key and allows access to the encrypted data. Generated when the pool is created. Consists of two components: a keyfile and/or a passphrase. This is the primary part of GELI that users interact with in the FreeNAS UI.
- The GELI "User Key" can have two "slots/subkeys" in FreeNAS: a Primary Key (no standard term) is generated with the pool, stored in /data/geli, has no passphrase associated, and is used to keep the pool unlocked after reboots. Creating a Passphrase modifies this key, making the pool lockable/unlockable in the UI. A Recovery Key is a file generated in the UI as an alternate method to interact with the "User Key". It is registered with the GELI metadata in the drives, but it doesn't use passphrases and is not stored anywhere on the FreeNAS system.
Notes from investigating FreeNAS code with Support:
On zpool creation, we set an encryption key in slot 0 and keep that key in /data/geli. We do not add a recovery key at this stage. The webUI prompts the end-user to download the "recovery" key upon creation of the zpool which is incorrect because the recovery key doesn't exist. It's actually just downloading the encryption key.
When a user chooses to add a recovery key, we geli setkey in slot 1 for the zpool and then prompt the user to download the "recovery" key (not the encryption key).