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 71Load the key for 72.Ar filesystem , 73allowing it and all children that inherit the 74.Sy keylocation 75property to be accessed. 76The key will be expected in the format specified by the 77.Sy keyformat 78and location specified by the 79.Sy keylocation 80property. 81Note that if the 82.Sy keylocation 83is set to 84.Sy prompt 85the terminal will interactively wait for the key to be entered. 86Loading a key will not automatically mount the dataset. 87If that functionality is desired, 88.Nm zfs Cm mount Fl l 89will ask for the key and mount the dataset 90.Po 91see 92.Xr zfs-mount 8 93.Pc . 94Once the key is loaded the 95.Sy keystatus 96property will become 97.Sy available . 98.Bl -tag -width "-r" 99.It Fl r 100Recursively loads the keys for the specified filesystem and all descendent 101encryption roots. 102.It Fl a 103Loads the keys for all encryption roots in all imported pools. 104.It Fl n 105Do a dry-run 106.Pq Qq No-op 107.Cm load-key . 108This will cause 109.Nm zfs 110to simply check that the provided key is correct. 111This command may be run even if the key is already loaded. 112.It Fl L Ar keylocation 113Use 114.Ar keylocation 115instead of the 116.Sy keylocation 117property. 118This will not change the value of the property on the dataset. 119Note that if used with either 120.Fl r 121or 122.Fl a , 123.Ar keylocation 124may 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 133Unloads a key from ZFS, removing the ability to access the dataset and all of 134its children that inherit the 135.Sy keylocation 136property. 137This requires that the dataset is not currently open or mounted. 138Once the key is unloaded the 139.Sy keystatus 140property will become 141.Sy unavailable . 142.Bl -tag -width "-r" 143.It Fl r 144Recursively unloads the keys for the specified filesystem and all descendent 145encryption roots. 146.It Fl a 147Unloads 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 165Changes the user's key (e.g. a passphrase) used to access a dataset. 166This command requires that the existing key for the dataset is already loaded. 167This command may also be used to change the 168.Sy keylocation , 169.Sy keyformat , 170and 171.Sy pbkdf2iters 172properties as needed. 173If the dataset was not previously an encryption root it will become one. 174Alternatively, the 175.Fl i 176flag may be provided to cause an encryption root to inherit the parent's key 177instead. 178.Pp 179If the user's key is compromised, 180.Nm zfs Cm change-key 181does not necessarily protect existing or newly-written data from attack. 182Newly-written data will continue to be encrypted with the same master key as 183the existing data. 184The master key is compromised if an attacker obtains a 185user key and the corresponding wrapped master key. 186Currently, 187.Nm zfs Cm change-key 188does not overwrite the previous wrapped master key on disk, so it is 189accessible via forensic analysis for an indeterminate length of time. 190.Pp 191In the event of a master key compromise, ideally the drives should be securely 192erased to remove all the old data (which is readable using the compromised 193master key), a new pool created, and the data copied back. 194This 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 , 196and then clearing the free space with 197.Nm zpool Cm trim Fl -secure 198if supported by your hardware, otherwise 199.Nm zpool Cm initialize . 200.Bl -tag -width "-r" 201.It Fl l 202Ensures the key is loaded before attempting to change the key. 203This 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 206Allows the user to set encryption key properties 207.Pq Sy keyformat , keylocation , No and Sy pbkdf2iters 208while changing the key. 209This is the only way to alter 210.Sy keyformat 211and 212.Sy pbkdf2iters 213after the dataset has been created. 214.It Fl i 215Indicates that zfs should make 216.Ar filesystem 217inherit the key of its parent. 218Note that this command can only be run on an encryption root 219that has an encrypted parent. 220.El 221.El 222.Ss Encryption 223Enabling the 224.Sy encryption 225feature allows for the creation of encrypted filesystems and volumes. 226ZFS will encrypt file and volume data, file attributes, ACLs, permission bits, 227directory listings, FUID mappings, and 228.Sy userused Ns / Ns Sy groupused 229data. 230ZFS will not encrypt metadata related to the pool structure, including 231dataset and snapshot names, dataset hierarchy, properties, file size, file 232holes, and deduplication tables (though the deduplicated data itself is 233encrypted). 234.Pp 235Key rotation is managed by ZFS. 236Changing the user's key (e.g. a passphrase) 237does not require re-encrypting the entire dataset. 238Datasets can be scrubbed, 239resilvered, renamed, and deleted without the encryption keys being loaded (see the 240.Cm load-key 241subcommand for more info on key loading). 242.Pp 243Creating an encrypted dataset requires specifying the 244.Sy encryption No and Sy keyformat 245properties at creation time, along with an optional 246.Sy keylocation No and Sy pbkdf2iters . 247After entering an encryption key, the 248created dataset will become an encryption root. 249Any descendant datasets will 250inherit their encryption key from the encryption root by default, meaning that 251loading, unloading, or changing the key for the encryption root will implicitly 252do the same for all inheriting datasets. 253If this inheritance is not desired, simply supply a 254.Sy keyformat 255when creating the child dataset or use 256.Nm zfs Cm change-key 257to break an existing relationship, creating a new encryption root on the child. 258Note that the child's 259.Sy keyformat 260may match that of the parent while still creating a new encryption root, and 261that changing the 262.Sy encryption 263property alone does not create a new encryption root; this would simply use a 264different cipher suite with the same key as its encryption root. 265The one exception is that clones will always use their origin's encryption key. 266As a result of this exception, some encryption-related properties 267.Pq namely Sy keystatus , keyformat , keylocation , No and Sy pbkdf2iters 268do not inherit like other ZFS properties and instead use the value determined 269by their encryption root. 270Encryption root inheritance can be tracked via the read-only 271.Sy encryptionroot 272property. 273.Pp 274Encryption changes the behavior of a few ZFS 275operations. 276Encryption is applied after compression so compression ratios are preserved. 277Normally checksums in ZFS are 256 bits long, but for encrypted data 278the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from 279the encryption suite, which provides additional protection against maliciously 280altered data. 281Deduplication is still possible with encryption enabled but for security, 282datasets will only deduplicate against themselves, their snapshots, 283and their clones. 284.Pp 285There are a few limitations on encrypted datasets. 286Encrypted data cannot be embedded via the 287.Sy embedded_data 288feature. 289Encrypted datasets may not have 290.Sy copies Ns = Ns Em 3 291since the implementation stores some encryption metadata where the third copy 292would normally be. 293Since compression is applied before encryption, datasets may 294be vulnerable to a CRIME-like attack if applications accessing the data allow for it. 295Deduplication with encryption will leak information about which blocks 296are equivalent in a dataset and will incur an extra CPU cost for each block written. 297. 298.Sh SEE ALSO 299.Xr zfsprops 7 , 300.Xr zfs-create 8 , 301.Xr zfs-set 8 302