Skip to content
Browse files

Document zfs change-key caveats

As discussed on the 2019-01-07 OpenZFS Leadership Meeting, we need to be
clear about the limitations of `zfs change-key`.  Changing the user key
does not change the master key, nor does it currently overwrite the old
wrapped master key on disk.

Reviewed-by: Tom Caputi <>
Reviewed-by: Brian Behlendorf <>
Reviewed-by: Matt Ahrens <>
Reviewed-by: George Melikov <>
Reviewed-by: Garrett Fields <>
Reviewed-by: Kjeld Schouten <>
Signed-off-by: Richard Laager <>
Closes #9819
  • Loading branch information
rlaager authored and behlendorf committed Jan 14, 2020
1 parent 7e2da77 commit f744f36ce583ed27dcfcda93ecd0af1df994a891
Showing with 25 additions and 2 deletions.
  1. +25 −2 man/man8/zfs-load-key.8
@@ -30,7 +30,7 @@
.\" Copyright 2018 Nexenta Systems, Inc.
.\" Copyright 2019 Joyent, Inc.
.Dd June 30, 2019
.Dd January 13, 2020
.Os Linux
@@ -154,7 +154,7 @@ Unloads the keys for all encryption roots in all imported pools.
.Op Fl l
.Ar filesystem
Allows a user to change the encryption key used to access a dataset. This
Changes the user's key (e.g. a passphrase) used to access a dataset. This
command requires that the existing key for the dataset is already loaded into
ZFS. This command may also be used to change the
.Sy keylocation ,
@@ -166,6 +166,29 @@ will become one. Alternatively, the
.Fl i
flag may be provided to cause an encryption root to inherit the parent's key
If the user's key is compromised,
.Nm zfs Cm 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,
.Nm zfs Cm 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.
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
.Nm zfs Cm send
.Nm zfs Cm recv Ns
), and then clearing the free space with
.Nm zpool Cm trim --secure
if supported by your hardware, otherwise
.Nm zpool Cm initialize Ns .
.Bl -tag -width "-r"
.It Fl l
Ensures the key is loaded before attempting to change the key. This is

0 comments on commit f744f36

Please sign in to comment.
You can’t perform that action at this time.