From 16bfa32bd6f92d0afbd50745df2ae47d7cd61e80 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Tue, 17 Mar 2020 21:10:58 -0700 Subject: [PATCH] README.md: update v2 policy-related documentation - Mention that a v5.4+ kernel is recommended. - Mention that policy_version defaults to 1 when unset. - Emphasize that v2 policies are the recommended solution to the key visibility problems, and add some more information. --- README.md | 61 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index e81bb62f..f465451f 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,10 @@ To check whether the needed option is enabled in your kernel, run: zgrep -h ENCRYPTION /proc/config.gz /boot/config-$(uname -r) | sort | uniq ``` +It is also recommended for the kernel to be v5.4 or later, since this +allows the use of v2 encryption policies. v2 policies have several +security and usability improvements over v1 policies. + Be careful when using encryption on removable media, since filesystems with the `encrypt` feature cannot be mounted on systems with kernel versions older than the minimums listed above -- even to access unencrypted files! @@ -241,9 +245,10 @@ The fields are: for more details about the supported algorithms. * "policy\_version" is the version of encryption policy to use. - The choices are "1" and "2". Directories created with policy - version "2" are only usable on kernel v5.4 or later, but are - preferable to version "1" if you don't mind this restriction. + The choices are "1" and "2". If unset, "1" is assumed. + Directories created with policy version "2" are only usable on + kernel v5.4 or later, but are preferable to version "1" if you + don't mind this restriction. * "use\_fs\_keyring\_for\_v1\_policies" specifies whether to add keys for v1 encryption policies to the filesystem keyring, rather than to @@ -746,27 +751,45 @@ manifest in other ways such as Docker containers being unable to access encrypted files, or NetworkManager being unable to access certificates if they are located in an encrypted directory. -If you are using kernel v5.4 or later, you can fix this by setting the -following in `/etc/fscrypt.conf`: +The recommended way to fix this is by creating your encrypted +directories using v2 encryption policies rather than v1. This +requires Linux v5.4 or later and `fscrypt` v0.2.6 or later. If these +prerequisites are met, to enable v2 policies on new directories set +`"policy_version": "2"` in `/etc/fscrypt.conf`. For example: - "use_fs_keyring_for_v1_policies": true +``` + "options": { + "padding": "32", + "contents": "AES_256_XTS", + "filenames": "AES_256_CTS", + "policy_version": "2" + }, +``` + +This only affects new directories. If you want to upgrade an existing +encrypted directory to use a v2 policy, you'll need to re-create it by +using `fscrypt encrypt` to encrypt a new empty directory, copying your +files into it, and replacing the original directory with it. -However, this makes manually unlocking and locking encrypted -directories start to require root. (The PAM module will still work.) -E.g., you'll need to run `sudo fscrypt unlock`, not `fscrypt unlock`. +In `fscrypt` v0.2.7 and later, the `fscrypt setup` command +automatically sets `"policy_version": "2"` when creating +`/etc/fscrypt.conf` if kernel support is present. -Alternatively, you can upgrade your encrypted directories to use v2 -encryption policies by setting the following in the "options" section -of `/etc/fscrypt.conf`: +__IMPORTANT:__ directories that use v2 encryption policies are +unusable on Linux v5.3 and earlier. If this will be a problem for you +(for example, if your encrypted directories are on removable storage +that needs to work on computers with both old and new kernels), you'll +need to use v1 policies instead. In this case, or if you simply don't +want to re-create your encrypted directories, there's also a fallback +option to make `fscrypt` use the filesystem keyring for v1 policies +whenever the kernel supports it: - "policy_version": "2" + "use_fs_keyring_for_v1_policies": true -... and then for each of your encrypted directories, using `fscrypt -encrypt` to encrypt a new empty directory, copying your files into it, -and replacing the original directory with it. This will fix the key -access problems, while also keeping `fscrypt unlock` and `fscrypt -lock` usable by non-root users. This is the recommended solution if -you don't need to access your files on kernels older than v5.4. +However, this fallback option makes manually unlocking and locking +encrypted directories start to require root. (The PAM module will +still work.) E.g., you'll need to run `sudo fscrypt unlock`, not +`fscrypt unlock`. Most people should just use v2 policies instead. ## Legal