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