From fe2939cc7e50f4c6025253efdf7380c04fac9ae1 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 15 Dec 2019 19:31:39 -0800 Subject: README.md: document new settings and troubleshooting key access Document the new /etc/fscrypt.conf settings for the filesystem keyring and v2 encryption policies, and add a new subsection for troubleshooting key access problems. --- README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4130962..b815807 100644 --- a/README.md +++ b/README.md @@ -194,8 +194,10 @@ that looks like the following: "options": { "padding": "32", "contents": "AES_256_XTS", - "filenames": "AES_256_CTS" - } + "filenames": "AES_256_CTS", + "policy_version": "1" + }, + "use_fs_keyring_for_v1_policies": false } ``` @@ -237,6 +239,25 @@ The fields are: documentation](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html#encryption-modes-and-usage) 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. + +* "use\_fs\_keyring\_for\_v1\_policies" specifies whether to add keys + for v1 encryption policies to the filesystem keyring, rather than to + user keyrings. This can solve [issues with processes being unable + to access encrypted files](#cant-log-in-with-ssh-even-when-users-encrypted-home-directory-is-unlocked). + However, it requires kernel v5.4 or later, and it makes unlocking + and locking encrypted directories require root. + + The purpose of this setting is to allow people to take advantage of + some of the improvements in Linux v5.4 on encrypted directories that + are also compatible with older kernels. If you don't need + compatibility with older kernels, it's better to not use this + setting and instead (re-)create your encrypted directories with + `"policy_version": "2"`. + ### Setting up the PAM module Note that to make use of the installed PAM module, your @@ -716,6 +737,37 @@ shred -u file However, `shred` isn't guaranteed to be effective on all filesystems and storage devices. +#### Can't log in with ssh even when user's encrypted home directory is unlocked + +This is caused by a limitation in the original design of Linux +filesystem encryption which made it difficult to ensure that all +processes can access unlocked encrypted files. This issue can also +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`: + + "use_fs_keyring_for_v1_policies": true + +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`. + +Alternatively, you can upgrade your encrypted directories to use v2 +encryption policies by setting the following in the "options" section +of `/etc/fscrypt.conf`: + + "policy_version": "2" + +... 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. + ## Legal Copyright 2017 Google Inc. under the -- cgit v1.2.3