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

NAME
     zfs-load-key - load, unload, or change encryption key of ZFS dataset

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

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

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

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

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

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

FreeBSD 13.1-RELEASE-p6        January 13, 2020        FreeBSD 13.1-RELEASE-p6