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