Introduction

fscrypt is a tool built directly into the Linux kernel that encrypts individual files and directories instead of the entire hard drive. It transparently scrambles the contents and names of your files when they are saved to disk and unscrambles them when you open them, using a secure key that you provide.

Why use fscrypt

• Multi-User Security: It is great for shared computers or servers. User A and User B can have completely separate encrypted directories on the same hard drive.
• Targeted Protection: You only spend processing power encrypting the specific folders that contain sensitive data, rather than the whole system.
• Secure Cloud Backups: You can back up the raw, encrypted files to a cloud server. Even if the server is compromised, the files remain unreadable without your local Master Key.
• Instant Deletion: If you delete the Master Key, every file in the encrypted directory instantly turns into permanent, unrecoverable gibberish.

How it Works

File-Level vs. Full Disk Encryption

• Traditional Full Disk Encryption (like LUKS) encrypts the entire physical drive as one giant, uniform block of data.
• fscrypt operates at the "filesystem level." This means the core operating system still knows there are files and folders, how big they are, and who owns them. Only the actual data inside the files and the filenames are scrambled.

The Key Management System

fscrypt uses a hierarchy of keys to keep your data safe without slowing down your computer.

• The Master Key: When you set up an encrypted folder, you create a Master Key, which is usually protected by a passphrase or your login password.
• The Kernel Keyring: When you log in or unlock the folder, fscrypt securely loads your Master Key into a protected area of the Linux kernel called the "keyring."
• File-Specific Keys: To maximize security, fscrypt does not use the Master Key directly to encrypt your files. Instead, the kernel uses the Master Key to automatically generate a unique, temporary encryption key for every single file.

The Encryption Process (Reading and Writing)

• Writing a file: When you save a file into an fscrypt-enabled folder, the data first sits in your computer's temporary memory (RAM) as readable plain text. As the Linux kernel moves that data from RAM to the permanent storage drive, fscrypt steps in and scrambles it on the fly.
• Reading a file: When you open a file, the process reverses. The kernel pulls the scrambled data from the drive, fscrypt unlocks it using the file's unique key, and it delivers the readable plain text into your RAM so your applications can use it.

Runtime Encryption

When you unlock an encrypted folder, you are only handing the decryption key to the Linux kernel. The actual data resting on your hard drive remains scrambled 100% of the time.

• Reading a File: When you open a file, the kernel pulls the encrypted data from the disk and decrypts it into your computer's temporary memory (RAM). Your applications interact only with the unencrypted version sitting in RAM.
• Writing a File: When you save a file, your application writes normal, unencrypted data to RAM. Right before the kernel moves that data from RAM down to the physical hard drive, it encrypts it block-by-block.
• Locking the Folder: When you clear the key from the kernel's memory, the kernel simply "forgets" how to translate the data. Because the disk itself never changed, any attempt to access the files will instantly return scrambled gibberish or an error.

Handling Heavy Data

Here is what happens under the hood when you transfer a massive amount of data into an unlocked fscrypt folder

Block-by-Block Processing

• fscrypt does not attempt to encrypt or decrypt the entire ISO file at once.
• The filesystem divides the file into standard "blocks" (typically 4KB each). As the file transfers, fscrypt translates these blocks sequentially on the fly. It only needs enough RAM to hold the specific blocks it is actively working on at that exact millisecond, meaning a 10GB file will not consume 10GB of your system's memory during the transfer.

The "Page Cache" Buffer

• When an application dumps massive log files, it doesn't write directly to the physical drive instantly. Linux uses a chunk of your free RAM called the "page cache" as a waiting room.
• Your application writes the plain-text data into this RAM buffer at lightning speed and considers the job "done," allowing the application to keep running without freezing.
• The Linux kernel then works in the background to take the data from that buffer, encrypt it block-by-block, and permanently flush it down to the physical drive.

Hardware Acceleration

• Almost all modern computer processors (both Intel/AMD and ARM) have dedicated physical circuits built directly into the silicon specifically for AES encryption (often called AES-NI).
• This hardware can scramble and unscramble data significantly faster than your physical storage drive (even a fast NVMe SSD) can read or write it.

Bottleneck

• Because of this hardware acceleration and the page cache, the CPU is almost never the bottleneck. If transferring a massive ISO file takes a long time, it is almost always because the physical hard drive has reached its maximum hardware write speed, not because fscrypt is struggling to keep up with the encryption.

What Gets Encrypted

Encrypted

• File contents
• Filenames and directory names inside protected folders
• Symlink targets

NOT Encrypted (visible to anyone with disk access)

• Directory structure (you can see that a folder exists and contains X encrypted files)
• File sizes, timestamps, permissions, ownership
• Extended attributes (unless the filesystem specifically supports encrypting them)
• Filesystem metadata (superblock, journals, allocation bitmaps)

Security Model & Limitations

What It Protects Against

• Offline attacks: Stolen drive, backup media, cloud snapshots
• Physical access: Someone pulling your SSD out and reading it on another machine
• Multi-tenant isolation: Different users/directories can use different keys

What It Does NOT Protect Against

• Root/admin compromise: If an attacker has kernel or root access, they can read keys from memory or intercept decrypted data
• Swap/hibernation leaks: If your system swaps encrypted file contents to disk or hibernates with keys in RAM, plaintext may persist
• Filesystem metadata analysis: Attackers can still see file sizes, timestamps, and directory layout
• Online attacks: Malware running on your machine can read files while they're decrypted in memory

Full Process Diagram

graph TD
    %% Define styles
    classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
    classDef meta fill:#fff3e0,stroke:#e65100,stroke-width:2px;
    classDef system fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;

    %% Nodes
    Input["Your Passphrase or Raw Key"]:::user
    
    Protector["Protector
(The Lockbox)"]:::meta
    
    subgraph Policy ["Policy (The Rulebook)"]
        TrueKey["Master Encryption Key
(The True Key)"]:::meta
        Rules["Encryption Algorithm Rules"]:::meta
    end
    
    Kernel["Linux Kernel Memory"]:::system
    Files["Encrypted Files & Directory"]:::system

    %% Connections
    Input -->|Step 1: Unlocks| Protector
    Protector -->|Step 2: Unwraps| TrueKey
    TrueKey -.->|Step 3: Loaded into| Kernel
    Policy -->|Step 4: Assigned to| Files
    Kernel ===>|Step 5: On-the-fly Decryption| Files