From 2b127afb44d11bfddaf8ed95be18c7aefe7ea5de Mon Sep 17 00:00:00 2001 From: Richard Laager Date: Wed, 24 Apr 2019 19:14:25 -0500 Subject: [PATCH] Clarify and improve encryption documentation - Remove the language that "all user data" is encrypted. This is to avoid misunderstandings or arguments about what is "user data", especially in light of "user properties". - Document that properties are unencrypted. - Document that snapshot names are unencrypted. - For consistency with the rest of the zfs.8 man page, use "ZFS" as the generic noun, not (bolded) "zfs". The latter refers to the command. Likewise, use "ZFS" instead of "the kernel module". - Give "a passphrase" as an example of a "user's key". Reviewed-by: Tom Caputi Reviewed-by: Brian Behlendorf Reviewed-by: George Melikov Signed-off-by: Richard Laager Closes #8652 --- man/man8/zfs.8 | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index a8e859bdc..3b118ac3e 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -2380,17 +2380,19 @@ configuration is not supported. .Ss Encryption Enabling the .Sy encryption -feature allows for the creation of encrypted filesystems and volumes. -.Nm -will encrypt all user data including file and zvol data, file attributes, -ACLs, permission bits, directory listings, FUID mappings, and userused / -groupused data. -.Nm -will not encrypt metadata related to the pool structure, including dataset -names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation -is managed internally by the kernel module and changing the user's key does not -require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered, -renamed, and deleted without the encryption keys being loaded (see the +feature allows for the creation of encrypted filesystems and volumes. ZFS +will encrypt file and zvol data, file attributes, ACLs, permission bits, +directory listings, FUID mappings, and +.Sy userused +/ +.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. +.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 .Nm zfs Cm load-key subcommand for more info on key loading). .Pp @@ -2432,8 +2434,7 @@ read-only .Sy encryptionroot property. .Pp -Encryption changes the behavior of a few -.Nm +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 -- 2.39.5