Skip to content
Permalink
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 <tcaputi@datto.com>
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Reviewed-by: Matt Ahrens <matt@delphix.com>
Reviewed-by: George Melikov <mail@gmelikov.ru>
Reviewed-by: Garrett Fields <ghfields@gmail.com>
Reviewed-by: Kjeld Schouten <kjeld@schouten-lebbing.nl>
Signed-off-by: Richard Laager <rlaager@wiktel.com>
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
.Dt ZFS-LOAD-KEY 8
.Os Linux
.Sh NAME
@@ -154,7 +154,7 @@ Unloads the keys for all encryption roots in all imported pools.
.Op Fl l
.Ar filesystem
.Xc
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
instead.
.Pp
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.
.Pp
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.