1--- 2title: Home Directories 3category: Users, Groups and Home Directories 4layout: default 5SPDX-License-Identifier: LGPL-2.1-or-later 6--- 7 8# Home Directories 9 10[`systemd-homed.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html) 11manages home directories of regular ("human") users. Each directory it manages 12encapsulates both the data store and the user record of the user, so that it 13comprehensively describes the user account, and is thus naturally portable 14between systems without any further, external metadata. This document describes 15the format used by these home directories, in the context of the storage 16mechanism used. 17 18## General Structure 19 20Inside of the home directory a file `~/.identity` contains the JSON formatted 21user record of the user. It follows the format defined in 22[`JSON User Records`](USER_RECORD.md). It is recommended to bring the 23record into 'normalized' form (i.e. all objects should contain their fields 24sorted alphabetically by their key) before storing it there, though this is not 25required nor enforced. Since the user record is cryptographically signed, the 26user cannot make modifications to the file on their own (at least not without 27corrupting it, or knowing the private key used for signing the record). Note 28that user records are stored here without their `binding`, `status` and 29`secret` sections, i.e. only with the sections included in the signature plus 30the signature section itself. 31 32## Storage Mechanism: Plain Directory/`btrfs` Subvolume 33 34If the plain directory or `btrfs` subvolume storage mechanism of 35`systemd-homed` is used (i.e. `--storage=directory` or `--storage=subvolume` on 36the 37[`homectl(1)`](https://www.freedesktop.org/software/systemd/man/homectl.html) 38command line) the home directory requires no special setup besides including 39the user record in the `~/.identity` file. 40 41It is recommended to name home directories managed this way by 42`systemd-homed.service` by the user name, suffixed with `.homedir` (example: 43`lennart.homedir` for a user `lennart`) but this is not enforced. When the user 44is logged in, the directory is generally mounted to `/home/$USER` (in our 45example: `/home/lennart`), thus dropping the suffix while the home directory is 46active. `systemd-homed` will automatically discover home directories named this 47way in `/home/*.homedir` and synthesize NSS user records for them as they show 48up. 49 50## Storage Mechanism: `fscrypt` Directories 51 52This storage mechanism is mostly identical to the plain directory storage 53mechanism, except that the home directory is encrypted using `fscrypt`. (Use 54`--storage=fscrypt` on the `homectl` command line.) Key management is 55implemented via extended attributes on the directory itself: for each password 56an extended attribute `trusted.fscrypt_slot0`, `trusted.fscrypt_slot1`, 57`trusted.fscrypt_slot2`, … is maintained. Its value contains a colon-separated 58pair of Base64 encoded data fields. The first field contains a salt value, the 59second field the encrypted volume key. The latter is encrypted using AES256 in 60counter mode, using a key derived from the password via PBKDF2-HMAC-SHA512, 61together with the salt value. The construction is similar to what LUKS does for 62`dm-crypt` encrypted volumes. Note that extended attributes are not encrypted 63by `fscrypt` and hence are suitable for carrying the key slots. Moreover, by 64using extended attributes, the slots are directly attached to the directory and 65an independent sidecar key database is not required. 66 67## Storage Mechanism: `cifs` Home Directories 68 69In this storage mechanism, the home directory is mounted from a CIFS server and 70service at login, configured inside the user record. (Use `--storage=cifs` on 71the `homectl` command line.) The local password of the user is used to log into 72the CIFS service. The directory share needs to contain the user record in 73`~/.identity` as well. Note that this means that the user record needs to be 74registered locally before it can be mounted for the first time, since CIFS 75domain and server information needs to be known *before* the mount. Note that 76for all other storage mechanisms it is entirely sufficient if the directories 77or storage artifacts are placed at the right locations — all information to 78activate them can be derived automatically from their mere availability. 79 80## Storage Mechanism: `luks` Home Directories 81 82This is the most advanced and most secure storage mechanism and consists of a 83Linux file system inside a LUKS2 volume inside a loopback file (or on removable 84media). (Use `--storage=luks` on the `homectl` command line.) Specifically: 85 86* The image contains a GPT partition table. For now it should only contain a 87 single partition, and that partition must have the type UUID 88 `773f91ef-66d4-49b5-bd83-d683bf40ad16`. Its partition label must be the 89 user name. 90 91* This partition must contain a LUKS2 volume, whose label must be the user 92 name. The LUKS2 volume must contain a LUKS2 token field of type 93 `systemd-homed`. The JSON data of this token must have a `record` field, 94 containing a string with base64-encoded data. This data is the JSON user 95 record, in the same serialization as in `~/.identity`, though encrypted. The 96 JSON data of this token must also have an `iv` field, which contains a 97 base64-encoded binary initialization vector for the encryption. The 98 encryption used is the same as the LUKS2 volume itself uses, unlocked by the 99 same volume key, but based on its own IV. 100 101* Inside of this LUKS2 volume must be a Linux file system, one of `ext4`, 102 `btrfs` and `xfs`. The file system label must be the user name. 103 104* This file system should contain a single directory named after the user. This 105 directory will become the home directory of the user when activated. It 106 contains a second copy of the user record in the `~/.identity` file, like in 107 the other storage mechanisms. 108 109The image file should reside in a directory `/home/` on the system, 110named after the user, suffixed with `.home`. When activated, the container home 111directory is mounted to the same path, though with the `.home` suffix dropped — 112unless a different mount point is defined in the user record. (e.g.: the 113loopback file `/home/waldo.home` is mounted to `/home/waldo` while activated.) 114When the image is stored on removable media (such as a USB stick), the image 115file can be directly `dd`'ed onto it; the format is unchanged. The GPT envelope 116should ensure the image is properly recognizable as a home directory both when 117used in a loopback file and on a removable USB stick. (Note that when mounting 118a home directory from an USB stick, it too defaults to a directory in `/home/`, 119named after the username, with no further suffix.) 120 121Rationale for the GPT partition table envelope: this way the image is nicely 122discoverable and recognizable already by partition managers as a home 123directory. Moreover, when copied onto a USB stick the GPT envelope makes sure 124the stick is properly recognizable as a portable home directory 125medium. (Moreover, it allows embedding additional partitions later on, for 126example on a multi-purpose USB stick that contains both a home 127directory and a generic storage volume.) 128 129Rationale for including the encrypted user record in the LUKS2 header: 130Linux kernel file system implementations are generally not robust towards 131maliciously formatted file systems; there's a good chance that file system 132images can be used as attack vectors, exploiting the kernel. Thus it is 133necessary to validate the home directory image *before* mounting it and 134establishing a minimal level of trust. Since the user record data is 135cryptographically signed and user records not signed with a recognized private 136key are not accepted, a minimal level of trust between the system and the home 137directory image is established. 138 139Rationale for storing the home directory one level below to root directory of 140the contained file system: this way special directories such as `lost+found/` 141do not show up in the user's home directory. 142 143## Algorithm 144 145Regardless of the storage mechanism used, an activated home directory 146necessarily involves a mount point to be established. In case of the 147directory-based storage mechanisms (`directory`, `subvolume` and `fscrypt`) 148this is a bind mount. In case of `cifs` this is a CIFS network mount, and in 149case of the LUKS2 backend a regular block device mount of the file system 150contained in the LUKS2 image. By requiring a mount for all cases (even for 151those that already are a directory), a clear logic is defined to distinguish 152active and inactive home directories, so that the directories become 153inaccessible under their regular path the instant they are 154deactivated. Moreover, the `nosuid`, `nodev` and `noexec` flags configured in 155the user record are applied when the bind mount is established. 156 157During activation, the user records retained on the host, the user record 158stored in the LUKS2 header (in case of the LUKS2 storage mechanism) and the 159user record stored inside the home directory in `~/.identity` are 160compared. Activation is only permitted if they match the same user and are 161signed by a recognized key. When the three instances differ in `lastChangeUSec` 162field, the newest record wins, and is propagated to the other two locations. 163 164During activation, the file system checker (`fsck`) appropriate for the 165selected file system is automatically invoked, ensuring the file system is in a 166healthy state before it is mounted. 167 168If the UID assigned to a user does not match the owner of the home directory in 169the file system, the home directory is automatically and recursively `chown()`ed 170to the correct UID. 171 172Depending on the `luksDiscard` setting of the user record, either the backing 173loopback file is `fallocate()`ed during activation, or the mounted file system 174is `FITRIM`ed after mounting, to ensure the setting is correctly enforced. 175 176When deactivating a home directory, the file system or block device is trimmed 177or extended as configured in the `luksOfflineDiscard` setting of the user 178record. 179