The Linux Home Encryption Policy (LINUX_HOME_ENCRYPTION_POLICY) allows administrators to manage home directory encryption for specific Linux users as an alternative to full disk encryption. In many Linux environments, enabling full disk encryption requires reinstalling the operating system — home directory encryption provides a targeted, non-disruptive alternative that protects user data at rest.

This policy is available for both BYOD and company-owned devices. The device must not be TPM-enabled.

The Linux Home Encryption Policy uses fscrypt to encrypt the home directories of specified users. The encryption process follows these rules:

Once encrypted, a user's home directory will report the following fscrypt configuration:

When this policy is active, the device will report encryption status back to the Swif console:

This status is visible in the device details under MDM Device Info > Encryption.

Specifies whether to manage home encryption for all users on the device or only for specific users defined in the User List.

Note: When allUsers is set to true, the userList field is ignored. A dedicated boolean field is used (rather than placing "all" in the user list) to avoid ambiguity in cases where a Linux username is literally "all."

Specifies the Linux usernames whose home directory encryption should be managed by this policy. This field is only used when allUsers is set to false.

Example value:

Tip: Use the exact Linux username (login name) as it appears in /etc/passwd.

After the policy has been applied, you can verify whether a user's home directory is encrypted by running:

If encrypted, the output will show:

If not encrypted, the output will indicate that no fscrypt policy is applied to the directory.

A user may enter the correct password but be returned to the graphical login screen. This can occur when the user’s home directory remains encrypted and the automatic fscrypt unlock operation does not complete during startup.

The password itself may be valid. The graphical desktop cannot start because it cannot read files such as ~/.config while the encrypted home directory is locked.

In rare cases, this can be caused by the startup order of the services involved in unlocking the home directory.

Important: Do not repeatedly use the graphical login while troubleshooting. Use a text console and preserve the existing encrypted directory and key files.

From the graphical login screen:

Using a different administrator prevents the target user from retaining an active session. If no other administrator account is available, contact Swif Support before continuing.

Replace <username> with the affected Linux username:

A locked directory reports:

Encrypted filenames may appear as long, unreadable strings when the key is not loaded. This does not mean the files are empty or deleted.

Run:

If the affected user has an active graphical session, terminate it from the alternate administrator account:

There should be no remaining session for the affected user before attempting to unlock or decrypt the home directory.

Swif-managed encryption normally creates files under:

Check for the affected user’s key without displaying its contents:

The expected key path is:

Security warning: The key file is sensitive encryption material. Do not open it in an editor, print its contents, include it in logs, or send it through email or chat.

If the key exists, use it directly:

Then verify the result:

The status should report:

Normal filenames such as Desktop, Documents, and .config should become visible.

Return to the graphical login screen with Ctrl + Alt + F1 or Ctrl + Alt + F2, depending on the Linux distribution, and try signing in again.

Running fscrypt unlock without elevated permissions may produce an error similar to:

Use sudo and provide the Swif-managed key file:

If the protector is described as a raw key protector, the user’s normal login password cannot unlock the directory. Do not repeatedly enter the login password when fscrypt requests a key file.

If the key, unlock script, or other expected files are missing, stop troubleshooting and contact Swif Support.

Do not:

A newly generated key cannot unlock data encrypted with the original key. The files may still be present on disk, but their contents and filenames cannot be decrypted without recovering the original key.

To collect non-sensitive diagnostic information, run:

Some shells report no matches found when no backup directory matches a wildcard. This only means that no matching path was found.

Send the command output to Swif Support. Do not send encryption-key contents.

Search for any leftover copy of the key

Try recovering the deleted 32-byte file (ext4)
​
The key was a 32-byte file with path:
​/var/lib/swifteam/fscrypt/<username>.key
​
If df shows ext4 for /var:

Then, only if you are comfortable installing a recovery tool:

If that restores a file, check size:

It must be exactly 32 bytes. If it is, unlock with:

If undelete finds nothing
The safer option is to stop using this disk for writes, boot a USB live session. Learn more here.

If the original key cannot be recovered, the encrypted data cannot be decrypted with the login password or a newly generated key.

An administrator can remove the inaccessible encrypted home and create a new home directory, but this is not data recovery. It permanently abandons the encrypted data.

Before taking this action:

Do not delete the encrypted home directory merely to restore graphical login unless the loss of its contents has been reviewed and accepted.

After the home directory is unlocked:

For additional information about fscrypt, see the official fscrypt documentation.

If the Swif-managed key file is missing, the home directory may still contain encrypted files even though the user cannot sign in. A missing unlock script or disabled unlock service can also prevent automatic access, but recreating those components does not replace a lost key.

For example, an affected user named kenn may have:

The steps below use kenn as an example. Replace it with the affected username. Disk partitions, logical volumes, and mount paths must also be identified on the actual device.

An fscrypt raw-key protector requires the original 32-byte binary key, along with the filesystem’s encryption metadata. A login password cannot substitute for that raw key. If fscrypt status shows another valid protector, it may provide an alternative unlock method. See the official fscrypt documentation.

Do not generate a replacement key, run fscrypt encrypt again, delete the encrypted home, or remove its .fscrypt metadata. A new key cannot decrypt the existing data.

If the home is currently unlocked and files are readable, do not reboot or deliberately lock it. Preserve accessible files to secure external storage and contact Swif Support first. The following procedure addresses an already locked home with a missing key.

Use an existing alternate administrator account in a text console for brief diagnostics. Avoid ordinary desktop use, creating users, installing packages, copying large files, or running disk cleanup/TRIM on the affected storage.

If local recovery access is available, temporarily stop the agent to reduce its activity:

This can interrupt Swif management and reporting. It does not stop other system services from writing to disk. If the service name differs or remote management is your only access route, coordinate with Support before stopping it.

Collect these details without displaying key contents:

Record the approximate deletion time and timezone if known. Photograph the output or save it externally rather than writing diagnostic files to the affected disk.

Recover the filesystem that contained the key file. This may be the root filesystem or a separate /var filesystem, even when the encrypted home is on another volume.

If the home is locked and recovery is needed:

Do not open the internal disk in the file manager, which may mount it automatically. Check mountpoints before proceeding.

Keeping an alternate account open on the installed system is not a safe long-term recovery environment. Background writes can overwrite deleted data. The extundelete project recommends an unmounted source and a separate destination. See extundelete recovery guidance.

Full-disk encryption and home-directory encryption are separate layers:

For a device whose verified LUKS partition is /dev/nvme0n1p6, an example read-only mapping is:

Use the disk-unlock passphrase when prompted, which is not necessarily the desktop password. The --readonly option creates a read-only mapping. See cryptsetup open documentation.

If the mapped device contains LVM, identify and activate the correct volume group. For a group actually named ubuntu-vg:

An example logical-volume path is /dev/mapper/ubuntu--vg-ubuntu--lv. Use the path reported by the device, not an assumed partition or volume name.

No password prompt does not automatically mean failure; check whether the mapping exists. If the system relies on Clevis/TPM unlocking, have Support review its existing binding and live-environment requirements. Installing Clevis alone does not create a recovery credential, and it cannot recover the missing fscrypt key.

For the rest of this example, assume the root filesystem is ext4 and contains both /var/lib/swifteam and /home/kenn:

Only use this value after verifying the device. If /var or /home is separate, adapt the mounts and paths with Support.

For ext4, ro alone can still replay the journal. ro,noload prevents that replay, although an unclean filesystem may appear inconsistent. If mounting fails, stop rather than trying a writable mount or repairing the original filesystem. See the Linux kernel’s ext4 documentation.

Search the installed filesystem:

The search stays on that filesystem. Search separately mounted filesystems and external backups separately. Review any pre-existing snapshots that actually included the key’s location; do not create a new snapshot on the affected disk. A Btrfs subvolume list is not an ext4 recovery method, and a Timeshift snapshot may exclude relevant paths.

If a candidate key is found, note its path and securely preserve a copy externally. Do not print its contents or open it in an editor. A missing backup directory does not prove that no external backup exists.

When finished, unmount the source:

If no copy is found, preserve an image before recovery attempts. For important data or a disk showing read errors, use a qualified recovery specialist.

The example below assumes:

Verify the destination with findmnt -T /mnt/recovery and df -h /mnt/recovery. Stop if the external drive is not mounted there or the destination is on the affected disk.

Install tools in the live session, not inside the installed system:

Create a filesystem image on the external drive:

Review the result. Do not interpret an incomplete image as proof that the key is unrecoverable. The image can contain sensitive information, including data exposed by opening LUKS; protect the external drive accordingly.

Run extundelete against the unmounted image, writing output externally:

The restore path is relative to the root of the imaged filesystem:

By default, recovered files are placed under RECOVERED_FILES in the working directory. Recovery is not guaranteed, and extundelete may not handle every modern ext4 feature. See the extundelete command reference.

Stop if it reports EXT3_FEATURE_INCOMPAT_RECOVER, requests unmounting, or recommends running fsck.

Confirm that you are using the intended image and that it is not mounted. The warning can persist on an image because it preserves the original filesystem’s unclean state.

Do not run fsck on the original disk to clear the warning. Keep the original image unchanged. Have Support or a recovery specialist evaluate a separate working copy before journal replay, repair, or further attempts.

Do not save recovered files under another user’s home on the affected filesystem. That can overwrite the deleted key’s blocks.

Locate candidate files without displaying their contents:

The expected key is exactly 32 bytes. Size alone does not establish that it is the correct key. Do not truncate, pad, or convert a recovered file to make its size match.

After preserving the image, mount the original ext4 filesystem read-only again for a controlled unlock test. For the example where root contains the home and its fscrypt metadata:

Use the actual recovered path. Install fscrypt in the live environment if needed. If the home is on a separate filesystem, mount that filesystem and preserve its .fscrypt metadata; the example path must be adjusted.

Success should show Unlocked: Yes and allow normal filenames and files to be read. Back up accessible data to secure external storage before attempting service repairs or normal use.

If the key is rejected, keep all candidates and the image. A same-sized file, a damaged key, or missing encryption metadata can prevent unlocking. See fscrypt’s recovery and metadata guidance.

After successful recovery, work with Swif Support to restore the key’s expected path and permissions, the missing unlock script, and the per-user service. A successful manual unlock does not fix automatic unlocking. Preserve the recovered key and data backup before testing a reboot, then confirm agent operation and policy status.

If recovery finds nothing, preserve the disk and image. Further writes or discarded SSD blocks may make recovery impossible. PhotoRec is not a guaranteed fallback for a small random binary key; it primarily identifies files by recognizable formats. See PhotoRec’s recovery overview.

If no original key, usable alternative protector, or readable backup is available, recreating the desktop requires a separate decision to abandon the inaccessible home. Follow Replacing the Home Directory After Accepting Data Loss in this article.

Deleting /home/kenn and copying /etc/skel creates a fresh home. It does not recover encrypted files. Do not include that operation in the key-recovery procedure. Any later rebuild must verify both the user’s UID and GID rather than assuming 1000:1000.

When contacting Support, provide the filesystem layout, approximate deletion time, tool errors, and candidate file paths and sizes. Do not send key contents, disk passphrases, or private files through ordinary chat or email.

If you encounter the error `encrypt user home "<username>": user has an active login session; retry after logout`, it indicates that the encryption process was skipped because the target user is currently logged in. To prevent data corruption, the policy only applies when the user is logged out.

To resolve this and ensure the home directory is encrypted:

Once these steps are completed, the device will report the encryption status as active in the Swif console.

Q: What happens if allUsers is true and I also provide a userList?
A: The userList is ignored. When allUsers is enabled, encryption management applies to every user on the device.

Q: Why does encryption only run when the user is logged out?
A: Encrypting a home directory while the user is actively logged in could cause data corruption or session instability. The agent waits until the user logs out before performing encryption operations.

Q: Which encryption method is used?
A: This policy uses fscrypt (Linux native file-system-level encryption). The agent verifies encryption status via sudo fscrypt status /home/<username>.

Q: Does this work on non-ext4 file systems?
A: No. Currently only ext4 file systems are supported. Home directories on btrfs, xfs, or other file systems will not be managed.

Q: Why isn't my home directory encrypted even though the policy is assigned?
A: The most common reason is that you are currently logged in. Log out, have another user log in (or restart the device and log in as a different user), and the encryption will be applied to your home directory.

Q: Do I need to reinstall my OS to use this policy?
A: No. Unlike full disk encryption, home directory encryption can be applied to existing installations without reinstalling the operating system.

Q: What happens if I assign an empty user list?
A: No home directories will be encrypted. This effectively disables the policy without removing it.

Q: How do I encrypt all users' home directories?
A: Set allUsers to true.