fscrypt - ArchWiki

Jump to content

# fscrypt

From ArchWiki

Related articles

- Data-at-rest encryption
- Ext4
- F2FS

fscrypt is a tool for managing the native file encryption support of the ext4, F2FS, UBIFS, CephFS and Lustre file systems.

The underlying encryption mechanism in the kernel, which is integrated into the above file systems, is also sometimes called "fscrypt". To avoid ambiguity, this article calls the kernel feature "Linux native file encryption". With Linux native file encryption, different directories can use different encryption keys. In an encrypted directory, all file contents, filenames, and symlinks are encrypted. All subdirectories are encrypted too. Non-filename metadata, such as timestamps, the sizes and number of files, and extended attributes, is not encrypted.

As this article assumes the use of the fscrypt tool (and optionally pam_fscrypt, which goes along with fscrypt), most of it is not applicable to other userspace tools that can set up Linux native file encryption, for example systemd-homed.

This article or section needs expansion.

Reason: A reference should be added for access semantics (multi-user system ACLs and ext4 fallback to data-ordered-mode). (Discuss in Talk:Fscrypt)

## Alternatives to consider

To protect an entire file system with one password, block device encryption with dm-crypt (LUKS) is generally a better option, as it ensures that all files on the file system are encrypted, and also that all file system metadata is encrypted. fscrypt is most useful to encrypt specific directories, or to enable different encrypted directories to be unlockable independently—for example, per-user encrypted home directories.

Compared to eCryptfs, the Linux native file encryption controlled by fscrypt does not use file system stacking, which makes it more memory-efficient. It also uses more up-to-date cryptography and does not require root privileges to set up, which avoids the need for setuid binaries. eCryptfs is also no longer being actively developed, and its largest users (Ubuntu and Chrome OS) have migrated to other solutions.

See data-at-rest encryption for more information about other encryption solutions, and about what encryption does and does not do.

Note

- It is possible to use fscrypt in combination with dm-crypt, with each encryption layer serving a different purpose. For example, the file system itself could be protected by dm-crypt using a less secure method, like a TPM tied into "secure boot" or a password known to all the system's users, while each user's home directory could also be protected by fscrypt using a password known only to that user.
- The e4crypt tool from e2fsprogs can be used as an alternative to the fscrypt tool. However, this is not recommended since e4crypt is missing many basic features and is no longer being actively developed.
- f2fscrypt from f2fs-tools is just a copy of e4crypt and likewise is not recommended.

## Preparations

### Kernel

All officially supported kernels support native file encryption on ext4, F2FS, UBIFS and CephFS.

Users of custom kernels, make sure `CONFIG_FS_ENCRYPTION=y` is set.

### File system

#### ext4

For ext4, the file system on which encryption is to be used must have the `encrypt` feature flag enabled. To enable it, run:

    # tune2fs -O encrypt /dev/device

Tip When creating a new file system, one can enable the `encrypt` feature immediately with `mkfs.ext4 -O encrypt`.

#### F2FS

For F2FS, use `mkfs.f2fs -O encrypt` when creating the file system or `fsck.f2fs -O encrypt` at a later time.

### Userspace tool

Install the fscrypt package. Then run:

    # fscrypt setup

This creates the file `/etc/fscrypt.conf` and the directory `/.fscrypt`.

Then, if the file system on which encryption is to be used is not the root file system, also run:

    # fscrypt setup --all-users mountpoint

where `mountpoint` is where the file system is mounted, e.g. `/home`.

The `--all-users` option enables users to select directories to encrypt. It is possible to start without it and change it later, see fscrypt documentation for more information.

This creates the directory `mountpoint/.fscrypt` to store fscrypt policies and protectors.

Warning

- Never delete the `.fscrypt` directory; otherwise all access to encrypted files will be lost!
- Extra consideration is required for backup, restore and recovery of encrypted directories; do test it!

### Auto-unlocking directories

To (optionally) unlock login passphrase-protected directories automatically at login, and to keep login passphrase-protected directories in sync with changes to the login passphrase, adjust the system PAM configuration to enable pam_fscrypt.

Append the following line to the auth section in `/etc/pam.d/system-login`:

    /etc/pam.d/system-login

    auth       optional   pam_fscrypt.so

Insert the following lines before `session include system-auth` in the session section:

    /etc/pam.d/system-login

    session    [success=1 default=ignore]  pam_succeed_if.so  service = systemd-user quiet
    session    optional                    pam_fscrypt.so

Note The first line, taken from https://github.com/google/fscrypt/issues/95, is a bypass for the `systemd --user` session which does not properly close its PAM session and would otherwise block the locking on logout.

Finally, append the following line to `/etc/pam.d/passwd`:

    /etc/pam.d/passwd

    password    optional    pam_fscrypt.so

## Encrypt a directory

To encrypt an empty directory, run:

    $ fscrypt encrypt dir

Follow the prompts to create or choose a "protector". A protector is the secret or information that protects the directory's encryption key. The types of protectors include:

- "custom_passphrase". This is exactly what it sounds like, a user defined passphrase.
- "pam_passphrase". This is the login passphrase for a particular user. Directories using this type of protector will be automatically unlocked by pam_fscrypt (if enabled) when that user logs in. While keeping in mind that Arch Linux changed to the yescrypt hashing algorithm, see the upstream security recommendations before using this type of protector.

In both cases, the passphrase can be changed later, or the directory can be re-protected with another method.

Example for custom passphrase:

    $ fscrypt encrypt private/

    Should we create a new protector? [y/N] y
    Your data can be protected with one of the following sources:
    1 - Your login passphrase (pam_passphrase)
    2 - A custom passphrase (custom_passphrase)
    3 - A raw 256-bit key (raw_key)
    Enter the source number for the new protector [2 - custom_passphrase]: 2
    Enter a name for the new protector: Super Secret
    Enter custom passphrase for protector "Super Secret":
    Confirm passphrase:
    "private/" is now encrypted, unlocked, and ready for use.

Example for PAM passphrase:

    $ fscrypt encrypt private/

    Should we create a new protector? [y/N] y
    Your data can be protected with one of the following sources:
    1 - Your login passphrase (pam_passphrase)
    2 - A custom passphrase (custom_passphrase)
    3 - A raw 256-bit key (raw_key)
    Enter the source number for the new protector [2 - custom_passphrase]: 1
    Enter login passphrase for testuser:
    "private/" is now encrypted, unlocked, and ready for use.

Note Encryption can only be enabled on an empty directory. To encrypt an existing directory, first copy the contents elsewhere and then delete the original files, e.g.:

    $ mkdir new_dir
    $ fscrypt encrypt new_dir
    $ cp -a -T old_dir new_dir
    $ find old_dir -type f -print0 | xargs -0 shred -n1 --remove=unlink
    $ rm -rf old_dir

Beware of moving files (command mv), instead of copying, because the unencrypted files will be easily recoverable. In some cases they may even be forensically recoverable from disk after being shredded and deleted, especially if using an SSD. It is better to encrypt data from the start.

## Lock/unlock a directory

To unlock an encrypted directory, run:

    $ fscrypt unlock dir

fscrypt will prompt for the passphrase.

To lock an encrypted directory, run:

    $ fscrypt lock dir

## Encrypt a home directory

Warning

- Login protectors are only as secure as the system's passphrase hashing in `/etc/shadow`. Before using a login protector, see the information in #Encrypt a directory.
- If a user's home directory is encrypted, SSH for that user may not work until their home directory has been unlocked.

To encrypt a user's home directory, first ensure that all preparations have been completed, including enabling pam_fscrypt.

Then, create a new encrypted directory for the user:

    # mkdir /home/newhome
    # chown user:user /home/newhome
    # fscrypt encrypt /home/newhome --user=user

Select the option to protect the directory with the user's login passphrase.

Then copy the contents of the user's old home directory into the encrypted directory:

    # cp -a -T /home/user /home/newhome

Tip If there is not enough disk space for a second copy of the home directory, consider using `mv -T /home/user /home/newhome` instead. However, this is unsafe. Making a backup first is strongly recommended.

If the cp method was used, check whether the directory is being automatically unlocked on login before actually switching to using it. The simplest way to do this is to reboot and log in as that user. Afterwards, run:

    $ fscrypt status /home/newhome

    "/home/newhome" is encrypted with fscrypt.

    Policy:   d80f252996aae181204403043b0ada25
    Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2
    Unlocked: Yes

    Protected with 1 protector:
    PROTECTOR         LINKED  DESCRIPTION
    5952c84ebaf0f98d  No      login protector for testuser

If it says `Unlocked: No` instead, then something is wrong with the PAM configuration, or the incorrect type of protector was selected.

Otherwise, replace the home directory:

    # mv /home/user /home/oldhome
    # mv /home/newhome /home/user
    # reboot

If everything is working as expected, delete the old home directory:

    # find /home/oldhome -type f -print0 | xargs -0 shred -n1 --remove=unlink
    # rm -rf /home/oldhome

Tip Running shred is optional, but strongly recommended.

## Encryption within Linux Containers (lxc)

Support to use fscrypt inside Linux Containers (lxc), or more generally in mount_namespaces(7) where the file system's root directory is not visible has been added in v0.2.8.

### Lock directory when container is stopped

A systemd/User unit within the container can lock an encrypted directory when the container is stopped:

    ~/.config/systemd/user/lock-directory.service

    [Unit]
    Description=lock encrypted directory on shutdown
    DefaultDependencies=no
    Before=shutdown.target

    [Service]
    Type=oneshot
    ExecStart=/bin/sh -c "/usr/bin/fscrypt lock /home/facade/target"
    TimeoutStartSec=0

    [Install]
    WantedBy=shutdown.target

## Troubleshooting

See https://github.com/google/fscrypt/blob/master/README.md#troubleshooting for solutions to some common problems and also the open issues on Github.

### ext4: Encrypted files outside fscrypt encrypted directory

Encrypted regular files from an unlocked fscrypt can be moved into an unencrypted directory, but is not well supported and can lead to subsequent issues when the according protector is locked, or even data loss if it is deleted. See https://github.com/google/fscrypt/issues/393.

If you want to decrypt files permanently, copy them from the unlocked fscrypt directory into a regular unencrypted directory.[1].

## See also

- Documentation for the fscrypt tool
- Documentation for Linux native file encryption
- The design document for the fscrypt tool

Category:

- Data-at-rest encryption

Hidden category:

- Pages or sections flagged with Template:Expansion

fscrypt
Add topic