aboutsummaryrefslogtreecommitdiffstats
path: root/man/man8/zfs-load-key.8
blob: 7d273ddd53b01569c5b558194f70775f8d47e923 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
.\"
.\" 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 the encryption key used to access a dataset.
.Sh SYNOPSIS
.Nm zfs
.Cm load-key
.Op Fl nr
.Op Fl L Ar keylocation
.Fl a | Ar filesystem
.Nm zfs
.Cm unload-key
.Op Fl r
.Fl a | 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 | 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 Sy -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
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.
.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 | 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 into
ZFS. 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
(e.g. using
.Nm zfs Cm send
|
.Nm zfs Cm recv Ns
), and then clearing the free space with
.Nm zpool Cm trim --secure
if supported by your hardware, otherwise
.Nm zpool Cm initialize Ns .
.Bl -tag -width "-r"
.It Fl l
Ensures the key is loaded before attempting to change the key. This is
effectively equivalent to
.Qq 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 (
.Sy keyformat ,
.Sy keylocation ,
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 zvol data, file attributes, ACLs, permission bits,
directory listings, FUID mappings, and
.Sy userused
/
.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
.Nm zfs Cm load-key
subcommand for more info on key loading).
.Pp
Creating an encrypted dataset requires specifying the
.Sy encryption
and
.Sy keyformat
properties at creation time, along with an optional
.Sy keylocation
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 (namely
.Sy keystatus ,
.Sy keyformat ,
.Sy keylocation ,
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 dedup 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 per block written.
.Sh SEE ALSO
.Xr zfs-create 8 ,
.Xr zfs-set 8 ,
.Xr zfsprops 8