|ZFS-LOAD-KEY(8)||System Manager's Manual||ZFS-LOAD-KEY(8)|
Load, unload, or change the encryption key used to access a
- 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
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.
- Recursively loads the keys for the specified filesystem and all descendent encryption roots.
- Loads the keys for all encryption roots in all imported pools.
- 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.
- 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
-a, keylocation may only be given as prompt.
- 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.
- 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. Alternatively, the
-iflag may be provided to cause an encryption root to inherit the parent's key instead.
If the user's key is compromised,
change-keydoes 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,
change-keydoes 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
recv), and then clearing the free space with
trim --secureif supported by your hardware, otherwise
- Ensures the key is loaded before attempting to change the key. This is
effectively equivalent to "
- 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.
- 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 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
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
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
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 dedup 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 per block written.
|January 13, 2020||Linux|