Overview

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.

Supported Platforms

Requirement	Details
Operating System	Linux
File System	ext4 only
Encryption Tool	`fscrypt` (preferred). Legacy `ecryptfs` is not used.
Device Ownership	Company-owned and BYOD (Non TPM)

How It Works

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

Encryption only runs while the target user is logged out. If a user in the policy's user list is currently logged in, their home directory will not be encrypted during that session. This prevents file corruption from encrypting an active home directory.
Encryption is applied on the next login cycle. When another user logs in and the target user is logged out, the agent encrypts the logged-out user's home directory.
All users are encrypted after a full login cycle. By cycling through logins (e.g., logging in as each user in turn), all specified users' home directories will be encrypted.

Encryption Details

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

Contents encryption: AES-256-XTS
Filenames encryption: AES-256-CTS
Padding: 32
Policy version: 2

Device Compliance Reporting

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

Status	Meaning
`Encrypted`	The user's home directory is encrypted via fscrypt
`Unencrypted`	The user's home directory is not encrypted

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

Policy Configuration

1. Apply to All Users (`allUsers`)

Property	Value
Type	Boolean
Default	`false`
Required	No
Platform	Linux

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

true — Home encryption will be managed for all users on the device.
false — Home encryption will be managed only for users specified in the userList field.

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."

2. User List (`userList`)

Property	Value
Type	Array of Strings
Default	None
Required	No
Platform	Linux

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:

["john", "jane", "deploy-user"]

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

Quick Reference

Field	Display Name	Type	Default
`allUsers`	Apply to All Users	Boolean	`false`
`userList`	User List	Array of Strings	—

Verifying Encryption Status

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

sudo fscrypt status /home/<username>

If encrypted, the output will show:

"/home/userB" is encrypted with fscrypt.

Policy:   <policyId>
Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2
Unlocked: Yes

Protected with 1 protector:
...

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

Troubleshooting: User Is Returned to the Login Screen

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.

1. Open a Text Console

From the graphical login screen:

Press Ctrl + Alt + F3.
Sign in using a different sudo-enabled administrator account.
Remain in the text console until troubleshooting is complete.

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.

2. Check the Home Directory’s Encryption Status

Replace <username> with the affected Linux username:

sudo fscrypt status /home/<username>

A locked directory reports:

"/home/<username>" is encrypted with fscrypt. Unlocked: No

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

3. Confirm That the User Has No Active Session

Run:

loginctl list-sessions

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

sudo loginctl terminate-user <username> 
loginctl list-sessions

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

4. Check for the Swif-Managed Key

Swif-managed encryption normally creates files under:

/var/lib/swifteam/fscrypt/

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

sudo ls -la /var/lib/swifteam/fscrypt/ 
sudo test -f /var/lib/swifteam/fscrypt/<username>.key \   
  && echo "Key exists" \   
  || echo "Key is missing"

The expected key path is:

/var/lib/swifteam/fscrypt/<username>.key

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.

5. Unlock the Home Directory When the Key Exists

If the key exists, use it directly:

sudo fscrypt unlock /home/<username> \   
  --key=/var/lib/swifteam/fscrypt/<username>.key

Then verify the result:

sudo fscrypt status /home/<username> 
sudo ls -la /home/<username> | head

The status should report:

Unlocked: Yes

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.

Permission Denied When Running `fscrypt unlock`

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

open /.fscrypt/policies/<policy-id>: permission denied

Use sudo and provide the Swif-managed key file:

sudo fscrypt unlock /home/<username> \   
  --key=/var/lib/swifteam/fscrypt/<username>.key

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.

The Key File Is Missing

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

Do not:

Generate a new key
Run fscrypt encrypt again
Delete or rename the encrypted home directory
Create a replacement directory at the same path
Run file-recovery tools against the mounted system disk
Perform large downloads, installations, or file copies

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:

sudo ls -la /var/lib/swifteam/fscrypt/ 
sudo ls -ld /home/<username> \   
  /home/<username>.bak.* \   
  /home/<username>.new.* \   
  /home/<username>.encrypted.* \   
  /home/<username>.decrypted.* 2>/dev/null 
sudo systemctl status 'swif-fscrypt-unlock@<username>.service' 
df -hT /var/lib/swifteam /home/<username> 
lsblk -f

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.

Recovering a Missing Key

Recovery may be possible if the key was recently deleted and its disk blocks have not been overwritten. Continuing to use the device reduces the likelihood of successful recovery.

The safest approach is generally to:

Stop unnecessary activity on the affected device.
Shut down the installed operating system.
Boot from trusted Linux live media.
Unlock any full-disk encryption or LVM storage.
keep the affected filesystem unmounted while evaluating recovery options.
Create a forensic image when the encrypted data is important.
Use filesystem-appropriate recovery tools or engage a qualified data-recovery specialist.

Do not run extundelete, fsck, PhotoRec, or similar tools against a mounted production filesystem without understanding the recovery implications. Tool selection and commands depend on the device’s partitioning, full-disk encryption, LVM configuration, and filesystem.

Important: A live USB does not automatically recover the encrypted files. It provides a safer environment from which the original key might be recovered without writing to the affected filesystem.

Replacing the Home Directory After Accepting Data Loss

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:

Obtain explicit approval from the device owner or organization.
Confirm that no required backup exists.
Preserve a disk image if future recovery may be attempted.
Verify the user’s UID and GID.
Contact Swif Support for commands appropriate to the device.

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

After Restoring Access

After the home directory is unlocked:

Confirm that normal filenames and files are accessible.
Verify that the user can sign in graphically.
Restart the device and test another login.
Confirm that the unlock service runs successfully.
Review the policy assignment and device status in Swif.
Contact Swif Support if the directory becomes locked again.

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

Known Limitations

Limitation	Details
Logged-in users cannot be encrypted	Encryption is skipped for any user currently logged in to avoid file corruption. The user must be logged out for encryption to proceed.
ext4 file systems only	Other Linux file systems (e.g., btrfs, xfs) are not supported.
ecryptfs is legacy	The older `ecryptfs` method (which uses `/home/.ecryptfs/<username>/.Private`) is not used. This policy uses `fscrypt` exclusively.
TPM-enabled devices	Devices with TPM enabled are not compatible with this policy. For TPM-based full disk encryption, refer to your distribution's documentation.

Troubleshooting

Active Session Encryption

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:

Restart the device.
Log in as a different user (or a temporary administrative user).
Wait for 3 minutes to allow the Swif agent to complete the encryption process in the background.
Log back in as the target user.

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

Frequently Asked Questions

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.