fscrypt

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, limitation of encrypted directory backup 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
mountpoint
where
mountpoint
is where the file system is mounted, e.g.
/home
.
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!
PAM module
To 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. 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.
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, be sure to follow the
security recommendations
.
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. While possible, it is not well supported, normally not desired and could led to later issues: It may not be noticed by the user, unless the according protector is locked or worse: deleted.
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