All pam_fscrypt configuration guides that I'm aware of say to use the "lock_policies" option for the pam_fscrypt.so session hook. The Debian/Ubuntu pam-config-framework config file has it too. Make locking the default behavior, since this is what everyone wants. Existing configuration files that contain the "lock_policies" option will continue to work, but that option won't do anything anymore. (We could add an option "unlock_only" to restore the old default behavior, but it's not clear that it would be useful. So for simplicity, leave it out for now.)
Configuring whether pam_fscrypt drops caches or not isn't really something the user should have to do, and it's also irrelevant for v2 encryption policies (the default on newer systems). It's better to have pam_fscrypt automatically decide whether it needs to drop caches or not. Do this by making pam_fscrypt check whether any encryption policy keys are being removed from a user keyring (rather than from a filesystem keyring). If so, it drops caches; otherwise it doesn't. This supersedes the "drop_caches" option, which won't do anything anymore.
Services launched by systemd user sessions on Debian / Ubuntu systems are often not able to access the home directory, because there is no guarantee / requirement that pam_fscrypt is sequenced before pam_systemd. Although this pam-config mechanism is Debian-specific, the config file is provided here upstream and unmodified in Debian. Raising the priority here so that it's always ordered ahead of pam_systemd will solve issues such as https://github.com/google/fscrypt/issues/270, https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=964951 and https://bugs.launchpad.net/ubuntu/+source/systemd/+bug/1889416. After a survey of pam-config files available in Debian bullseye, the value of 100 was chosen as it appears after most other plugins that could be involved in more explicit homedir configuration (eg pam_mount at 128) but before those which seem unlikely to work without a home directory (eg pam_ssh at 64).
Allow overriding the mountpoint where login protectors are stored by setting the FSCRYPT_ROOT_MNT environmental variable. The CLI tests need this to avoid touching the real "/".
Allow root to provide the --all-users option to 'fscrypt lock' to force an encryption key to be removed from the filesystem (i.e., force an encrypted directory to be locked), even if other users have added it. To implement this option, we just need to use the FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl rather than FS_IOC_REMOVE_ENCRYPTION_KEY. In theory this option could be implemented for the user keyrings case too, but it would be difficult and the user keyrings are being deprecated for fscrypt, so don't bother.
Implement adding/removing v2 encryption policy keys to/from the kernel. The kernel requires that the new ioctls FS_IOC_ADD_ENCRYPTION_KEY and FS_IOC_REMOVE_ENCRYPTION_KEY be used for this. Root is not required. However, non-root support brings an extra complication: the kernel keeps track of which users have called FS_IOC_ADD_ENCRYPTION_KEY for the same key. FS_IOC_REMOVE_ENCRYPTION_KEY only works as one of these users, and it only removes the calling user's claim to the key; the key is only truly removed when the last claim is removed. Implement the following behavior: - 'fscrypt unlock' and pam_fscrypt add the key for the user, even if other user(s) have it added already. This behavior is needed so that another user can't remove the key out from under the user. - 'fscrypt lock' and pam_fscrypt remove the key for the user. However, if the key wasn't truly removed because other users still have it added, 'fscrypt lock' prints a warning. - 'fscrypt status' shows whether the directory is unlocked for anyone.
FS_IOC_ADD_ENCRYPTION_KEY and FS_IOC_REMOVE_ENCRYPTION_KEY require root for v1 policy keys, so update the PAM module to re-acquire root privileges while provisioning/deprovisioning policies that need this. Also, only set up the user keyring if it will actually be used.
These were found by a combination of manual review and a custom script that checks for common errors. Also removed an outdated sentence from the comment for setupBefore().