302 lines
9.3 KiB
Groff
302 lines
9.3 KiB
Groff
.\"
|
|
.\" CDDL HEADER START
|
|
.\"
|
|
.\" The contents of this file are subject to the terms of the
|
|
.\" Common Development and Distribution License (the "License").
|
|
.\" You may not use this file except in compliance with the License.
|
|
.\"
|
|
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
|
|
.\" or http://www.opensolaris.org/os/licensing.
|
|
.\" See the License for the specific language governing permissions
|
|
.\" and limitations under the License.
|
|
.\"
|
|
.\" When distributing Covered Code, include this CDDL HEADER in each
|
|
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
|
|
.\" If applicable, add the following below this CDDL HEADER, with the
|
|
.\" fields enclosed by brackets "[]" replaced with your own identifying
|
|
.\" information: Portions Copyright [yyyy] [name of copyright owner]
|
|
.\"
|
|
.\" CDDL HEADER END
|
|
.\"
|
|
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
|
|
.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
|
|
.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
|
|
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
|
|
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
|
|
.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
|
|
.\" Copyright (c) 2014 Integros [integros.com]
|
|
.\" Copyright 2019 Richard Laager. All rights reserved.
|
|
.\" Copyright 2018 Nexenta Systems, Inc.
|
|
.\" Copyright 2019 Joyent, Inc.
|
|
.\"
|
|
.Dd January 13, 2020
|
|
.Dt ZFS-LOAD-KEY 8
|
|
.Os
|
|
.
|
|
.Sh NAME
|
|
.Nm zfs-load-key
|
|
.Nd load, unload, or change encryption key of ZFS dataset
|
|
.Sh SYNOPSIS
|
|
.Nm zfs
|
|
.Cm load-key
|
|
.Op Fl nr
|
|
.Op Fl L Ar keylocation
|
|
.Fl a Ns | Ns Ar filesystem
|
|
.Nm zfs
|
|
.Cm unload-key
|
|
.Op Fl r
|
|
.Fl a Ns | Ns Ar filesystem
|
|
.Nm zfs
|
|
.Cm change-key
|
|
.Op Fl l
|
|
.Op Fl o Ar keylocation Ns = Ns Ar value
|
|
.Op Fl o Ar keyformat Ns = Ns Ar value
|
|
.Op Fl o Ar pbkdf2iters Ns = Ns Ar value
|
|
.Ar filesystem
|
|
.Nm zfs
|
|
.Cm change-key
|
|
.Fl i
|
|
.Op Fl l
|
|
.Ar filesystem
|
|
.
|
|
.Sh DESCRIPTION
|
|
.Bl -tag -width ""
|
|
.It Xo
|
|
.Nm zfs
|
|
.Cm load-key
|
|
.Op Fl nr
|
|
.Op Fl L Ar keylocation
|
|
.Fl a Ns | Ns Ar filesystem
|
|
.Xc
|
|
Load the key for
|
|
.Ar filesystem ,
|
|
allowing it and all children that inherit the
|
|
.Sy keylocation
|
|
property to be accessed.
|
|
The key will be expected in the format specified by the
|
|
.Sy keyformat
|
|
and location specified by the
|
|
.Sy keylocation
|
|
property.
|
|
Note that if the
|
|
.Sy keylocation
|
|
is set to
|
|
.Sy 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,
|
|
.Nm zfs Cm mount Fl l
|
|
will ask for the key and mount the dataset
|
|
.Po
|
|
see
|
|
.Xr zfs-mount 8
|
|
.Pc .
|
|
Once the key is loaded the
|
|
.Sy keystatus
|
|
property will become
|
|
.Sy available .
|
|
.Bl -tag -width "-r"
|
|
.It Fl r
|
|
Recursively loads the keys for the specified filesystem and all descendent
|
|
encryption roots.
|
|
.It Fl a
|
|
Loads the keys for all encryption roots in all imported pools.
|
|
.It Fl n
|
|
Do a dry-run
|
|
.Pq Qq No-op
|
|
.Cm load-key .
|
|
This will cause
|
|
.Nm zfs
|
|
to simply check that the provided key is correct.
|
|
This command may be run even if the key is already loaded.
|
|
.It Fl L Ar keylocation
|
|
Use
|
|
.Ar keylocation
|
|
instead of the
|
|
.Sy keylocation
|
|
property.
|
|
This will not change the value of the property on the dataset.
|
|
Note that if used with either
|
|
.Fl r
|
|
or
|
|
.Fl a ,
|
|
.Ar keylocation
|
|
may only be given as
|
|
.Sy prompt .
|
|
.El
|
|
.It Xo
|
|
.Nm zfs
|
|
.Cm unload-key
|
|
.Op Fl r
|
|
.Fl a Ns | Ns Ar filesystem
|
|
.Xc
|
|
Unloads a key from ZFS, removing the ability to access the dataset and all of
|
|
its children that inherit the
|
|
.Sy keylocation
|
|
property.
|
|
This requires that the dataset is not currently open or mounted.
|
|
Once the key is unloaded the
|
|
.Sy keystatus
|
|
property will become
|
|
.Sy unavailable .
|
|
.Bl -tag -width "-r"
|
|
.It Fl r
|
|
Recursively unloads the keys for the specified filesystem and all descendent
|
|
encryption roots.
|
|
.It Fl a
|
|
Unloads the keys for all encryption roots in all imported pools.
|
|
.El
|
|
.It Xo
|
|
.Nm zfs
|
|
.Cm change-key
|
|
.Op Fl l
|
|
.Op Fl o Ar keylocation Ns = Ns Ar value
|
|
.Op Fl o Ar keyformat Ns = Ns Ar value
|
|
.Op Fl o Ar pbkdf2iters Ns = Ns Ar value
|
|
.Ar filesystem
|
|
.Xc
|
|
.It Xo
|
|
.Nm zfs
|
|
.Cm change-key
|
|
.Fl i
|
|
.Op Fl l
|
|
.Ar filesystem
|
|
.Xc
|
|
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
|
|
.Sy keylocation ,
|
|
.Sy keyformat ,
|
|
and
|
|
.Sy pbkdf2iters
|
|
properties as needed.
|
|
If the dataset was not previously an encryption root it will become one.
|
|
Alternatively, the
|
|
.Fl i
|
|
flag may be provided to cause an encryption root to inherit the parent's key
|
|
instead.
|
|
.Pp
|
|
If the user's key is compromised,
|
|
.Nm zfs Cm 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,
|
|
.Nm zfs Cm 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.
|
|
.Pp
|
|
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
|
|
.Pq e.g. using Nm zfs Cm send | Nm zfs Cm recv ,
|
|
and then clearing the free space with
|
|
.Nm zpool Cm trim Fl -secure
|
|
if supported by your hardware, otherwise
|
|
.Nm zpool Cm initialize .
|
|
.Bl -tag -width "-r"
|
|
.It Fl l
|
|
Ensures the key is loaded before attempting to change the key.
|
|
This is effectively equivalent to runnin
|
|
.Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
|
|
.It Fl o Ar property Ns = Ns Ar value
|
|
Allows the user to set encryption key properties
|
|
.Pq Sy keyformat , keylocation , No and Sy pbkdf2iters
|
|
while changing the key.
|
|
This is the only way to alter
|
|
.Sy keyformat
|
|
and
|
|
.Sy pbkdf2iters
|
|
after the dataset has been created.
|
|
.It Fl i
|
|
Indicates that zfs should make
|
|
.Ar filesystem
|
|
inherit the key of its parent.
|
|
Note that this command can only be run on an encryption root
|
|
that has an encrypted parent.
|
|
.El
|
|
.El
|
|
.Ss Encryption
|
|
Enabling the
|
|
.Sy 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
|
|
.Sy userused Ns / Ns Sy 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).
|
|
.Pp
|
|
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
|
|
.Cm load-key
|
|
subcommand for more info on key loading).
|
|
.Pp
|
|
Creating an encrypted dataset requires specifying the
|
|
.Sy encryption No and Sy keyformat
|
|
properties at creation time, along with an optional
|
|
.Sy keylocation No and Sy 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
|
|
.Sy keyformat
|
|
when creating the child dataset or use
|
|
.Nm zfs Cm change-key
|
|
to break an existing relationship, creating a new encryption root on the child.
|
|
Note that the child's
|
|
.Sy keyformat
|
|
may match that of the parent while still creating a new encryption root, and
|
|
that changing the
|
|
.Sy 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
|
|
.Pq namely Sy keystatus , keyformat , keylocation , No and Sy 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
|
|
.Sy encryptionroot
|
|
property.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
There are a few limitations on encrypted datasets.
|
|
Encrypted data cannot be embedded via the
|
|
.Sy embedded_data
|
|
feature.
|
|
Encrypted datasets may not have
|
|
.Sy copies Ns = Ns Em 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.
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr zfsprops 7 ,
|
|
.Xr zfs-create 8 ,
|
|
.Xr zfs-set 8
|