man/man8/zfs-load-key.8

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