Repository files navigation

fscrypt is a high-level tool for the management ofLinux native filesystemencryption.fscrypt manages metadata, key generation, key wrapping, PAM integration, andprovides a uniform interface for creating and modifying encrypted directories.For a small low-level tool that directly sets policies, seefscryptctl.

To usefscrypt, you must have a filesystem that supports the Linux nativefilesystem encryption API (which is also sometimes called "fscrypt"; thisdocumentation calls it "Linux native filesystem encryption" to avoid confusion).Only certain filesystems, such asext4 andf2fs, support this API. For a full listof supported filesystems and how to enable encryption support on each one, seeRuntime dependencies.

For the release notes, see theNEWS file.

• Alternatives to consider
• Threat model
• Features
• Building and installing
• Runtime dependencies
• Configuration file
• Setting upfscrypt on a filesystem
• Setting up for login protectors
  • Securing your login passphrase
  • Enabling the PAM module
    • Enabling the PAM module on Debian or Ubuntu
    • Enabling the PAM module on Arch Linux
    • Enabling the PAM module on other Linux distros
  • Allowingfscrypt to check your login passphrase
• Backup, restore, and recovery
• Encrypting existing files
• Example usage
  • Setting up fscrypt on a directory
  • Locking and unlocking a directory
  • Protecting a directory with your login passphrase
  • Changing a custom passphrase
  • Using a raw key protector
  • Using multiple protectors for a policy
• Contributing
• Troubleshooting
  • I changed my login passphrase, now all my directories are inaccessible
  • Directories using my login passphrase are not automatically unlocking
  • Getting "encryption not enabled" on an ext4 filesystem
  • Getting "user keyring not linked into session keyring"
  • Getting "Operation not permitted" when moving files into an encrypted directory
  • Getting "Package not installed" when trying to use an encrypted directory
  • Some processes can't access unlocked encrypted files
  • Users can access other users' unlocked encrypted files
  • Getting "Required key not available" when backing up locked encrypted files
  • The reported size of encrypted symlinks is wrong
• Legal

Operating-system level storage encryption solutions work at either thefilesystem or block device level.Linux native filesystemencryption(the solution configured byfscrypt) is filesystem-level; it encryptsindividual directories. Only file contents and filenames are encrypted;non-filename metadata, such as timestamps, the sizes and number of files, andextended attributes, isnot encrypted. Users choose which directories willbe encrypted, and with what keys.

Before usingfscrypt, you should consider other solutions:

• dm-crypt/LUKS is block devicelevel encryption: it encrypts an entire block device (and hence an entirefilesystem) with one key. Unlocking this key will unlock the entire blockdevice. dm-crypt/LUKS is usually configured usingcryptsetup.

• systemd-homed supports encrypting homedirectories using the same Linux native filesystem encryption API thatfscrypt uses. Note that while thesystemd-homed documentation refers tothis as fscrypt support, it does not use thefscrypt tool; directories setup usingsystemd-homed cannot be managed byfscrypt and vice versa.systemd-homed has better integration with systemd thanfscrypt does.However,systemd-homed (as of systemd v255) uses the"V1" Linux kernel encryption API,whilefscrypt prefers the "V2" API. The older API causesknown issues, andmigratingsystemd-home to the "V2" API is trackedin thissystemd issue.Issues withsystemd-homed should be reported to the systemd developers.

• eCryptfs is an alternativefilesystem-level encryption solution. It is a stacked filesystem, which meansit sits on top of a real filesystem, rather than being directly integratedinto the real filesystem. Stacked filesystems have a couple advantages (suchas working on almost any real filesystem), but also some significantdisadvantages. eCryptfs is usually configured usingecryptfs-utils.

• Some Linux filesystems support encryption natively, but not in a way that iscompatible with the common API thatfscrypt uses. Examples of this areBcachefs and ZFS. (Note: ZFS is not part of the upstream kernel.) Bcachefsencryption is similar to dm-crypt in that it encrypts the full filesystem withone key. ZFS encryption operates on a per-dataset basis. If you are usingone of these filesystems, refer to the documentation for that filesystem.

Which solution to use? Here are our recommendations:

• eCryptfs shouldn't be used, if at all possible. eCryptfs's use of filesystemstacking causes a number of issues, and eCryptfs is no longer activelymaintained. The original author of eCryptfs recommends using Linux nativefilesystem encryption instead. The largest users of eCryptfs (Ubuntu andChrome OS) have switched to dm-crypt or Linux native filesystem encryption.

• If you need fine-grained control of encryption within a filesystem and you areusing a filesystem that supportsfscrypt, then usefscrypt, orfscrypttogether with dm-crypt/LUKS. If you don't need this, then use dm-crypt/LUKS.

  To understand this recommendation: consider that the main advantage offscrypt is to allow different files on the same filesystem to be encryptedby different keys, and thus be unlockable, lockable, and securely deletableindependently from each other. Therefore,fscrypt is useful in cases suchas:

  • Multi-user systems, since each user's files can be encrypted with theirown key that is unlocked by their own passphrase.

  • Single-user systems where it's not possible for all files to have thestrongest level of protection. For example, it might be necessary for thesystem to boot up without user interaction. Any files that are needed todo so can only be encrypted by a hardware-protected (e.g. TPM-bound) keyat best. If the user's personal files are located on the same filesystem,then with dm-crypt/LUKS the user's personal files would be limited to thisweak level of protection. Withfscrypt, the user's personal files couldbe fully protected using the user's passphrase.

  fscrypt isn't very useful in the following cases:

  • Single-user systems where the user is willing to enter a strong passphraseat boot time to unlock the entire filesystem. In this case, the mainadvantage offscrypt would go unused, so dm-crypt/LUKS would be betteras it would provide better security (due to ensuring that all files andall filesystem metadata are encrypted).

  • Any case where it is feasible to create a separate filesystem for everyencryption key you want to use.

  Note: dm-crypt/LUKS andfscrypt aren't mutually exclusive; they can be usedtogether when the performance hit of double encryption is tolerable. It onlymakes sense to do this when the keys for each encryption layer are protectedin different ways, such that each layer serves a different purpose. Areasonable set-up would be to encrypt the whole filesystem with dm-crypt/LUKSusing a TPM-bound key that is automatically unlocked at boot time, and alsoencrypt users' home directories withfscrypt using their login passphrases.

Like other storage encryption solutions (including dm-crypt/LUKS and eCryptfs),Linux native filesystem encryption is primarily intended to protect theconfidentiality of data from a single point-in-time permanent offline compromiseof the disk. For a detailed description of the threat model, see thekerneldocumentation.

It's worth emphasizing that none of these encryption solutions protect unlockedencrypted files from other users on the same system (that's the job of OS-levelaccess control, such as UNIX file permissions), or from the cloud provider youmay be running a virtual machine on. By themselves, they also do not protectfrom "evil maid" attacks, i.e. non-permanent offline compromises of the disk.

fscrypt is intended to improve upon the work ine4crypt by providing amore managed environment and handling more functionality in the background.fscrypt has adesign document specifying its fullarchitecture. See also thekernel documentation for Linux native filesystemencryption.

Briefly,fscrypt deals with protectors and policies. Protectors represent somesecret or information used to protect the confidentiality of your data. Thethree currently supported protector types are:

1. Your login passphrase, throughPAM.The included PAM module (pam_fscrypt.so) can automatically unlockdirectories protected by your login passphrase when you log in, and lock themwhen you log out.IMPORTANT: before using a login protector, followSetting up for login protectors.

2. A custom passphrase. This passphrase is hashed withArgon2id, by default calibrated touse all CPUs and take about 1 second.

3. A raw key file. SeeUsing a raw key protector.

These protectors are mutable, so the information can change without needing toupdate any of your encrypted directories.

Policies represent the actual key passed to the kernel. This "policy key" isimmutable and policies are (usually) applied to a single directory. Protectorsthen protect policies, so that having one of the protectors for a policy isenough to get the policy key and access the data. Which protectors protect apolicy can also be changed. This allows a user to change how a directory isprotected without needing to reencrypt the directory's contents.

Concretely,fscrypt contains the following functionality:

• fscrypt setup - Creates/etc/fscrypt.conf and the/.fscrypt directory
  • This is the only functionality which always requires root privileges
• fscrypt setup MOUNTPOINT - Gets a filesystem ready for use with fscrypt
• fscrypt encrypt DIRECTORY - Encrypts an empty directory
• fscrypt unlock DIRECTORY - Unlocks an encrypted directory
• fscrypt lock DIRECTORY - Locks an encrypted directory
• fscrypt purge MOUNTPOINT - Locks all encrypted directories on a filesystem
• fscrypt status [PATH] - Gets detailed info about filesystems or paths
• fscrypt metadata - Manages policies or protectors directly

See the example usage section below or runfscrypt COMMAND --help for moreinformation about each of the commands.

fscrypt has a minimal set of build dependencies:

• Go 1.18 or higher. Older versions may workbut they are not tested or supported.
• A C compiler (gcc orclang)
• make
• Headers forlibpam.Install them with the appropriate package manager:
  • Debian/Ubuntu:sudo apt install libpam0g-dev
  • Red Hat:sudo yum install pam-devel
  • Arch:pampackage (usually installed by default)

Once all the dependencies are installed, clone the repository by running:

git clone https://github.com/google/fscrypt

Runningmake builds the binary (fscrypt) and PAM module (pam_fscrypt.so)in thebin/ directory.

Runningsudo make install installsfscrypt into/usr/local/bin,pam_fscrypt.so into/usr/local/lib/security, andpam_fscrypt/config into/usr/local/share/pam-configs.

On Debian (and Debian derivatives such as Ubuntu), usesudo make install PREFIX=/usr to install into/usr instead of the default of/usr/local.Ordinarily you shouldn't manually install software into/usr, since/usr isreserved for Debian's own packages. However, Debian's PAM configurationframework only recognizes configuration files in/usr, not in/usr/local.Therefore, the PAM module will only work if you install into/usr. Note: ifyou later decide to switch to using the Debian packagelibpam-fscrypt, you'llhave to first manually runsudo make uninstall PREFIX=/usr.

It is also possible to usemake install-bin to only install thefscryptbinary, ormake install-pam to only install the PAM files.

Alternatively, if you only want to install thefscrypt binary to$GOPATH/bin, simply run:

go install github.com/google/fscrypt/cmd/fscrypt@latest

See theMakefile for instructions on how to further customize the build.

To run,fscrypt needs the following libraries:

• libpam.so (almost certainly already on your system)

In addition,fscrypt requires a filesystem that supports the Linux nativefilesystem encryption API. Currently, the filesystems that support this are:

• ext4, with upstream kernel v4.1 or later. The kernel configuration mustcontainCONFIG_FS_ENCRYPTION=y (for kernels v5.1+) orCONFIG_EXT4_ENCRYPTION=y or=m (for older kernels). The filesystem mustalso have theencrypt feature flag enabled; to enable this flag, seehere.

• f2fs, with upstream kernel v4.2 or later. The kernel configuration mustcontainCONFIG_FS_ENCRYPTION=y (for kernels v5.1+) orCONFIG_F2FS_FS_ENCRYPTION=y (for older kernels). The filesystem must alsohave theencrypt feature flag enabled; this flag can be enabled at formattime bymkfs.f2fs -O encrypt or later byfsck.f2fs -O encrypt.

• UBIFS, with upstream kernel v4.10 or later. The kernel configuration mustcontainCONFIG_FS_ENCRYPTION=y (for kernels v5.1+) orCONFIG_UBIFS_FS_ENCRYPTION=y (for older kernels).

• CephFS, with upstream kernel v6.6 or later. The kernel configuration mustcontainCONFIG_FS_ENCRYPTION=y.

• Lustre, with Lustre v2.14.0 or later. For details,see the Lustre documentation. Please note that Lustre is not part of theupstream Linux kernel, and its encryption implementation has not been reviewedby the authors offscrypt. Questions/issues about Lustre encryption shouldbe directed to the Lustre developers. Lustre version 2.14 does not encryptfilenames, even though it claims to, so v2.15.0 or later should be used.

To check whether the needed option is enabled in your kernel, run:

zgrep -h ENCRYPTION /proc/config.gz /boot/config-$(uname -r)| sort| uniq

It is also recommended to use Linux kernel v5.4 or later, since thisallows the use of v2 encryption policies. v2 policies have severalsecurity and usability improvements over v1 policies.

If you configurefscrypt to use non-default features, other kernelprerequisites may be needed too. SeeConfigurationfile.

Runningsudo fscrypt setup will create the configuration file/etc/fscrypt.conf if it doesn't already exist. It's a JSON filethat looks like the following:

{"source": "custom_passphrase","hash_costs": {"time": "52","memory": "131072","parallelism": "32"},"options": {"padding": "32","contents": "AES_256_XTS","filenames": "AES_256_CTS","policy_version": "2"},"use_fs_keyring_for_v1_policies": false,"allow_cross_user_metadata": false}

The fields are:

• "source" is the default source for new protectors. The choices are"pam_passphrase", "custom_passphrase", and "raw_key".

• "hash_costs" describes how difficult the passphrase hashing is.By default,fscrypt setup calibrates the hashing to use all CPUsand take about 1 second. The--time option tofscrypt setup canbe used to customize this time when creating the configuration file.

• "options" are the encryption options to use for new encrypteddirectories:

  • "padding" is the number of bytes by which filenames are paddedbefore being encrypted. The choices are "32", "16", "8", and"4". "32" is recommended.

  • "contents" is the algorithm used to encrypt file contents. Thechoices are "AES_256_XTS", "AES_128_CBC", and "Adiantum".Normally, "AES_256_XTS" is recommended.

  • "filenames" is the algorithm used to encrypt file names. Thechoices are "AES_256_CTS", "AES_128_CTS", "Adiantum", and"AES_256_HCTR2". Normally, "AES_256_CTS" is recommended.

    To use algorithms other than "AES_256_XTS" for contents and"AES_256_CTS" for filenames, the needed algorithm(s) may need tobe enabled in the Linux kernel's cryptography API. For example,to use Adiantum,CONFIG_CRYPTO_ADIANTUM must be set. Also,not all combinations of algorithms are allowed; for example,"Adiantum" for contents can only be paired with "Adiantum" forfilenames. See thekerneldocumentationfor more details about the supported algorithms.

  • "policy_version" is the version of encryption policy to use.The choices are "1" and "2". If unset, "1" is assumed.Directories created with policy version "2" are only usable onkernel v5.4 or later, but are preferable to version "1" if youdon't mind this restriction.

• "use_fs_keyring_for_v1_policies" specifies whether to add keys for v1encryption policies to the filesystem keyrings, rather than to user keyrings.This can solveissues with processes being unable to access unlockedencrypted files.However, it requires kernel v5.4 or later, and it makes unlocking and lockingencrypted directories require root. (The PAM module will still work.)

  The purpose of this setting is to allow people to take advantage of some ofthe improvements in Linux v5.4 on encrypted directories that are alsocompatible with older kernels. If you don't need compatibility with olderkernels, it's better to not use this setting and instead (re-)create yourencrypted directories with"policy_version": "2".

• "allow_cross_user_metadata" specifies whetherfscrypt will allowprotectors and policies from other non-root users to be read, e.g. to beoffered as options byfscrypt encrypt. The default value isfalse, sinceother users might be untrusted and could create malicious files. This can beset totrue to restore the old behavior on systems wherefscrypt metadataneeds to be shared between multiple users. Note that this option isindependent from the permissions on the metadata files themselves, which areset to 0600 by default; users who wish to share their metadata files withother users would also need to explicitly change their mode to 0644.

fscrypt needs some directories to exist on the filesystem on which encryptionwill be used:

• MOUNTPOINT/.fscrypt/policies
• MOUNTPOINT/.fscrypt/protectors

(If login protectors are used, these must also exist on the root filesystem.)

To create these directories, runfscrypt setup MOUNTPOINT. If MOUNTPOINT isowned by root, as is usually the case, then this command will require root.

There will be one decision you'll need to make: whether non-root users will beallowed to createfscrypt metadata (policies and protectors).

If you sayy, then these directories will be made world-writable, with thesticky bit set so that users can't delete each other's files -- just like/tmp. If you sayN, then these directories will be writable only by root.

Sayingy maximizes the usability offscrypt, and on most systems it's fineto sayy. However, on some systems this may be inappropriate, as it willallow malicious users to fill the entire filesystem unless filesystem quotashave been configured -- similar to problems that have historically existed withother world-writable directories, e.g./tmp. If you are concerned about this,sayN. If you sayN, then you'll only be able to runfscrypt as root toset up encryption on users' behalf, unless you manually set custom permissionson the metadata directories to grant write access to specific users or groups.

If you chose the wrong mode atfscrypt setup time, you can change thedirectory permissions at any time. To enable single-user writable mode, run:

sudo chmod 0755 MOUNTPOINT/.fscrypt/*

To enable world-writable mode, run:

sudo chmod 1777 MOUNTPOINT/.fscrypt/*

If you want any encrypted directories to be protected by your login passphrase,you'll need to:

1. Secure your login passphrase (optional, but strongly recommended)
2. Enable the PAM module (pam_fscrypt.so)

If you installedfscrypt from source rather than from your distro's packagemanager, you may also need to allowfscrypt to check your login passphrase.

Althoughfscrypt uses a strong passphrase hash algorithm, the security oflogin protectors is also limited by the strength of your system's passphrasehashing in/etc/shadow. On most Linux distributions,/etc/shadow by defaultuses SHA-512 with 5000 rounds, which is much weaker than whatfscrypt uses.

To mitigate this, you should use a strong login passphrase.

If using a strong login passphrase is annoying because it needs to be enteredfrequently to runsudo, consider increasing thesudo timeout. That can bedone by adding the following to/etc/sudoers:

Defaults timestamp_timeout=60

You should also increase the number of rounds that your system's passphrasehashing uses (though this doesn't increase security as much as choosing a strongpassphrase). To do this, find the line in/etc/pam.d/passwd that looks like:

passwordrequiredpam_unix.so sha512 shadow nullok

Appendrounds=1000000 (or another number of your choice; the goal is to makethe passphrase hashing take about 1 second, similar tofscrypt's default):

passwordrequiredpam_unix.so sha512 shadow nullok rounds=1000000

Then, change your login passphrase to a new, strong passphrase:

passwd

If you'd like to keep the same login passphrase (not recommended, as the oldpassphrase hash may still be recoverable from disk), then instead runsudo passwd $USER and enter your existing passphrase. This re-hashes yourexisting passphrase with the newrounds.

To enable the PAM modulepam_fscrypt.so, follow the directions for your Linuxdistro below. Enabling the PAM module is needed for login passphrase-protecteddirectories to be automatically unlocked when you log in (and be automaticallylocked when you log out), and for login passphrase-protected directories toremain accessible when you change your login passphrase.

The officiallibpam-fscrypt package for Debian (and Debian derivatives such asUbuntu) will install a configuration file forDebian's PAM configurationframework to/usr/share/pam-configs/fscrypt. This file contains reasonable defaults forthe PAM module. To automatically apply these defaults, runsudo pam-auth-update and follow the on-screen instructions.

This file also gets installed if you build and installfscrypt from source,but it is only installed to the correct location if you usemake install PREFIX=/usr to install into/usr instead of the default of/usr/local.

On Arch Linux, follow the recommendations at theArch LinuxWiki.

We recommend using the Arch Linux package, eitherfscrypt (official) orfscrypt-git (AUR). If you instead installfscrypt manually usingsudo make install, then in addition to the steps on the Wiki you'll also need tocreate/etc/pam.d/fscrypt.

On all other Linux distros, follow the general guidance below to edityour PAM configuration files.

Thefscrypt PAM module implements the Auth, Session, and Passwordtypes.

The Password functionality ofpam_fscrypt.so is used to automatically rewrapa user's login protector when their unix passphrase changes. An easy way to getthe working is to add the line:

password    optional    pam_fscrypt.so

afterpam_unix.so in/etc/pam.d/common-password or similar.

The Auth and Session functionality ofpam_fscrypt.so are used to automaticallyunlock directories when logging in as a user, and lock them when logging out.An easy way to get this working is to add the line:

auth        optional    pam_fscrypt.so

afterpam_unix.so in/etc/pam.d/common-auth or similar, and to add theline:

session     optional    pam_fscrypt.so

afterpam_unix.so in/etc/pam.d/common-session or similar, but beforepam_systemd.so or any other module that accesses the user's home directory orwhich starts processes that access the user's home directory during theirsession.

pam_fscrypt.so accepts several options:

• debug: print additional debug messages to the syslog. All hook types acceptthis option.

• unlock_only: only unlock directories (at log-in); don't also lock them (atlog-out). This is only relevant for the "session" hook. Note that infscrypt v0.2.9 and earlier, unlock-only was the default behavior, andlock_policies needed to be specified to enable locking.

This step is only needed if you installedfscrypt from source code.

Some Linux distros use restrictive settings in/etc/pam.d/other that preventprograms from checking your login passphrase unless a per-program PAMconfiguration file grants access. This preventsfscrypt from creating anylogin passphrase-protected directories, even without auto-unlocking. To ensurethatfscrypt will work properly (if you didn't install an officialfscryptpackage from your distro, which should have already handled this), also create afile/etc/pam.d/fscrypt containing:

auth        required    pam_unix.so

Encrypted files and directories can't be backed up while they are "locked", i.e.while they appear in encrypted form. They can only be backed up while they areunlocked, in which case they can be backed up like any other files. Note thatsince the encryption is transparent, the files won't be encrypted in the backup(unless the backup applies its own encryption).

For the same reason (and several others), an encrypted directory can't bedirectly "moved" to another filesystem. However, it is possible to create a newencrypted directory on the destination filesystem usingfscrypt encrypt, thencopy the contents of the source directory into it.

For directories protected by acustom_passphrase orraw_key protector, allmetadata needed to unlock the directory (excluding the actual passphrase or rawkey, of course) is located in the.fscrypt directory at the root of thefilesystem that contains the encrypted directory. For example, if you have anencrypted directory/home/$USER/private that is protected by a custompassphrase, allfscrypt metadata needed to unlock the directory with thatcustom passphrase will be located in/home/.fscrypt if you are using adedicated/home filesystem or in/.fscrypt if you aren't. If desired, youcan back up thefscrypt metadata by making a copy of this directory, althoughthis isn't too important since this metadata is located on the same filesystemas the encrypted directory(s).

pam_passphrase (login passphrase) protectors are a bit different as they arealways stored on the root filesystem, in/.fscrypt. This ties them to thespecific system and ensures that each user has only a single login protector.Therefore, encrypted directories on a non-root filesystemcan't be unlockedvia a login protector if the operating system is reinstalled or if the disk isconnected to another system -- even if the new system uses the same loginpassphrase for the user.

Because of this,fscrypt encrypt will automatically generate a recoverypassphrase when creating a login passphrase-protected directory on a non-rootfilesystem. The recovery passphrase is simply acustom_passphrase protectorwith a randomly generated high-entropy passphrase. Initially, the recoverypassphrase is stored in a file in the encrypted directory itself; therefore, touse it youmust record it in another secure location. It is stronglyrecommended to do this. Then, if ever needed, you can usefscrypt unlock tounlock the directory with the recovery passphrase (by choosing the recoveryprotector instead of the login protector).

If you really want to disable the generation of a recovery passphrase, use the--no-recovery option. Only do this if you really know what you are doing andare prepared for potential data loss.

Alternative approaches to supporting recovery of login passphrase-protecteddirectories include the following:

• Manually adding your own recovery protector, usingfscrypt metadata add-protector-to-policy.

• Backing up and restoring the/.fscrypt directory on the root filesystem.Note that after restoring the/.fscrypt directory, unlocking the loginprotectors will require the passphrases they had at the time the backup wasmadeeven if they were changed later, so make sure to remember thesepassphrase(s) or record them in a secure location. Also note that if the UUIDof the root filesystem changed, you will need to manually fix the UUID in any.fscrypt/protectors/*.link files on other filesystems.

The auto-generated recovery passphrases should be enough for most users, though.

fscrypt isn't designed to encrypt existing files, as this presents significanttechnical challenges and usually is impossible to do securely. Therefore,fscrypt encrypt only works on empty directories.

Of course, it is still possible to create an encrypted directory, copy filesinto it, and delete the original files. Themv command will even work, as itwill fall back to a copy and delete (except on olderkernels).However, beware that due to the characteristics of filesystems and storagedevices, this may not properly protect the files, as their original contents maystill be forensically recoverable from disk even after being deleted. It'smuch better to encrypt files from the very beginning.

There are only a few cases where copying files into an encrypted directory canreally make sense, such as:

• The source files are located on an in-memory filesystem such astmpfs.

• The confidentiality of the source files isn't important, e.g. they aresystem default files and the user hasn't added any personal files yet.

• The source files are protected by a differentfscrypt policy, the old andnew policies are protected by only the same protector(s), and the old policyuses similar strength encryption.

If one of the above doesn't apply, then it's probably too late to securelyencrypt your existing files.

As a best-effort attempt, you can use theshred program to try to erase theoriginal files. Here are the recommended commands for "best-effort" encryptionof an existing directory named "dir":

mkdir dir.newfscrypt encrypt dir.newcp -a -T dir dir.newfind dir -type f -print0| xargs -0 shred -n1 --remove=unlinkrm -rf dirmv dir.new dir

However, beware thatshred isn't guaranteed to be effective on all storagedevices and filesystems. For example, if you're using an SSD, "overwrites" ofdata typically go to new flash blocks, so they aren't really overwrites.

Note: for reasons similar to the above, changed or removedfscrypt protectorsaren't guaranteed to be forensically unrecoverable from disk either. Thus, theuse of weak or default passphrases should be avoided, even if changed later.

All these examples assume there is an ext4 filesystem which supportsencryption mounted at/mnt/disk. Seehere for howto enable encryption support on an ext4 filesystem.

# Check which directories on our system support encryption>>>>> fscrypt statusfilesystems supporting encryption: 1filesystems with fscrypt metadata: 0MOUNTPOINT  DEVICE     FILESYSTEM  ENCRYPTION   FSCRYPT/           /dev/sda1  ext4        not enabled  No/mnt/disk   /dev/sdb   ext4        supported    No# Create the global configuration file. Nothing else necessarily needs root.>>>>> sudo fscrypt setupDefaulting to policy_version 2 because kernel supports it.Customizing passphrase hashing difficultyfor this system...Created global config file at"/etc/fscrypt.conf".Allow users other than root to create fscrypt metadata on the root filesystem?(See https://github.com/google/fscrypt#setting-up-fscrypt-on-a-filesystem) [y/N] yMetadata directories created at"/.fscrypt", writable by everyone.# Start using fscrypt with our filesystem>>>>> sudo fscrypt setup /mnt/diskAllow users other than root to create fscrypt metadata on this filesystem? (Seehttps://github.com/google/fscrypt#setting-up-fscrypt-on-a-filesystem) [y/N] yMetadata directories created at"/mnt/disk/.fscrypt", writable by everyone.# Initialize encryption on a new empty directory>>>>> mkdir /mnt/disk/dir1>>>>> fscrypt encrypt /mnt/disk/dir1The following protector sources are available:1 - Your login passphrase (pam_passphrase)2 - A custom passphrase (custom_passphrase)3 - A raw 256-bit key (raw_key)Enter thesource numberfor the new protector [2 - custom_passphrase]: 2Enter a namefor the new protector: Super SecretEnter custom passphrasefor protector"Super Secret":Confirm passphrase:"/mnt/disk/dir1" is now encrypted, unlocked, and readyfor use.# We can see this created one policy and one protector for this directory>>>>> fscrypt status /mnt/diskext4 filesystem"/mnt/disk" has 1 protector and 1 policyPROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret"POLICY                            UNLOCKED  PROTECTORS16382f282d7b29ee27e6460151d03382  Yes       7626382168311a9d

>>>>> sudo fscrypt setup --quiet --force --all-users>>>>> sudo fscrypt setup /mnt/disk --quiet --all-users>>>>>echo"hunter2"| fscrypt encrypt /mnt/disk/dir1 --quiet --source=custom_passphrase  --name="Super Secret"

# Write a file to our encrypted directory.>>>>>echo"Hello World"> /mnt/disk/dir1/secret.txt>>>>> fscrypt status /mnt/disk/dir1"/mnt/disk/dir1" is encrypted with fscrypt.Policy:   16382f282d7b29ee27e6460151d03382Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: YesProtected with 1 protector:PROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret"# Lock the directory.  Note: if using a v1 encryption policy instead# of v2, you'll need 'sudo fscrypt lock /mnt/disk/dir1 --user=$USER'.>>>>> fscrypt lock /mnt/disk/dir1"/mnt/disk/dir1" is now locked.>>>>> fscrypt status /mnt/disk/dir1"/mnt/disk/dir1" is encrypted with fscrypt.Policy:   16382f282d7b29ee27e6460151d03382Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: NoProtected with 1 protector:PROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret"# Now the filenames and file contents are inaccessible>>>>> ls /mnt/disk/dir1u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P>>>>> cat /mnt/disk/dir1/u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4Pcat: /mnt/disk/dir1/u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P: Required key not available# Unlocking the directory makes the contents available>>>>> fscrypt unlock /mnt/disk/dir1Enter custom passphrasefor protector"Super Secret":"/mnt/disk/dir1" is now unlocked and readyfor use.>>>>> fscrypt status /mnt/disk/dir1"/mnt/disk/dir1" is encrypted with fscrypt.Policy:   16382f282d7b29ee27e6460151d03382Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: YesProtected with 1 protector:PROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret">>>>> cat /mnt/disk/dir1/secret.txtHello World

>>>>> fscrypt lock /mnt/disk/dir1 --quiet>>>>>echo"hunter2"| fscrypt unlock /mnt/disk/dir1 --quiet

First, ensure that you have properlyset up your system for loginprotectors.

Then, you can protect directories with your login passphrase as follows:

# Select your login passphrase as the desired source.>>>>> mkdir /mnt/disk/dir2>>>>> fscrypt encrypt /mnt/disk/dir2Should we create a new protector? [y/N] yThe following protector sources are available:1 - Your login passphrase (pam_passphrase)2 - A custom passphrase (custom_passphrase)3 - A raw 256-bit key (raw_key)Enter thesource numberfor the new protector [2 - custom_passphrase]: 1Enter login passphrasefor joerichey:"/mnt/disk/dir2" is now encrypted, unlocked, and readyfor use.# Note that the login protector actually sits on the root filesystem>>>>> fscrypt status /mnt/disk/dir2"/mnt/disk/dir2" is encrypted with fscrypt.Policy:   fe1c92009abc1cff4f3257c77e8134e3Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: YesProtected with 1 protector:PROTECTOR         LINKED   DESCRIPTION6891f0a901f0065e  Yes (/)  login protectorfor joerichey>>>>> fscrypt status /mnt/diskext4 filesystem"/mnt/disk" has 2 protectors and 2 policiesPROTECTOR         LINKED   DESCRIPTION7626382168311a9d  No       custom protector"Super Secret"6891f0a901f0065e  Yes (/)  login protectorfor joericheyPOLICY                            UNLOCKED  PROTECTORS16382f282d7b29ee27e6460151d03382  Yes       7626382168311a9dfe1c92009abc1cff4f3257c77e8134e3  Yes       6891f0a901f0065e>>>>> fscrypt status /ext4 filesystem"/" has 1 protector(s) and 0 policy(ies)PROTECTOR         LINKED  DESCRIPTION6891f0a901f0065e  No      login protectorfor joerichey

>>>>> mkdir /mnt/disk/dir2>>>>>echo"password"| fscrypt encrypt /mnt/disk/dir2 --source=pam_passphrase --quiet

# First we have to figure out which protector we wish to change.>>>>> fscrypt status /mnt/disk/dir1"/mnt/disk/dir1" is encrypted with fscrypt.Policy:   16382f282d7b29ee27e6460151d03382Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: YesProtected with 1 protector:PROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret"# Now specify the protector directly to the metadata command>>>>> fscrypt metadata change-passphrase --protector=/mnt/disk:7626382168311a9dEnter old custom passphrasefor protector"Super Secret":Enter new custom passphrasefor protector"Super Secret":Confirm passphrase:Passphrasefor protector 7626382168311a9d successfully changed.

>>>>>printf"hunter2\nhunter3"| fscrypt metadata change-passphrase --protector=/mnt/disk:7626382168311a9d --quiet

fscrypt also supports protectors which use raw key files as the user-providedsecret. These key files must be exactly 32 bytes long and contain the raw binarydata of the key. Obviously, make sure to store the key file securely (and not inthe directory you are encrypting with it). If generating the keys on Linux makesure you are aware ofhow randomness works andsome common myths.

# Generate a 256-bit key file>>>>> head --bytes=32 /dev/urandom> secret.key# Now create a key file protector without using it on a directory. Note that we# could also use `fscrypt encrypt --key=secret.key` to achieve the same thing.>>>>> fscrypt metadata create protector /mnt/diskCreate new protector on"/mnt/disk" [Y/n] yThe following protector sources are available:1 - Your login passphrase (pam_passphrase)2 - A custom passphrase (custom_passphrase)3 - A raw 256-bit key (raw_key)Enter thesource numberfor the new protector [2 - custom_passphrase]: 3Enter a namefor the new protector: SkeletonEnter key filefor protector"Skeleton": secret.keyProtector 2c75f519b9c9959d created on filesystem"/mnt/disk".>>>>> fscrypt status /mnt/diskext4 filesystem"/mnt/disk" has 3 protectors and 2 policiesPROTECTOR         LINKED   DESCRIPTION7626382168311a9d  No       custom protector"Super Secret"2c75f519b9c9959d  No       raw key protector"Skeleton"6891f0a901f0065e  Yes (/)  login protectorfor joericheyPOLICY                            UNLOCKED  PROTECTORS16382f282d7b29ee27e6460151d03382  Yes       7626382168311a9dfe1c92009abc1cff4f3257c77e8134e3  Yes       6891f0a901f0065e# Finally, we could apply this key to a directory>>>>> mkdir /mnt/disk/dir3>>>>> fscrypt encrypt /mnt/disk/dir3 --protector=/mnt/disk:2c75f519b9c9959dEnter key filefor protector"Skeleton": secret.key"/mnt/disk/dir3" is now encrypted, unlocked, and readyfor use.

>>>>> head --bytes=32 /dev/urandom> secret.key>>>>> fscrypt encrypt /mnt/disk/dir3 --key=secret.key --source=raw_key --name=Skeleton

fscrypt supports the idea of protecting a single directory with multipleprotectors. This means having access to any of the protectors is sufficient todecrypt the directory. This is useful for sharing data or setting up accesscontrol systems.

# Add an existing protector to the policy for some directory>>>>> fscrypt status /mnt/diskext4 filesystem"/mnt/disk" has 3 protectors and 3 policiesPROTECTOR         LINKED   DESCRIPTION7626382168311a9d  No       custom protector"Super Secret"2c75f519b9c9959d  No       raw key protector"Skeleton"6891f0a901f0065e  Yes (/)  login protectorfor joericheyPOLICY                            UNLOCKED  PROTECTORSd03fb894584a4318d1780e9a7b0b47eb  No        2c75f519b9c9959d16382f282d7b29ee27e6460151d03382  No        7626382168311a9dfe1c92009abc1cff4f3257c77e8134e3  No        6891f0a901f0065e>>>>> fscrypt status /mnt/disk/dir1"/mnt/disk/dir1" is encrypted with fscrypt.Policy:   16382f282d7b29ee27e6460151d03382Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: NoProtected with 1 protector:PROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret">>>>> fscrypt metadata add-protector-to-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382WARNING: All files using this policy will be accessible with this protector!!Protect policy 16382f282d7b29ee27e6460151d03382 with protector 2c75f519b9c9959d? [Y/n]Enter key filefor protector"Skeleton": secret.keyEnter custom passphrasefor protector"Super Secret":Protector 2c75f519b9c9959d now protecting policy 16382f282d7b29ee27e6460151d03382.>>>>> fscrypt status /mnt/disk/dir1"/mnt/disk/dir1" is encrypted with fscrypt.Policy:   16382f282d7b29ee27e6460151d03382Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2Unlocked: NoProtected with 2 protectors:PROTECTOR         LINKED  DESCRIPTION7626382168311a9d  No      custom protector"Super Secret"2c75f519b9c9959d  No      raw key protector"Skeleton"# Now the unlock command will prompt for which protector we want to use>>>>> fscrypt unlock /mnt/disk/dir1The available protectors are:0 - custom protector"Super Secret"1 - raw key protector"Skeleton"Enter the number of protector to use: 1Enter key filefor protector"Skeleton": secret.key"/mnt/disk/dir1" is now unlocked and readyfor use.# The protector can also be removed from the policy (if it is not the only one)>>>>> fscrypt metadata remove-protector-from-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382WARNING: All files using this policy will NO LONGER be accessible with this protector!!Stop protecting policy 16382f282d7b29ee27e6460151d03382 with protector 2c75f519b9c9959d? [y/N] yProtector 2c75f519b9c9959d no longer protecting policy 16382f282d7b29ee27e6460151d03382.

>>>>>echo"hunter2"| fscrypt metadata add-protector-to-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382 --key=secret.key --quiet>>>>> fscrypt metadata remove-protector-from-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382 --quiet --force

We would love to accept your contributions tofscrypt. See theCONTRIBUTING.md file for more information about signing the CLA and submittinga pull request.

In general, if you are encountering issues withfscrypt,open an issue, following theguidelines inCONTRIBUTING.md. We will try our best to help.

Usually, the PAM modulepam_fscrypt.so will automatically detect changes to auser's login passphrase and update the user'sfscrypt login protector so thatthey retain access their login-passphrase protected directories. However,sometimes a user's login passphrase can become desynchronized from theirfscrypt login protector. This can happen ifroot assigns the user a newpassphrase without providing the old one, if the user's login passphrase ismanaged by an external system such as LDAP, if the PAM module is not installed,or if the PAM module is not properly configured. SeeEnabling the PAMmodule for how to configure the PAM module.

To fix a user's login protector, find the corresponding protector ID by runningfscrypt status "/". Then, change this protector's passphrase by running:

fscrypt metadata change-passphrase --protector=/:ID

First, directories won't unlock if your session starts without passwordauthentication. The most common case of this is public-key ssh login. Totrigger a password authentication event, runsu $USER -c exit.

If your session did start with password authentication, then the following maybe causing the issue:

• The PAM module might not be configured correctly. Ensure you have correctlyconfigured the PAM module.

• If your login passphrase recently changed, then it might have gotten out ofsync with your login protector. To fix this,manually change your loginprotector'spassphraseto get it back in sync with your actual login passphrase.

• Due to abug in sshd,encrypted directories won't auto-unlock when logging in with ssh using theChallengeResponseAuthentication ssh authentication method, which is alsocalledKbdInteractiveAuthentication. This ssh authentication methodimplements password authentication by default, so it might appear similar toPasswordAuthentication. However, onlyPasswordAuthentication works withfscrypt. To avoid this issue, make sure that your/etc/ssh/sshd_configfile containsPasswordAuthentication yes,UsePAM yes, and eitherChallengeResponseAuthentication no orKbdInteractiveAuthentication no.

This is usually caused by your ext4 filesystem not having theencrypt featureflag enabled. Theencrypt feature flag allows the filesystem to containencrypted files. (It doesn't actually encrypt anything by itself.)

Before enablingencrypt on your ext4 filesystem, first ensure that all of thefollowing are true for you:

• You only need to use your filesystem on kernels v4.1 and later.

  (Kernels v4.0 and earlier can't mount ext4 filesystems that have theencryptfeature flag.)

• Either you only need to use your filesystem on kernels v5.5 and later, or yourkernel page size (rungetconf PAGE_SIZE) and filesystem block size (runtune2fs -l /dev/device | grep 'Block size') are the same.

  (Both values will almost always be 4096, but they may differ if yourfilesystem is very small, if your system uses the PowerPC CPU architecture, orif you overrode the default block size when you created the filesystem. Onlykernels v5.5 and later support ext4 encryption in such cases.)

• Either you aren't using GRUB to boot directly off the filesystem in question,or you are using GRUB 2.04 or later.

  (Old versions of GRUB can't boot from ext4 filesystems that haveencryptenabled. If, like most people, you have a separate/boot partition, you arefine. You are also fine if you are using the GRUB Debian package2.02-2 orlater [not2.02_beta*], including the version in Ubuntu 18.04 and later,since the patch to supportencrypt was backported.)

After verifying all of the above, enableencrypt by running:

tune2fs -O encrypt /dev/device

If you need to undo this, first delete all encrypted files and directories onthe filesystem. Then, run:

fsck -fn /dev/devicedebugfs -w -R "feature -encrypt" /dev/devicefsck -fn /dev/device

If you've enabledencrypt but you still get the "encryption not enabled"error, then the problem is that ext4 encryption isn't enabled in your kernelconfig. SeeRuntime dependencies for how to enable it.

Some older versions of Ubuntu didn't link the user keyring into the sessionkeyring, which caused problems withfscrypt.

To avoid this issue, upgrade to Ubuntu 20.04 or later.

Originally, filesystems didn't return the correct error code when attempting torename unencrypted files (or files with a different encryption policy) into anencrypted directory. Specifically, they returnedEPERM instead ofEXDEV,which causedmv to fail rather than fall back to a copy as expected.

This bug was fixed in version 5.1 of the mainline Linux kernel, as well as inversions 4.4 and later of the LTS (Long Term Support) branches of the Linuxkernel; specifically v4.19.155, 4.14.204, v4.9.242, and v4.4.242.

If the kernel can't be upgraded, this bug can be worked around by explicitlycopying the files instead, e.g. withcp.

IMPORTANT: Encrypting existing files can be insecure. Before doing so, readEncrypting existing files.

Trying to create or open an encrypted file will fail withENOPKG ("Package notinstalled") when the kernel doesn't support one or more of the cryptographicalgorithms used by the file or its directory. Note thatfscrypt encrypt andfscrypt unlock will still succeed; it's only using the directory afterwardsthat will fail.

The kernel will always support the algorithms thatfscrypt uses by default.However, if you changed the contents and/or filenames encryption algorithms in/etc/fscrypt.conf, then you may run into this issue.To fix it, enable the neededCONFIG_CRYPTO_* options in your Linux kernelconfiguration. See thekerneldocumentationfor details about which option(s) are required for each encryption mode.

This issue is caused by a limitation in the original design of Linux nativefilesystem encryption which made it difficult to ensure that all processes canaccess unlocked encrypted files. This issue can manifest in many ways, such as:

• SSH to a user with an encrypted home directory not working, even when thatdirectory is already unlocked

• Docker containers being unable to access encrypted files that were unlockedfrom outside the container

• NetworkManager being unable to access certificates stored in the user'salready-unlocked encrypted home directory

• Other system services being unable to access already-unlocked encrypted files

• sudo sessions being unable to access already-unlocked encrypted files

• A user being unable to access encrypted files that were unlocked by root

If an OS-level error is shown, it isENOKEY ("Required key not available").

To fix this issue, first runfscrypt status $dir, where$dir is yourencrypted directory. If the output containspolicy_version:2, then your issueis something else, so stop reading now. If the output containspolicy_version:1 or doesn't contain any mention ofpolicy_version, thenyou'll need to upgrade your directory(s) to policy version 2. To do this:

1. Upgrade to Linux kernel v5.4 or later.

2. Upgrade tofscrypt v0.2.7 or later.

3. Runsudo fscrypt setup --force.

4. Re-encrypt your encrypted directory(s). Since files cannot be (re-)encryptedin-place, this requires replacing them with new directories. For example:

     fscrypt unlock dir  # if not already unlocked  mkdir dir.new  fscrypt encrypt dir.new  cp -a -T dir dir.new  find dir -type f -print0 | xargs -0 shred -n1 --remove=unlink  rm -rf dir  mv dir.new dir

   You don't need to create a new protector. I.e., whenfscrypt encrypt asksfor a protector, just choose the one you were using before.

5. fscrypt status on your directory(s) should now showpolicy_version:2,and the issue should be gone.

Note that once your directories are using policy version 2, they will only beusable with Linux kernel v5.4 and later andfscrypt v0.2.6 and later. So becareful not to downgrade your software past those versions.

This issue can also be fixed by setting"use_fs_keyring_for_v1_policies": truein/etc/fscrypt.conf, as described inConfigurationfile. This avoids needing to upgrade directories topolicy version 2. However, this has some limitations, and the same kernel andfscrypt prerequisites still apply for this option to take effect. It isrecommended to upgrade your directories to policy version 2 instead.

This is working as intended. When an encrypted directory is unlocked (orlocked), it is unlocked (or locked) for all users. Encryption is not accesscontrol; the Linux kernel already has many access control mechanisms, such asthe standard UNIX file permissions, that can be used to control access to files.

Setting the mode of your encrypted directory to0700 will prevent users otherthan the directory's owner androot from accessing it while it is unlocked.Infscrypt v0.2.5 and later,fscrypt encrypt sets this mode automatically.

Having the locked/unlocked status of directories be global instead of per-usermay seem unintuitive, but it is actually the only logical way. The encryptionis done by the filesystem, so in reality the filesystem either has the key or itdoesn't. And once it has the key, any additional checks of whether particularusers "have" the key would be OS-level access control checks (not cryptography)that are redundant with existing OS-level access control mechanisms.

Similarly, any attempt of the filesystem encryption feature to preventrootfrom accessing unlocked encrypted files would be pointless. On Linux systems,root is usually all-powerful and can always get access to files in ways thatcannot be prevented, e.g.setuid() andptrace(). The only reliable way tolimit whatroot can do is via a mandatory access control system, e.g. SELinux.

The original design of Linux native filesystem encryption actually did put thekeys into per-user keyrings. However, this caused amassive number ofproblems, as it'sactually very common that encrypted files need to be accessed by processesrunning under different user IDs -- even if it may not be immediately apparent.

Encrypted files can't be backed up while locked; you need to unlock them first.For details, seeBackup, restore, and recovery.

Originally, filesystems didn't conform to POSIX when reporting the size ofencrypted symlinks, as they gave the size of the ciphertext symlink targetrather than the size of the plaintext target. This would make the reported sizeof symlinks appear to be slightly too large when queried usinglstat() orsimilar system calls. Most programs don't care about this, but in rare casesprograms can depend on the filesystem reporting symlink sizes correctly.

This bug was fixed in version 5.15 of the mainline Linux kernel, as well as inversions 4.19 and later of the LTS (Long Term Support) branches of the Linuxkernel; specifically v5.10.63, v5.4.145, and v4.19.207.

If the kernel can't be upgraded, the only workaround for this bug is to updateany affected programs to not depend on symlink sizes being reported correctly.

Copyright 2017 Google Inc. under theApache 2.0 License; see theLICENSE file for more information.

Author: Joe Richeyjoerichey@google.com

This is not an official Google product.