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.

1 files 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