Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ZFS-LOAD-KEY(8)		  BSD System Manager's Manual	       ZFS-LOAD-KEY(8)

     zfs-load-key -- Load, unload, or change the encryption key	used to	access
     a dataset.

     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

     zfs load-key [-nr]	[-L keylocation] -a | filesystem
       Load the	key for	filesystem, allowing it	and all	children that inherit
       the keylocation property	to be accessed.	The key	will be	expected in
       the format specified by the keyformat and location specified by the
       keylocation property. Note that if the keylocation is set to prompt the
       terminal	will interactively wait	for the	key to be entered. Loading a
       key will	not automatically mount	the dataset. If	that functionality is
       desired,	zfs mount -l will ask for the key and mount the	dataset	(see
       zfs-mount(8)).  Once the	key is loaded the keystatus property will be-
       come available.

       -r  Recursively loads the keys for the specified	filesystem and all de-
	   scendent encryption roots.

       -a  Loads the keys for all encryption roots in all imported pools.

       -n  Do a	dry-run	("No-op") load-key. This will cause zfs	to simply
	   check that the provided key is correct. This	command	may be run
	   even	if the key is already loaded.

       -L keylocation
	   Use keylocation instead of the keylocation property.	This will not
	   change the value of the property on the dataset. Note that if used
	   with	either -r or -a, keylocation may only be given as prompt.

     zfs unload-key [-r] -a | filesystem
       Unloads a key from ZFS, removing	the ability to access the dataset and
       all of its children that	inherit	the keylocation	property. This re-
       quires that the dataset is not currently	open or	mounted. Once the key
       is unloaded the keystatus property will become 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.

     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 (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
       keylocation, keyformat, and pbkdf2iters properties as needed. If	the
       dataset was not previously an encryption	root it	will become one. Al-
       ternatively, the	-i flag	may be provided	to cause an encryption root to
       inherit the parent's key	instead.

       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.

       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

       -l  Ensures the key is loaded before attempting to change the key. This
	   is effectively equivalent to	"zfs load-key filesystem; zfs
	   change-key filesystem"

       -o property=value
	   Allows the user to 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.

       -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.

     Enabling the encryption feature allows for	the creation of	encrypted
     filesystems and volumes.  ZFS will	encrypt	file and zvol data, file at-
     tributes, 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).

     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	zfs load-key subcommand	for more info on key

     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 im-
     plicitly 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 en-
     cryption 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 en-
     cryption-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 inheri-
     tance 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 en-
     cryption suite, which provides additional protection against maliciously
     altered data. Deduplication is still possible with	encryption enabled but
     for security, datasets will only dedup against themselves,	their snap-
     shots, and	their clones.

     There are a few limitations on encrypted datasets.	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 be-
     fore encryption datasets may be vulnerable	to a CRIME-like	attack if ap-
     plications	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 per block written.

     zfs-create(8), zfs-set(8),	zfsprops(8)

BSD			       January 13, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help