encryptfs-insert-wrapped-passphrase-itno-keyring

---
title: "fscrypt implementation"
source: ""
author:
  - ""
published:
created: 2026-07-15
description: "Search the Web. Privately. Truly useful results, AI-powered answers, & more. All from an independent index. No profiling, no bias, no Big Tech."
tags:
  - "clippings"
---
```
# fscrypt Implementation Guide for Garuda Linux (ext4)
**Date:** July 15, 2026  
**Target System:** Garuda Linux (Arch-based) on ext4 with LUKS full-disk encryption.  
**Status:** Current & Verified. eCryptfs is deprecated/removed; fscrypt is the standard.

---

## ⚠️ Critical Pre-Flight Checks

1.  **Filesystem Verification:** Confirm you are on **ext4**. fscrypt does not support Btrfs for home directory encryption in this manner.
    \`\`\`bash
    df -T /home
    # Output must show 'ext4'
    \`\`\`
2.  **Backup Strategy:** **Create a full backup** of your \`/home\` directory to an external drive. The migration process involves moving data; while safe, hardware failures or user errors can occur.
3.  **Recovery Phrase:** You **MUST** save the \`fscrypt_recovery_readme.txt\` content to a secure, offline location (e.g., password manager, printed paper). If you lose your login password, this is the **only** way to recover your data.

---

## Phase 1: Filesystem Preparation

The ext4 filesystem must have the \`encrypt\` feature flag enabled. Since you are using LUKS, you must apply this to the **mapped device**, not the physical partition.

### 1. Identify the Mapped Device
Find the device name associated with your LUKS container (e.g., \`cryptroot\`, \`luks-<uuid>\`).
\`\`\`bash
lsblk -f
# Look for the device mounted at '/' or '/home' with FSTYPE='ext4' under the crypto_LUKS layer.
# Example: /dev/mapper/luks-520d831c-aede-4969-80a6-3663b56d7274
```

### 2\. Enable Encryption Feature

Run the following on the **mapped device** identified above:

```
# Replace with your actual mapper path
sudo tune2fs -O encrypt /dev/mapper/YOUR_LUKS_MAPPER_NAME
```

### 3\. Verify

Ensure `encrypt` appears in the features list:

```
sudo tune2fs -l /dev/mapper/YOUR_LUKS_MAPPER_NAME | grep "Filesystem features"
```

---

## Phase 2: Installation & Initialization

### 1\. Install Packages

Install the fscrypt tool and the PAM module for auto-unlocking.

```
sudo pacman -S fscrypt libpam-fscrypt
```

### 2\. Initialize Global Config

Setup the global configuration and metadata directory on the root filesystem.

```
sudo fscrypt setup
```
- **Prompt:** "Defaulting to policy\_version 2..." -> Accept defaults.
- **Prompt:** "Do you want to allow users to create their own protectors?" -> **No** (Recommended for single-user systems to keep metadata root-owned) or **Yes** (If you prefer user-writable metadata).

### 3\. Initialize Mountpoint

Setup fscrypt specifically for your home directory.

```
sudo fscrypt setup /home
```
- **Prompt:** "Do you want to make /home/.fscrypt writable to all users?" -> **Yes**. (Required for users to manage their own encryption).

---

## Phase 3: Data Migration (The "Swap" Method)

**Constraint:** fscrypt **cannot** encrypt files in place. You must encrypt an empty directory and move data in.

### 1\. Prepare for Migration

Log out of your graphical session. Switch to a TTY (Ctrl+Alt+F3) or boot from a **Garuda Live USB** to ensure no files in `/home` are in use. Log in as `root`.

### 2\. Rename Existing Home

Move your current unencrypted home directory to a backup name.

```
mv /home/youruser /home/youruser.bak
```

### 3\. Create New Empty Home

Recreate the directory with correct permissions.

```
mkdir /home/youruser
chown youruser:youruser /home/youruser
chmod 700 /home/youruser
```

### 4\. Encrypt the Directory

Run this as the **user** (or use `--user` flag as root) to link encryption to your login password.

```
# Run as root but specify the user
fscrypt encrypt /home/youruser --user=youruser
```
- **Prompt:** "Should we create a new protector?" -> **Yes**.
- **Prompt:** "Select source..." -> **1 - Your login passphrase (pam\_passphrase)**.
- **Action:** **IMMEDIATELY** copy the contents of `fscrypt_recovery_readme.txt` displayed on screen to your secure backup location.

### 5\. Restore Data

Copy your data back into the now-encrypted directory.

```
rsync -avH /home/youruser.bak/ /home/youruser/
```
- **Verification:** Log in as the user. Ensure files are accessible. Check `fscrypt status /home/youruser` (should say `Unlocked: Yes`).
- **Cleanup:** Once verified, securely delete the backup:
	```
	rm -rf /home/youruser.bak
	```

---

## Phase 4: PAM Configuration (Auto-Unlock)

To ensure the directory unlocks automatically at login and locks at logout, configure PAM.

### 1\. Edit System Login

Edit `/etc/pam.d/system-login`:

- **Auth Section:** Add `auth optional pam_fscrypt.so`
- **Session Section:** Add `session optional pam_fscrypt.so` (Place before `include system-auth` if possible, or after).

### 2\. Edit Display Manager (Garuda Default: SDDM)

Edit `/etc/pam.d/sddm` (or `lightdm`/`gdm` if changed):

- **Auth Section:** Add `auth optional pam_fscrypt.so`
- **Session Section:** Add `session optional pam_fscrypt.so`

### 3\. Edit Password Change Hook

Edit `/etc/pam.d/passwd`:

- **Password Section:** Add `password optional pam_fscrypt.so`
	- *Why:* This ensures that if you change your login password, the encryption key is automatically re-wrapped with the new password. Without this, changing your password will lock you out of your home directory.

---

## 🔑 Key Insights & Best Practices

### 1\. The "Recovery Passphrase" is Critical

When you select "Login Passphrase" as the protector, fscrypt automatically generates a random **Recovery Passphrase**.

- **Storage:** Save this string offline. It is not stored on the disk in plain text; it is the only backup key.
- **Usage:** If you forget your login password or corrupt your PAM config, you can unlock the directory using `fscrypt unlock /home/youruser` and selecting the recovery option.

### 2\. Metadata Backup (`/.fscrypt`)

The directory `/.fscrypt` (on root) and `/home/.fscrypt` contain the metadata linking your password to the encryption keys.

- **Risk:** If these files are deleted, **data is lost forever**, even if you know your password.
- **Mitigation:** Include these directories in your regular system backups (e.g., Timeshift, rsync).

### 3\. Password Changes

Because we configured `pam_fscrypt.so` in `/etc/pam.d/passwd`, changing your password via standard tools (`passwd`, KDE Settings) will automatically update the encryption wrapper.

- **Warning:** If you ever reset a password via `root` (forcing a reset without the old password), the fscrypt key will **not** update. You will need to use the **Recovery Passphrase** to unlock the directory and then re-encrypt it or add a new protector.

### 4\. Performance

- **Filenames:** Filenames are encrypted. This prevents leakage of sensitive file names but may slightly impact directory listing speeds for folders with tens of thousands of files.
- **Double Encryption:** You are now running LUKS (Block Level) + fscrypt (File Level). This is "Defense in Depth."
	- *Benefit:* If the system is running and an attacker gains root, they still cannot read your files if you are logged out (fscrypt locks on logout). LUKS alone leaves files readable to root while the OS is running.
		- *Cost:* Negligible CPU overhead on modern CPUs with AES-NI instructions.

### 5\. Troubleshooting Lockouts

If you cannot log in after a reboot:

1. Boot to a TTY or Live USB.
2. Mount your LUKS container.
3. Run `fscrypt unlock /home/youruser`.
4. Enter your **Recovery Passphrase**.
5. Check `fscrypt status` to diagnose policy issues.

---

## Verification Commands

- **Check Status:** `fscrypt status /home/youruser`
- **Check Mountpoint:** `fscrypt status /home`
- **Manual Lock Test:** `fscrypt lock /home/youruser` (Try listing dir; should show gibberish or empty).
- **Manual Unlock Test:** `fscrypt unlock /home/youruser` (Enter password; files should appear).