| .\" |
| .\" CDDL HEADER START |
| .\" |
| .\" The contents of this file are subject to the terms of the |
| .\" Common Development and Distribution License (the "License"). |
| .\" You may not use this file except in compliance with the License. |
| .\" |
| .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE |
| .\" or http://www.opensolaris.org/os/licensing. |
| .\" See the License for the specific language governing permissions |
| .\" and limitations under the License. |
| .\" |
| .\" When distributing Covered Code, include this CDDL HEADER in each |
| .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. |
| .\" If applicable, add the following below this CDDL HEADER, with the |
| .\" fields enclosed by brackets "[]" replaced with your own identifying |
| .\" information: Portions Copyright [yyyy] [name of copyright owner] |
| .\" |
| .\" CDDL HEADER END |
| .\" |
| .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. |
| .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org> |
| .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. |
| .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. |
| .\" Copyright (c) 2014, Joyent, Inc. All rights reserved. |
| .\" Copyright (c) 2014 by Adam Stevko. All rights reserved. |
| .\" Copyright (c) 2014 Integros [integros.com] |
| .\" Copyright 2019 Richard Laager. All rights reserved. |
| .\" Copyright 2018 Nexenta Systems, Inc. |
| .\" Copyright 2019 Joyent, Inc. |
| .\" |
| .Dd January 13, 2020 |
| .Dt ZFS-LOAD-KEY 8 |
| .Os |
| . |
| .Sh NAME |
| .Nm zfs-load-key |
| .Nd load, unload, or change encryption key of ZFS dataset |
| .Sh SYNOPSIS |
| .Nm zfs |
| .Cm load-key |
| .Op Fl nr |
| .Op Fl L Ar keylocation |
| .Fl a Ns | Ns Ar filesystem |
| .Nm zfs |
| .Cm unload-key |
| .Op Fl r |
| .Fl a Ns | Ns Ar filesystem |
| .Nm zfs |
| .Cm change-key |
| .Op Fl l |
| .Op Fl o Ar keylocation Ns = Ns Ar value |
| .Op Fl o Ar keyformat Ns = Ns Ar value |
| .Op Fl o Ar pbkdf2iters Ns = Ns Ar value |
| .Ar filesystem |
| .Nm zfs |
| .Cm change-key |
| .Fl i |
| .Op Fl l |
| .Ar filesystem |
| . |
| .Sh DESCRIPTION |
| .Bl -tag -width "" |
| .It Xo |
| .Nm zfs |
| .Cm load-key |
| .Op Fl nr |
| .Op Fl L Ar keylocation |
| .Fl a Ns | Ns Ar filesystem |
| .Xc |
| Load the key for |
| .Ar filesystem , |
| allowing it and all children that inherit the |
| .Sy keylocation |
| property to be accessed. |
| The key will be expected in the format specified by the |
| .Sy keyformat |
| and location specified by the |
| .Sy keylocation |
| property. |
| Note that if the |
| .Sy keylocation |
| is set to |
| .Sy prompt |
| the terminal will interactively wait for the key to be entered. |
| Loading a key will not automatically mount the dataset. |
| If that functionality is desired, |
| .Nm zfs Cm mount Fl l |
| will ask for the key and mount the dataset |
| .Po |
| see |
| .Xr zfs-mount 8 |
| .Pc . |
| Once the key is loaded the |
| .Sy keystatus |
| property will become |
| .Sy available . |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively loads the keys for the specified filesystem and all descendent |
| encryption roots. |
| .It Fl a |
| Loads the keys for all encryption roots in all imported pools. |
| .It Fl n |
| Do a dry-run |
| .Pq Qq No-op |
| .Cm load-key . |
| This will cause |
| .Nm zfs |
| to simply check that the provided key is correct. |
| This command may be run even if the key is already loaded. |
| .It Fl L Ar keylocation |
| Use |
| .Ar keylocation |
| instead of the |
| .Sy keylocation |
| property. |
| This will not change the value of the property on the dataset. |
| Note that if used with either |
| .Fl r |
| or |
| .Fl a , |
| .Ar keylocation |
| may only be given as |
| .Sy prompt . |
| .El |
| .It Xo |
| .Nm zfs |
| .Cm unload-key |
| .Op Fl r |
| .Fl a Ns | Ns Ar filesystem |
| .Xc |
| Unloads a key from ZFS, removing the ability to access the dataset and all of |
| its children that inherit the |
| .Sy keylocation |
| property. |
| This requires that the dataset is not currently open or mounted. |
| Once the key is unloaded the |
| .Sy keystatus |
| property will become |
| .Sy unavailable . |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively unloads the keys for the specified filesystem and all descendent |
| encryption roots. |
| .It Fl a |
| Unloads the keys for all encryption roots in all imported pools. |
| .El |
| .It Xo |
| .Nm zfs |
| .Cm change-key |
| .Op Fl l |
| .Op Fl o Ar keylocation Ns = Ns Ar value |
| .Op Fl o Ar keyformat Ns = Ns Ar value |
| .Op Fl o Ar pbkdf2iters Ns = Ns Ar value |
| .Ar filesystem |
| .Xc |
| .It Xo |
| .Nm zfs |
| .Cm change-key |
| .Fl i |
| .Op Fl l |
| .Ar filesystem |
| .Xc |
| Changes the user's key (e.g. a passphrase) used to access a dataset. |
| This command requires that the existing key for the dataset is already loaded. |
| This command may also be used to change the |
| .Sy keylocation , |
| .Sy keyformat , |
| and |
| .Sy pbkdf2iters |
| properties as needed. |
| If the dataset was not previously an encryption root it will become one. |
| Alternatively, the |
| .Fl i |
| flag may be provided to cause an encryption root to inherit the parent's key |
| instead. |
| .Pp |
| If the user's key is compromised, |
| .Nm zfs Cm change-key |
| does not necessarily protect existing or newly-written data from attack. |
| Newly-written data will continue to be encrypted with the same master key as |
| the existing data. |
| The master key is compromised if an attacker obtains a |
| user key and the corresponding wrapped master key. |
| Currently, |
| .Nm zfs Cm change-key |
| does not overwrite the previous wrapped master key on disk, so it is |
| accessible via forensic analysis for an indeterminate length of time. |
| .Pp |
| In the event of a master key compromise, ideally the drives should be securely |
| erased to remove all the old data (which is readable using the compromised |
| master key), a new pool created, and the data copied back. |
| This can be approximated in place by creating new datasets, copying the data |
| .Pq e.g. using Nm zfs Cm send | Nm zfs Cm recv , |
| and then clearing the free space with |
| .Nm zpool Cm trim Fl -secure |
| if supported by your hardware, otherwise |
| .Nm zpool Cm initialize . |
| .Bl -tag -width "-r" |
| .It Fl l |
| Ensures the key is loaded before attempting to change the key. |
| This is effectively equivalent to running |
| .Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem |
| .It Fl o Ar property Ns = Ns Ar value |
| Allows the user to set encryption key properties |
| .Pq Sy keyformat , keylocation , No and Sy pbkdf2iters |
| while changing the key. |
| This is the only way to alter |
| .Sy keyformat |
| and |
| .Sy pbkdf2iters |
| after the dataset has been created. |
| .It Fl i |
| Indicates that zfs should make |
| .Ar filesystem |
| inherit the key of its parent. |
| Note that this command can only be run on an encryption root |
| that has an encrypted parent. |
| .El |
| .El |
| .Ss Encryption |
| Enabling the |
| .Sy encryption |
| feature allows for the creation of encrypted filesystems and volumes. |
| ZFS will encrypt file and volume data, file attributes, ACLs, permission bits, |
| directory listings, FUID mappings, and |
| .Sy userused Ns / Ns Sy groupused |
| data. |
| ZFS will not encrypt metadata related to the pool structure, including |
| dataset and snapshot names, dataset hierarchy, properties, file size, file |
| holes, and deduplication tables (though the deduplicated data itself is |
| encrypted). |
| .Pp |
| Key rotation is managed by ZFS. |
| Changing the user's key (e.g. a passphrase) |
| does not require re-encrypting the entire dataset. |
| Datasets can be scrubbed, |
| resilvered, renamed, and deleted without the encryption keys being loaded (see the |
| .Cm load-key |
| subcommand for more info on key loading). |
| .Pp |
| Creating an encrypted dataset requires specifying the |
| .Sy encryption No and Sy keyformat |
| properties at creation time, along with an optional |
| .Sy keylocation No and Sy pbkdf2iters . |
| After entering an encryption key, the |
| created dataset will become an encryption root. |
| Any descendant datasets will |
| inherit their encryption key from the encryption root by default, meaning that |
| loading, unloading, or changing the key for the encryption root will implicitly |
| do the same for all inheriting datasets. |
| If this inheritance is not desired, simply supply a |
| .Sy keyformat |
| when creating the child dataset or use |
| .Nm zfs Cm change-key |
| to break an existing relationship, creating a new encryption root on the child. |
| Note that the child's |
| .Sy keyformat |
| may match that of the parent while still creating a new encryption root, and |
| that changing the |
| .Sy encryption |
| property alone does not create a new encryption root; this would simply use a |
| different cipher suite with the same key as its encryption root. |
| The one exception is that clones will always use their origin's encryption key. |
| As a result of this exception, some encryption-related properties |
| .Pq namely Sy keystatus , keyformat , keylocation , No and Sy pbkdf2iters |
| do not inherit like other ZFS properties and instead use the value determined |
| by their encryption root. |
| Encryption root inheritance can be tracked via the read-only |
| .Sy encryptionroot |
| property. |
| .Pp |
| Encryption changes the behavior of a few ZFS |
| operations. |
| Encryption is applied after compression so compression ratios are preserved. |
| Normally checksums in ZFS are 256 bits long, but for encrypted data |
| the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from |
| the encryption suite, which provides additional protection against maliciously |
| altered data. |
| Deduplication is still possible with encryption enabled but for security, |
| datasets will only deduplicate against themselves, their snapshots, |
| and their clones. |
| .Pp |
| There are a few limitations on encrypted datasets. |
| Encrypted data cannot be embedded via the |
| .Sy embedded_data |
| feature. |
| Encrypted datasets may not have |
| .Sy copies Ns = Ns Em 3 |
| since the implementation stores some encryption metadata where the third copy |
| would normally be. |
| Since compression is applied before encryption, datasets may |
| be vulnerable to a CRIME-like attack if applications accessing the data allow for it. |
| Deduplication with encryption will leak information about which blocks |
| are equivalent in a dataset and will incur an extra CPU cost for each block written. |
| . |
| .Sh SEE ALSO |
| .Xr zfsprops 7 , |
| .Xr zfs-create 8 , |
| .Xr zfs-set 8 |