ZFS-LOAD-KEY(8)

💖 zfs-load-key — the girlies' guide to loading, unloading, and changing your ZFS dataset's encryption key 🔑

okay so bestie, welcome to zfs-load-key from section 8 of the System Manager's Manual. this is the glow-up command for your encryption keys — loading them, yeeting them, and changing them. let's get into it ✨

---

🌸 SYNOPSIS 🌸

zfs load-key [-nr] [-L keylocation] -a|filesystem
zfs unload-key [-r] -a|filesystem
zfs change-key [-l] [-o keylocation=value] [-o keyformat=value]
    [-o pbkdf2iters=value] filesystem
zfs change-key -i [-l] filesystem

---

🦋 DESCRIPTION 🦋

zfs load-key [-nr] [-L keylocation] -a|filesystem

Loads the key for filesystem, which lets it — and every child that inherits the keylocation property — be accessed. 🔓 The key is expected in the format specified by keyformat, and at the location specified by keylocation. Heads up: if keylocation is set to prompt, the terminal will just... wait. interactively. for you to type the key in. 😭

Loading a key does not automatically mount the dataset. Not me expecting it to either 💀. If you want that whole situation, zfs mount -l will ask for the key and mount the dataset for you (peep zfs-mount(8)). Once the key is loaded, the keystatus property becomes available. slay.

• -r — recursively loads the keys for the specified filesystem and all descendent encryption roots. 🌳
• -a — loads the keys for all encryption roots in all imported pools. every single one, periodt.
• -n — do a dry-run ("No-op") load-key. this makes zfs simply check that the provided key is correct. and get this — you can run this even if the key is already loaded. obsessed. 👑
• -L keylocation — use keylocation instead of the keylocation property. this will not change the value of the property on the dataset. ngl, if you use this with either -r or -a, keylocation may only be given as prompt.

zfs unload-key [-r] -a|filesystem

Unloads a key from ZFS, which removes the ability to access the dataset and all of its children that inherit the keylocation property. 🔒 This requires that the dataset is not currently open or mounted — so like, close your apps first bestie. Once the key is unloaded, the keystatus property becomes unavailable.

• -r — recursively unloads the keys for the specified filesystem and all descendent encryption roots. 🌳
• -a — unloads the keys for all encryption roots in all imported pools. the full sweep 💅

zfs change-key [-l] [-o keylocation=value] [-o keyformat=value] [-o pbkdf2iters=value] filesystem

zfs change-key -i [-l] filesystem

Changes the user's key (like, a passphrase, iykyk) used to access a dataset. This command requires that the existing key for the dataset is already loaded. You can also use it to change the keylocation, keyformat, and pbkdf2iters properties as needed. If the dataset wasn't previously an encryption root, it will become one — main character energy fr. Alternatively, the -i flag can be provided to make an encryption root inherit the parent's key instead. 🧚

⚠️ Real talk, no cap: if the user's key is compromised, zfs change-key does not necessarily protect existing or newly-written data from attack. Newly-written data will continue to be encrypted with the same master key as the existing data. The master key is compromised if an attacker obtains a user key and the corresponding wrapped master key. Currently, zfs change-key does not overwrite the previous wrapped master key on disk, so it is accessible via forensic analysis for an indeterminate length of time. 😭 that's the tea and it's not cute tea.

In the event of a master key compromise, ideally the drives should be securely erased to remove all the old data (which is readable using the compromised master key), a new pool created, and the data copied back. This can be approximated in place by creating new datasets, copying the data (e.g. using zfs send | zfs recv), and then clearing the free space with zpool trim --secure if supported by your hardware, otherwise zpool initialize. 🔥

• -l — ensures the key is loaded before attempting to change the key. this is effectively equivalent to running zfs load-key filesystem; zfs change-key filesystem. two-for-one, we love efficiency ✨
• -o property=value — lets the user set encryption key properties (keyformat, keylocation, and pbkdf2iters) while changing the key. this is the only way to alter keyformat and pbkdf2iters after the dataset has been created. the only way, bestie. 👑
• -i — indicates that zfs should make filesystem inherit the key of its parent. note that this command can only be run on an encryption root that has an encrypted parent.

---

🎀 Encryption 🎀

Enabling the encryption feature allows for the creation of encrypted filesystems and volumes. ZFS will encrypt file and volume data, file attributes, ACLs, permission bits, directory listings, FUID mappings, and userused/groupused data. 🔐

ZFS will not encrypt metadata related to the pool structure, including dataset and snapshot names, dataset hierarchy, properties, file size, file holes, and deduplication tables (though the deduplicated data itself is encrypted). so like, the vibes are encrypted but the skeleton is visible, if you will 💀

Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase) does not require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered, renamed, and deleted without the encryption keys being loaded (see the load-key subcommand for more info on key loading). 🔄

Creating an encrypted dataset requires specifying the encryption and keyformat properties at creation time, along with an optional keylocation and pbkdf2iters. After entering an encryption key, the created dataset will become an encryption root. Any descendant datasets will inherit their encryption key from the encryption root by default, meaning that loading, unloading, or changing the key for the encryption root will implicitly do the same for all inheriting datasets. 🌈

If this inheritance is not desired, simply supply a keyformat when creating the child dataset, or use zfs change-key to break an existing relationship, creating a new encryption root on the child. Note that the child's keyformat may match that of the parent while still creating a new encryption root, and that changing the encryption property alone does not create a new encryption root — this would simply use a different cipher suite with the same key as its encryption root. The one exception is that clones will always use their origin's encryption key. As a result of this exception, some encryption-related properties (namely keystatus, keyformat, keylocation, and pbkdf2iters) do not inherit like other ZFS properties and instead use the value determined by their encryption root. Encryption root inheritance can be tracked via the read-only encryptionroot property. 👑

Encryption changes the behavior of a few ZFS operations. Encryption is applied after compression, so compression ratios are preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from the encryption suite, which provides additional protection against maliciously altered data. Deduplication is still possible with encryption enabled, but for security, datasets will only deduplicate against themselves, their snapshots, and their clones. 🦋

There are a few limitations on encrypted datasets, bestie, and we gotta be honest about them:

• Encrypted data cannot be embedded via the embedded_data feature.
• Encrypted datasets may not have copies=3, since the implementation stores some encryption metadata where the third copy would normally be.
• Since compression is applied before encryption, datasets may be vulnerable to a CRIME-like attack if applications accessing the data allow for it. 😬
• Deduplication with encryption will leak information about which blocks are equivalent in a dataset and will incur an extra CPU cost for each block written.

---

🌟 SEE ALSO 🌟

• zfsprops(7)
• zfs-create(8)
• zfs-set(8)

---

and that's the whole page, bestie!! this one came from the OpenZFS girlies, dated July 11, 2022, and it lives in section 8 as ZFS-LOAD-KEY(8) 🫶 go load those keys, you absolute icon 💅✨