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

FreeBSD Manual Pages


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

     zfs-load-key -- load, unload, or change encryption	key of ZFS 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.	Load-
       ing a key will not automatically	mount the dataset.  If that function-
       ality 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 prop-
       erty will become	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.	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.  Alternatively,
       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 running 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 volume	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	load-key subcommand for	more info on key load-

     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 deduplicate against themselves,
     their snapshots, 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 encryp-
     tion will leak information	about which blocks are equivalent in a dataset
     and will incur an extra CPU cost for each block written.

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

FreeBSD	13.0		       January 13, 2020			  FreeBSD 13.0


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

home | help