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 240the 241.Cm load-key 242subcommand for more info on key loading). 243.Pp 244Creating an encrypted dataset requires specifying the 245.Sy encryption No and Sy keyformat 246properties at creation time, along with an optional 247.Sy keylocation No and Sy pbkdf2iters . 248After entering an encryption key, the 249created dataset will become an encryption root. 250Any descendant datasets will 251inherit their encryption key from the encryption root by default, meaning that 252loading, unloading, or changing the key for the encryption root will implicitly 253do the same for all inheriting datasets. 254If this inheritance is not desired, simply supply a 255.Sy keyformat 256when creating the child dataset or use 257.Nm zfs Cm change-key 258to break an existing relationship, creating a new encryption root on the child. 259Note that the child's 260.Sy keyformat 261may match that of the parent while still creating a new encryption root, and 262that changing the 263.Sy encryption 264property alone does not create a new encryption root; this would simply use a 265different cipher suite with the same key as its encryption root. 266The one exception is that clones will always use their origin's encryption key. 267As a result of this exception, some encryption-related properties 268.Pq namely Sy keystatus , keyformat , keylocation , No and Sy pbkdf2iters 269do not inherit like other ZFS properties and instead use the value determined 270by their encryption root. 271Encryption root inheritance can be tracked via the read-only 272.Sy encryptionroot 273property. 274.Pp 275Encryption changes the behavior of a few ZFS 276operations. 277Encryption is applied after compression so compression ratios are preserved. 278Normally checksums in ZFS are 256 bits long, but for encrypted data 279the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from 280the encryption suite, which provides additional protection against maliciously 281altered data. 282Deduplication is still possible with encryption enabled but for security, 283datasets will only deduplicate against themselves, their snapshots, 284and their clones. 285.Pp 286There are a few limitations on encrypted datasets. 287Encrypted data cannot be embedded via the 288.Sy embedded_data 289feature. 290Encrypted datasets may not have 291.Sy copies Ns = Ns Em 3 292since the implementation stores some encryption metadata where the third copy 293would normally be. 294Since compression is applied before encryption, datasets may 295be vulnerable to a CRIME-like attack if applications accessing the data allow 296for it. 297Deduplication with encryption will leak information about which blocks 298are equivalent in a dataset and will incur an extra CPU cost for each block 299written. 300. 301.Sh SEE ALSO 302.Xr zfsprops 7 , 303.Xr zfs-create 8 , 304.Xr zfs-set 8 305