logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zfs-unload-key.8 (9556B)


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