]> git.ipfire.org Git - thirdparty/systemd.git/commit
homed/fscrypt: default new homes to v2 policies 42397/head
authorAnanth Bhaskararaman <antsub@gmail.com>
Tue, 2 Jun 2026 21:42:04 +0000 (03:12 +0530)
committerAnanth Bhaskararaman <antsub@gmail.com>
Tue, 21 Jul 2026 04:48:06 +0000 (10:18 +0530)
commit571253fdbe9fcc77b9bf630867d1ab80be38a8d6
tree20d2344c0a1ca82e58e487caaa321b37f2c7bd32
parent769e35369cb313ea2679d72b24c0fa15020eb288
homed/fscrypt: default new homes to v2 policies

fscrypt v1 policies bind master keys to the calling process's keyring,
which means files in a homed-managed directory aren't readable when
accessed through a container bind mount, a different mount namespace,
or by any process other than the one that first unlocked the home.
Reading a file from outside such a context first warms the buffer cache
and papers over the symptom (#18280), but the underlying problem (the
key not flowing across keyrings) remains.

v2 policies (Linux 5.4+) route master keys through the filesystem
keyring via FS_IOC_ADD_ENCRYPTION_KEY / FS_IOC_REMOVE_ENCRYPTION_KEY,
so the key is visible to every process accessing the filesystem.

Switch homed to v2:

- Read the existing policy via FS_IOC_GET_ENCRYPTION_POLICY_EX, which
  reports both v1 and v2 policies. The ioctl is available since Linux
  5.4, i.e. on every kernel we support (our baseline is 5.10), so no
  fallback to the v1-only FS_IOC_GET_ENCRYPTION_POLICY is needed.
- Drive slot matching off a full fscrypt_key_specifier (HomeSetup now
  carries that instead of a bare 8-byte descriptor). Slot decryption
  derives either the v1 descriptor (SHA-512 double hash) or the v2
  identifier (HKDF-SHA512 with the kernel's info string), and compares
  against the policy.
- Install the master key the right way per version: add_key("logon", ...)
  to thread+user keyrings for v1, FS_IOC_ADD_ENCRYPTION_KEY for v2.
- home_flush_keyring_fscrypt opens the image directory, looks up the
  policy, and either calls FS_IOC_REMOVE_ENCRYPTION_KEY (v2) or walks
  the user keyring (v1).
- New homes default to v2; fall back to v1 only if the kernel rejects
  FS_IOC_ADD_ENCRYPTION_KEY with ENOTTY/EOPNOTSUPP. The v2 create path
  derives the identifier locally first, passes it to ADD_KEY as
  expected_identifier, and cleans up via REMOVE_KEY if SET_POLICY then
  fails, so the v1 fallback never sees a stranded key. Existing v1
  homes continue to unlock, rekey, and deactivate as before.
- A v2 master key installed to work on an inactive home is always
  removed again unless that home ends up activated. v2 keys persist in
  the filesystem keyring until removed explicitly (v1 keys instead died
  with the homework process' keyring), so a key left behind would leave
  a home nobody activated readable until the next deactivation or reboot.
  home_setup_fscrypt() and home_create_fscrypt() therefore arm a rollback
  right after installing the key; the activation path disarms it once the
  mount is in place (the live home owns the key), while every other path
  -- create, and passwd/update/resize of an inactive home, plus all error
  paths -- rolls it back via home_setup_done(). Activation reinstalls the
  key.

The v1 and v2 on-disk policy formats differ (v1: 8-byte descriptor;
v2: 16-byte identifier) and fscrypt has no in-place upgrade path, so
a v1 home is always unlocked via the v1 code path and a v2 home is
always unlocked via the v2 code path, regardless of kernel version.

Slot xattr format is unchanged: the master key is the same, only how it
binds to the directory changes.

Fixes #18280.

Ananth Bhaskararaman antsub@gmail.com
README
src/home/homework-directory.c
src/home/homework-forward.h
src/home/homework-fscrypt.c
src/home/homework-fscrypt.h
src/home/homework.c
src/home/homework.h