Merge pull request #309 from ebiggers/troubleshooting

Updates to the troubleshooting documentation

1 files changed, 26 insertions, 5 deletions

diff --git a/README.md b/README.md
index 4368d91..530671a 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,7 @@ native encryption.  See [Runtime Dependencies](#runtime-dependencies).
   - [Getting "Package not installed" when trying to use an encrypted directory.](#getting-package-not-installed-when-trying-to-use-an-encrypted-directory)
   - [Some processes can't access unlocked encrypted files.](#some-processes-cant-access-unlocked-encrypted-files)
   - [Users can access other users' unlocked encrypted files.](#users-can-access-other-users-unlocked-encrypted-files)
+  - [The reported size of encrypted symlinks is wrong.](#the-reported-size-of-encrypted-symlinks-is-wrong)
 - [Legal](#legal)
 
 ## Other encryption solutions
@@ -940,7 +941,7 @@ unlocked encrypted files.  This issue can manifest in many ways, such as:
 
 * A user being unable to access encrypted files that were unlocked by root
 
-If an OS-level error is shown, it is "Required key not available".
+If an OS-level error is shown, it is `ENOKEY` ("Required key not available").
 
 To fix this issue, first run `fscrypt status $dir`, where `$dir` is your
 encrypted directory.  If the output contains `policy_version:2`, then your issue
@@ -990,10 +991,9 @@ locked), it is unlocked (or locked) for all users.  Encryption is not access
 control; the Linux kernel already has many access control mechanisms, such as
 the standard UNIX file permissions, that can be used to control access to files.
 
-Setting the mode of your encrypted directory to `0700` will prevent non-root
-users from accessing it while it is unlocked.  In `fscrypt` v0.2.5 and later,
-`fscrypt encrypt` sets this mode automatically.  This doesn't prevent root from
-accessing it; however, root has many other ways to get access to it anyway.
+Setting the mode of your encrypted directory to `0700` will prevent users other
+than the directory's owner and `root` from accessing it while it is unlocked.
+In `fscrypt` v0.2.5 and later, `fscrypt encrypt` sets this mode automatically.
 
 Having the locked/unlocked status of directories be global instead of per-user
 may seem unintuitive, but it is actually the only logical way.  The encryption
@@ -1002,12 +1002,33 @@ doesn't.  And once it has the key, any additional checks of whether particular
 users "have" the key would be OS-level access control checks (not cryptography)
 that are redundant with existing OS-level access control mechanisms.
 
+Similarly, any attempt of the filesystem encryption feature to prevent `root`
+from accessing unlocked encrypted files would be pointless.  On Linux systems,
+`root` is usually all-powerful and can always get access to files in ways that
+cannot be prevented, e.g. `setuid()` and `ptrace()`.  The only reliable way to
+limit what `root` can do is via a mandatory access control system, e.g. SELinux.
+
 The original design of Linux filesystem encryption actually did put the keys
 into per-user keyrings.  However, this caused a [massive number of
 problems](#some-processes-cant-access-unlocked-encrypted-files), as it's
 actually very common that encrypted files need to be accessed by processes
 running under different user IDs -- even if it may not be immediately apparent.
 
+#### The reported size of encrypted symlinks is wrong.
+
+Traditionally, filesystems didn't conform to POSIX when reporting the size of
+encrypted symlinks, as they gave the size of the ciphertext symlink target
+rather than the size of the plaintext target.  This would make the reported size
+of symlinks appear to be slightly too large when queried using ``lstat()`` or
+similar system calls.  Most programs don't care about this, but in rare cases
+programs can depend on the filesystem reporting symlink sizes correctly.
+
+This bug has been fixed in Linux kernel v5.15 and later.  Now, filesystems
+always report the correct symlink size.
+
+If the kernel can't be upgraded, the only workaround for this bug is to update
+any affected programs to not depend on symlink sizes being reported correctly.
+
 ## Legal
 
 Copyright 2017 Google Inc. under the