| blob | f68d6e985a78dc18eec21c0c1bcb809785fadb65 |
1 .\"
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or https://opensource.org/licenses/CDDL-1.0.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
22 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
23 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
24 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
25 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
26 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
27 .\" Copyright (c) 2014 Integros [integros.com]
28 .\" Copyright 2019 Richard Laager. All rights reserved.
29 .\" Copyright 2018 Nexenta Systems, Inc.
30 .\" Copyright 2019 Joyent, Inc.
31 .\"
32 .Dd January 13, 2020
33 .Dt ZFS-LOAD-KEY 8
34 .Os
35 .
36 .Sh NAME
37 .Nm zfs-load-key
38 .Nd load, unload, or change encryption key of ZFS dataset
39 .Sh SYNOPSIS
40 .Nm zfs
41 .Cm load-key
42 .Op Fl nr
43 .Op Fl L Ar keylocation
44 .Fl a Ns | Ns Ar filesystem
45 .Nm zfs
46 .Cm unload-key
47 .Op Fl r
48 .Fl a Ns | Ns Ar filesystem
49 .Nm zfs
50 .Cm change-key
51 .Op Fl l
52 .Op Fl o Ar keylocation Ns = Ns Ar value
53 .Op Fl o Ar keyformat Ns = Ns Ar value
54 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
55 .Ar filesystem
56 .Nm zfs
57 .Cm change-key
58 .Fl i
59 .Op Fl l
60 .Ar filesystem
61 .
62 .Sh DESCRIPTION
63 .Bl -tag -width ""
64 .It Xo
65 .Nm zfs
66 .Cm load-key
67 .Op Fl nr
68 .Op Fl L Ar keylocation
69 .Fl a Ns | Ns Ar filesystem
70 .Xc
71 Load the key for
72 .Ar filesystem ,
73 allowing it and all children that inherit the
74 .Sy keylocation
75 property to be accessed.
76 The key will be expected in the format specified by the
77 .Sy keyformat
78 and location specified by the
79 .Sy keylocation
80 property.
81 Note that if the
82 .Sy keylocation
83 is set to
84 .Sy prompt
85 the terminal will interactively wait for the key to be entered.
86 Loading a key will not automatically mount the dataset.
87 If that functionality is desired,
88 .Nm zfs Cm mount Fl l
89 will ask for the key and mount the dataset
90 .Po
91 see
92 .Xr zfs-mount 8
93 .Pc .
94 Once the key is loaded the
95 .Sy keystatus
96 property will become
97 .Sy available .
98 .Bl -tag -width "-r"
99 .It Fl r
100 Recursively loads the keys for the specified filesystem and all descendent
101 encryption roots.
102 .It Fl a
103 Loads the keys for all encryption roots in all imported pools.
104 .It Fl n
105 Do a dry-run
106 .Pq Qq No-op
107 .Cm load-key .
108 This will cause
109 .Nm zfs
110 to simply check that the provided key is correct.
111 This command may be run even if the key is already loaded.
112 .It Fl L Ar keylocation
113 Use
114 .Ar keylocation
115 instead of the
116 .Sy keylocation
117 property.
118 This will not change the value of the property on the dataset.
119 Note that if used with either
120 .Fl r
121 or
122 .Fl a ,
123 .Ar keylocation
124 may only be given as
125 .Sy prompt .
126 .El
127 .It Xo
128 .Nm zfs
129 .Cm unload-key
130 .Op Fl r
131 .Fl a Ns | Ns Ar filesystem
132 .Xc
133 Unloads a key from ZFS, removing the ability to access the dataset and all of
134 its children that inherit the
135 .Sy keylocation
136 property.
137 This requires that the dataset is not currently open or mounted.
138 Once the key is unloaded the
139 .Sy keystatus
140 property will become
141 .Sy unavailable .
142 .Bl -tag -width "-r"
143 .It Fl r
144 Recursively unloads the keys for the specified filesystem and all descendent
145 encryption roots.
146 .It Fl a
147 Unloads the keys for all encryption roots in all imported pools.
148 .El
149 .It Xo
150 .Nm zfs
151 .Cm change-key
152 .Op Fl l
153 .Op Fl o Ar keylocation Ns = Ns Ar value
154 .Op Fl o Ar keyformat Ns = Ns Ar value
155 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
156 .Ar filesystem
157 .Xc
158 .It Xo
159 .Nm zfs
160 .Cm change-key
161 .Fl i
162 .Op Fl l
163 .Ar filesystem
164 .Xc
165 Changes the user's key (e.g. a passphrase) used to access a dataset.
166 This command requires that the existing key for the dataset is already loaded.
167 This command may also be used to change the
168 .Sy keylocation ,
169 .Sy keyformat ,
170 and
171 .Sy pbkdf2iters
172 properties as needed.
173 If the dataset was not previously an encryption root it will become one.
174 Alternatively, the
175 .Fl i
176 flag may be provided to cause an encryption root to inherit the parent's key
177 instead.
178 .Pp
179 If the user's key is compromised,
180 .Nm zfs Cm change-key
181 does not necessarily protect existing or newly-written data from attack.
182 Newly-written data will continue to be encrypted with the same master key as
183 the existing data.
184 The master key is compromised if an attacker obtains a
185 user key and the corresponding wrapped master key.
186 Currently,
187 .Nm zfs Cm change-key
188 does not overwrite the previous wrapped master key on disk, so it is
189 accessible via forensic analysis for an indeterminate length of time.
190 .Pp
191 In the event of a master key compromise, ideally the drives should be securely
192 erased to remove all the old data (which is readable using the compromised
193 master key), a new pool created, and the data copied back.
194 This can be approximated in place by creating new datasets, copying the data
195 .Pq e.g. using Nm zfs Cm send | Nm zfs Cm recv ,
196 and then clearing the free space with
197 .Nm zpool Cm trim Fl -secure
198 if supported by your hardware, otherwise
199 .Nm zpool Cm initialize .
200 .Bl -tag -width "-r"
201 .It Fl l
202 Ensures the key is loaded before attempting to change the key.
203 This is effectively equivalent to running
204 .Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
205 .It Fl o Ar property Ns = Ns Ar value
206 Allows the user to set encryption key properties
207 .Pq Sy keyformat , keylocation , No and Sy pbkdf2iters
208 while changing the key.
209 This is the only way to alter
210 .Sy keyformat
211 and
212 .Sy pbkdf2iters
213 after the dataset has been created.
214 .It Fl i
215 Indicates that zfs should make
216 .Ar filesystem
217 inherit the key of its parent.
218 Note that this command can only be run on an encryption root
219 that has an encrypted parent.
220 .El
221 .El
222 .Ss Encryption
223 Enabling the
224 .Sy encryption
225 feature allows for the creation of encrypted filesystems and volumes.
226 ZFS will encrypt file and volume data, file attributes, ACLs, permission bits,
227 directory listings, FUID mappings, and
228 .Sy userused Ns / Ns Sy groupused
229 data.
230 ZFS will not encrypt metadata related to the pool structure, including
231 dataset and snapshot names, dataset hierarchy, properties, file size, file
232 holes, and deduplication tables (though the deduplicated data itself is
233 encrypted).
234 .Pp
235 Key rotation is managed by ZFS.
236 Changing the user's key (e.g. a passphrase)
237 does not require re-encrypting the entire dataset.
238 Datasets can be scrubbed,
239 resilvered, renamed, and deleted without the encryption keys being loaded (see
240 the
241 .Cm load-key
242 subcommand for more info on key loading).
243 .Pp
244 Creating an encrypted dataset requires specifying the
245 .Sy encryption No and Sy keyformat
246 properties at creation time, along with an optional
247 .Sy keylocation No and Sy pbkdf2iters .
248 After entering an encryption key, the
249 created dataset will become an encryption root.
250 Any descendant datasets will
251 inherit their encryption key from the encryption root by default, meaning that
252 loading, unloading, or changing the key for the encryption root will implicitly
253 do the same for all inheriting datasets.
254 If this inheritance is not desired, simply supply a
255 .Sy keyformat
256 when creating the child dataset or use
257 .Nm zfs Cm change-key
258 to break an existing relationship, creating a new encryption root on the child.
259 Note that the child's
260 .Sy keyformat
261 may match that of the parent while still creating a new encryption root, and
262 that changing the
263 .Sy encryption
264 property alone does not create a new encryption root; this would simply use a
265 different cipher suite with the same key as its encryption root.
266 The one exception is that clones will always use their origin's encryption key.
267 As a result of this exception, some encryption-related properties
268 .Pq namely Sy keystatus , keyformat , keylocation , No and Sy pbkdf2iters
269 do not inherit like other ZFS properties and instead use the value determined
270 by their encryption root.
271 Encryption root inheritance can be tracked via the read-only
272 .Sy encryptionroot
273 property.
274 .Pp
275 Encryption changes the behavior of a few ZFS
276 operations.
277 Encryption is applied after compression so compression ratios are preserved.
278 Normally checksums in ZFS are 256 bits long, but for encrypted data
279 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
280 the encryption suite, which provides additional protection against maliciously
281 altered data.
282 Deduplication is still possible with encryption enabled but for security,
283 datasets will only deduplicate against themselves, their snapshots,
284 and their clones.
285 .Pp
286 There are a few limitations on encrypted datasets.
287 Encrypted data cannot be embedded via the
288 .Sy embedded_data
289 feature.
290 Encrypted datasets may not have
291 .Sy copies Ns = Ns Em 3
292 since the implementation stores some encryption metadata where the third copy
293 would normally be.
294 Since compression is applied before encryption, datasets may
295 be vulnerable to a CRIME-like attack if applications accessing the data allow
296 for it.
297 Deduplication with encryption will leak information about which blocks
298 are equivalent in a dataset and will incur an extra CPU cost for each block
299 written.
300 .
301 .Sh SEE ALSO
302 .Xr zfsprops 7 ,
303 .Xr zfs-create 8 ,
304 .Xr zfs-set 8