From 9003a0331a112e8901fae8279f4897a825ee8069 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 15 Dec 2019 19:31:39 -0800 Subject: cmd/fscrypt: add 'fscrypt lock' command Add support for 'fscrypt lock'. This command "locks" a directory, undoing 'fscrypt unlock'. When the filesystem keyring is used, 'fscrypt lock' also detects when a directory wasn't fully locked due to some files still being in-use. It can then be run again later to try to finish locking the files. --- README.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3a86723..f183f2e 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,8 @@ Concretely, fscrypt contains the following functionality: * `fscrypt setup MOUNTPOINT` - Gets a filesystem ready for use with fscrypt * `fscrypt encrypt DIRECTORY` - Encrypts an empty directory * `fscrypt unlock DIRECTORY` - Unlocks an encrypted directory -* `fscrypt purge MOUNTPOINT` - Removes keys for a filesystem before unmounting +* `fscrypt lock DIRECTORY` - Locks an encrypted directory +* `fscrypt purge MOUNTPOINT` - Locks all encrypted directories on a filesystem * `fscrypt status [PATH]` - Gets detailed info about filesystems or paths * `fscrypt metadata` - Manages policies or protectors directly @@ -367,12 +368,10 @@ Protected with 1 protector: PROTECTOR LINKED DESCRIPTION 7626382168311a9d No custom protector "Super Secret" -# Purging a filesystem locks all the files. ->>>>> sudo fscrypt purge /mnt/disk --user=$USER -WARNING: Encrypted data on this filesystem will be inaccessible until unlocked again!! -Purge all policy keys from "/mnt/disk" and drop global inode cache? [y/N] y -Policies purged for "/mnt/disk". - +# Lock the directory. +>>>>> sudo fscrypt lock /mnt/disk/dir1 --user=$USER +Encrypted data removed from filesystem cache. +"/mnt/disk/dir1" is now locked. >>>>> fscrypt status /mnt/disk/dir1 "/mnt/disk/dir1" is encrypted with fscrypt. @@ -410,7 +409,7 @@ Hello World #### Quiet Version ```bash ->>>>> sudo fscrypt purge /mnt/disk --user=$USER --quiet --force +>>>>> sudo fscrypt lock /mnt/disk/dir1 --quiet --user=$USER >>>>> echo "hunter2" | fscrypt unlock /mnt/disk/dir1 --quiet ``` -- cgit v1.2.3 From 2b25de6d445faefc28629603dd754aec9f744e60 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 15 Dec 2019 19:31:39 -0800 Subject: Metadata support for v2 encryption policies Linux v5.4 and later supports v2 encryption policies. These have several advantages over v1 encryption policies: - Their encryption keys can be added/removed to/from the filesystem by non-root users, thus gaining the benefits of the filesystem keyring while also retaining support for non-root use. - They use a more standard, secure, and flexible key derivation function. Because of this, some future kernel-level fscrypt features will be implemented for v2 policies only. - They prevent a denial-of-service attack where a user could associate the wrong key with another user's encrypted files. Prepare the fscrypt tool to support v2 encryption policies by: - Adding a policy_version field to the EncryptionOptions, i.e. to the config file and to the policy metadata files. - Using the kernel-specified algorithm to compute the key descriptor for v2 policies. - Handling setting and getting v2 policies. Actually adding/removing the keys for v2 policies to/from the kernel is left for the next patch. --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f183f2e..ee8e389 100644 --- a/README.md +++ b/README.md @@ -361,7 +361,7 @@ POLICY UNLOCKED PROTECTORS "/mnt/disk/dir1" is encrypted with fscrypt. Policy: 16382f282d7b29ee -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: Yes Protected with 1 protector: @@ -376,7 +376,7 @@ Encrypted data removed from filesystem cache. "/mnt/disk/dir1" is encrypted with fscrypt. Policy: 16382f282d7b29ee -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: No Protected with 1 protector: @@ -397,7 +397,7 @@ Enter custom passphrase for protector "Super Secret": "/mnt/disk/dir1" is encrypted with fscrypt. Policy: 16382f282d7b29ee -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: Yes Protected with 1 protector: @@ -433,7 +433,7 @@ Enter login passphrase for joerichey: "/mnt/disk/dir2" is encrypted with fscrypt. Policy: fe1c92009abc1cff -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: Yes Protected with 1 protector: @@ -469,7 +469,7 @@ PROTECTOR LINKED DESCRIPTION "/mnt/disk/dir1" is encrypted with fscrypt. Policy: 16382f282d7b29ee -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: Yes Protected with 1 protector: @@ -565,7 +565,7 @@ fe1c92009abc1cff No 6891f0a901f0065e "/mnt/disk/dir1" is encrypted with fscrypt. Policy: 16382f282d7b29ee -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: No Protected with 1 protector: @@ -581,7 +581,7 @@ Protector 2c75f519b9c9959d now protecting policy 16382f282d7b29ee. "/mnt/disk/dir1" is encrypted with fscrypt. Policy: 16382f282d7b29ee -Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS +Options: padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:1 Unlocked: No Protected with 2 protectors: -- cgit v1.2.3 From 42e0dfe85ec7a75a2fa30c417d57eae60b5a881d Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 15 Dec 2019 19:31:39 -0800 Subject: Keyring support for v2 encryption policies 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. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ee8e389..4130962 100644 --- a/README.md +++ b/README.md @@ -279,8 +279,9 @@ after `pam_unix.so` in `/etc/pam.d/common-session` or similar. The `lock_policies` option locks the directories protected with the user's login passphrase when the last session ends. The `drop_caches` option tells fscrypt to clear the filesystem caches when the last session closes, ensuring all the -locked data is inaccessible. All the types also support the `debug` option which -prints additional debug information to the syslog. +locked data is inaccessible; this only needed for v1 encryption policies. +All the types also support the `debug` option which prints additional +debug information to the syslog. ## Note about stability @@ -368,7 +369,8 @@ Protected with 1 protector: PROTECTOR LINKED DESCRIPTION 7626382168311a9d No custom protector "Super Secret" -# Lock the directory. +# Lock the directory. 'sudo' and the '--user' argument are only +# required if the directory uses a v1 encryption policy. >>>>> sudo fscrypt lock /mnt/disk/dir1 --user=$USER Encrypted data removed from filesystem cache. "/mnt/disk/dir1" is now locked. -- cgit v1.2.3 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(-) (limited to 'README.md') 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