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)

OpenZFS                                         January 13, 2020                                 ZFS-LOAD-KEY(8)