The ext4, F2FS, and UBIFS file systems natively support file encryption via a common API called fscrypt (originally called "ext4 encryption"). With fscrypt, encryption is applied at the directory level. 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.
fscrypt is also the name of a userspace tool to use the kernel feature of the same name. This article shows how to use the fscrypt tool to encrypt directories, including how to encrypt a home directory.
- 1 Alternatives to consider
- 2 Preparations
- 3 Encrypt a directory
- 4 Manually unlock a directory
- 5 Encrypt a home directory
- 6 Encryption within Linux Containers (lxc)
- 7 Troubleshooting
- 8 See also
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 filesystem 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.
Unlike eCryptfs, fscrypt is not a stacked file system, i.e. it is supported by file systems natively. This makes fscrypt more memory-efficient. fscrypt also uses more up-to-date cryptography than eCryptfs, and it does not require setuid binaries. Also, eCryptfs is no longer being actively developed, and its largest users have migrated to dm-crypt (Ubuntu) or to fscrypt (Chrome OS).
See data-at-rest encryption for more information about other encryption solutions, and about what encryption does and does not do.
- 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.
e4crypttool from can be used as an alternative to the
fscrypttool. However, this is not recommended since
e4cryptis missing many basic features and is no longer being actively developed.
All officially supported kernels support fscrypt on ext4, F2FS, and UBIFS.
Users of custom kernels version 5.1 or later, make sure
CONFIG_FS_ENCRYPTION=y is set. For older kernels, see the documentation.
For ext4, the file system on which encryption is to be used must have the
encrypt feature flag enabled. To do this, check that file system uses page-sized blocks:
# tune2fs -l /dev/device | grep 'Block size'
Block size: 4096
# getconf PAGE_SIZE
If these values differ, the file system will not support encryption, so do not proceed further.
To enable the
encrypt feature on the file system, run:
# tune2fs -O encrypt /dev/device
encryptfeature is enabled, Linux versions older than 4.1 will be unable to mount the file system.
- The operation can be undone with
debugfs -w -R "feature -encrypt" /dev/device. Run fsck before and after to ensure the integrity of the file system.
- When creating a new file system, one can enable the
encryptfeature immediately with
mkfs.ext4 -O encrypt -b 4096.
For F2FS, use
mkfs.f2fs -O encrypt when creating the file system or
fsck.f2fs -O encrypt at a later time.
Install the package. Then run:
# fscrypt setup
This creates the file
/etc/fscrypt.conf and the directory
Then, if the file system on which encryption is to be used is not the root file system, also run:
# fscrypt setup mountpoint
mountpoint is where the file system is mounted, e.g.
This creates the directory
mountpoint/.fscrypt to store fscrypt policies and protectors.
.fscryptdirectory; otherwise ALL access to encrypted files will be lost!
To unlock login passphrase-protected directories automatically at login, and to keep login passphrase-protected directories in sync with changes to the login passphrase, edit the system's PAM configuration to enable
/etc/pam.d/system-login, append the following line to the "auth" section:
auth optional pam_fscrypt.so
/etc/pam.d/system-login, append the following line to the "session" section:
session optional pam_fscrypt.so drop_caches lock_policies
Finally, append the following line to
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. Be sure to follow the 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.
$ 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_dirBeware that the original unencrypted files may still be forensically recoverable from disk even after being shredded and deleted, especially if using an SSD. It is better to encrypt data from the start.
Manually unlock a directory
To manually unlock an encrypted directory, run:
$ fscrypt unlock dir
fscrypt will prompt for the passphrase.
Encrypt a home directory
- Login protectors are only as secure as the system's passphrase hashing in
/etc/shadow. Before using a login protector, be sure to follow the security recommendations.
- If a user's home directory is encrypted, ssh'ing to that user will 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
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
mv -T /home/user /home/newhomeinstead. However, this is unsafe. Making a backup first is strongly recommended.
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
Encryption within Linux Containers (lxc)
Support to use fscrypt inside Linux Containers (lxc), or more generally in 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:
[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
See https://github.com/google/fscrypt/blob/master/README.md#troubleshooting for solutions to some common problems and also the open issues on Github.