diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile | 10 | ||||
| -rw-r--r-- | README.md | 511 |
3 files changed, 464 insertions, 59 deletions
@@ -1,2 +1,2 @@ /fscrypt -fscrypt.sublime-* +fscrypt.* @@ -75,7 +75,15 @@ format: @find . -name "*.h" -o -name "*.c" -not -path "./vendor/*" | xargs clang-format -i -style=Google install: + go install $(CMD_DIR) + +install_all: govendor install $(GOFLAGS) +local +TARBALL = $(NAME).$(shell date --iso-8601).tar.gz +$(TARBALL): + git archive --format=tar.gz --output=$(TARBALL) HEAD +tarball: $(TARBALL) + clean: - rm -rf $(NAME) + rm -rf $(NAME) $(TARBALL) @@ -1,14 +1,13 @@ # fscrypt -<!-- TODO: Insert link to fscryptctl when it is released --> -`fscrypt` is a high-level tool [written in Go](https://golang.org) for the +fscrypt is a high-level tool [written in Go](https://golang.org) for the management of [Linux filesystem encryption](https://lwn.net/Articles/639427). This tool manages metadata, key generation, key wrapping, PAM integration, and provides a uniform interface for creating and modifying encrypted directories. For a small low-level tool that directly manipulates keys and policies, see -`fscryptctl`. +[fscryptctl](https://github.com/google/fscryptctl). -To use `fscrypt`, you must have a filesystem with encryption enabled and a +To use fscrypt, you must have a filesystem with encryption enabled and a kernel that supports reading/writing from that filesystem. Currently, [ext4](https://en.wikipedia.org/wiki/Ext4), [F2FS](https://en.wikipedia.org/wiki/F2FS), and @@ -20,10 +19,10 @@ encryption. Ext4 has supported Linux filesystem encryption certain configurations of the Linux kernel enable encryption, and other filesystems may add support for encryption. -Most of the testing for `fscrypt` has been done with ext4 filesystems. However, +Most of the testing for fscrypt has been done with ext4 filesystems. However, the kernel uses a common userspace interface, so this tool should work with all -existing and future filesystems which support for encryption. If there is a -problem using `fscrypt` with other filesystems, please open an issue. +existing and future filesystems which support encryption. If there is a problem +using fscrypt with other filesystems, please open an issue. ### Other encryption solutions @@ -31,59 +30,105 @@ It is important to distinguish Linux filesystem encryption from two other encryption solutions: [eCryptfs](https://en.wikipedia.org/wiki/ECryptfs) and [dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt). -Currently, dm-crypt encrypts an entire block device with a single master key. If -you do not need the fine-grained controls of `fscrypt` or want to fully encrypt -your filesystem metadata, dm-crypt could be a simpler choice. +Currently, dm-crypt encrypts an entire block device with a single master key. +dm-crypt can be used with or without fscrypt. All filesystem data (including all +filesystem metadata) is encrypted with this single key when using dm-crypt, +while fscrypt only encrypts the filenames and file contents in a specified +directory. Note that using both dm-crypt and fscrypt simultaneously will give +the protections and benefits of both; however, this may cause a decrease in +your performance, as files contents are encrypted twice. + +Once example of a reasonable setup could involve using dm-crypt with a TPM or +Secure boot key, while using fscrypt for the contents of a home directory. This +would still encrypt the entire drive, but would also tie the encryption of a +user's personal documents to their passphrase. On the other hand, eCryptfs is another form of filesystem encryption on Linux; it encrypts a filesystem directory with some key or passphrase. eCryptfs sits on top of an existing filesystem. This make eCryptfs an alternative choice if your -filesystem or kernel does not support Linux filesystem encryption or you do not -want to modify your existing filesystem. +filesystem or kernel does not support native filesystem encryption. -Also note that `fscrypt` does not support or setup either eCryptfs or dm-crypt. +Also note that fscrypt does not support or setup either eCryptfs or dm-crypt. For these tools, use [ecryptfs-utils](https://packages.debian.org/source/jessie/ecryptfs-utils) for eCryptfs or [cryptsetup](https://linux.die.net/man/8/cryptsetup) for dm-crypt. ## Features -`fscrypt` is intended to improve upon the work in +fscrypt is intended to improve upon the work in [e4crypt](http://man7.org/linux/man-pages/man8/e4crypt.8.html) by providing a more managed environment and handling more functionality in the -background. `fscrypt` has a [design document](https://goo.gl/55cCrI) that -discusses many of the higher level design choices that were made. - -Specifically, `fscrypt` contains the following functionality: -* `fscrypt info` - Prints detailed application info -* `fscrypt setup global` - Initializes the `fscrypt.conf` file -* `fscrypt setup filesystem` - Gets a filesystem ready for use with fscrypt -* `fscrypt setup directory` - Sets up encryption for a directory -* `fscrypt unlock` - Unlocks an encrypted directory for use -* `fscrypt encrypt` - Shortcut for `fscrypt setup directory`+`fscrypt unlock` -* `fscrypt change` - Changes how a directory is protected -* `fscrypt status` - Gets the status of some component of fscrypt +background. fscrypt has a [design document](https://goo.gl/55cCrI) which +should be read to understand the full architecture of fscrypt. + +Briefly, fscrypt deals with protectors and policies. Protectors represent some +secret or information used to protect the confidentiality of your data. The +three currently supported protectors types are: +1. Your login passphrase, through + [PAM](http://www.linux-pam.org/Linux-PAM-html/) (see troubleshooting below) +2. A custom passphrase +3. A raw key file + +These protectors are mutable, so the information can change without needing to +update any of your encrypted directories. + +Policies represent the actual key passed to the kernel. This "policy key" is +immutable and policies are (usually) applied to a single directory. Protectors +then protect policies, so that having one of the protectors for a policy is +enough to get the policy key and access the data. Which protectors protect a +policy can also be changed. This allows a user to change how a directory is +protected without needing to reencrypt the directory's contents. + +Specifically, fscrypt contains the following functionality: +* `fscrypt setup` - Initializes the `fscrypt.conf` file + * This is the only functionality which 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 purge MOUNTPOINT` - Removes keys for a filesystem before unmounting +* `fscrypt status [PATH]` - Gets detailed info about filesystems or paths +* `fscrypt metadata` - Manages policies or protectors directly + +The following functionality is planned: * `fscrypt backup` - Manages backups of the fscrypt metadata -* `fscrypt recovery` - Manages recovery keys for fscrypt protectors -* `fscrypt cleanup` - Scans filesystem for unused policies -* `fscrypt purge` - Removes keys for a filesystem before unmounting. -* `fscrypt [protector|policy]` - Manages metadata directly +* `fscrypt recovery` - Manages recovery keys for directories +* `fscrypt cleanup` - Scans filesystem for unused policies/protectors +* A PAM module to support changing of login passphrase -See the example usage section below or run `fscrypt <command> --help` for more +See the example usage section below or run `fscrypt COMMAND --help` for more information about each of the commands. ## Building -`fscrypt` is written in Go, so to build the program you will need to +### Release build instructions + +fscrypt is written in Go, so to build the program you will need to +[setup Go](https://golang.org/doc/install), +[setup your `GOPATH`](https://golang.org/doc/code.html#GOPATH), and clone the +repository into the correct location by running: +```shell +go get -u github.com/google/fscrypt +``` +Alternatively, just copy or checkout the source into +`$GOPATH/src/github.com/google/fscrypt` and run: +```shell +go build github.com/google/fscrypt +``` + +### Pre-release build instructions +<!-- TODO(joerichey) remove these before release --> +fscrypt is written in Go, so to build the program you will need to [setup Go](https://golang.org/doc/install), [setup your `GOPATH`](https://golang.org/doc/code.html#GOPATH), and clone the repository into the correct location by running -```shell <!-- TODO: Change git clone URL before public release --> -git clone [REDACTED] $GOPATH/src/fscrypt +```shell +git clone REPOSITORY $GOPATH/fscrypt ``` +or by unpacking a source tar file into `$GOPATH/fscrypt`. + You will also want to add `$GOPATH/bin` to your `$PATH`. -`fscrypt` has the following build dependencies: +fscrypt has the following build dependencies: * `make` * A C compiler (`gcc` or `clang`) * Go @@ -91,54 +136,406 @@ You will also want to add `$GOPATH/bin` to your `$PATH`. library which can be installed (both the header `argon2.h` and library `libargon2`) by running: ```bash - > git clone https://github.com/P-H-C/phc-winner-argon2 argon2 - > cd argon2 - > make - > sudo make install + >>>>> git clone https://github.com/P-H-C/phc-winner-argon2 argon2 + >>>>> cd argon2 + >>>>> make + >>>>> sudo make install ``` -* Headers for `libblkid` (specifically `blkid/blkid.h`). This can be installed - with your appropriate package manager (`libblkid-dev` for APT, - `libblkid-devel` for RPM, should already be part of `util-linux` for Arch). +* Headers for `libblkid` (specifically `blkid/blkid.h`) and `libpam` + (specifically `security/pam_appl.h`). These can be installed with your + appropriate package manager. + - `sudo apt-get install libblkid-dev libpam0g-dev` + - `sudo yum install libblkid-devel pam-devel` + - `pam` and `util-liux` packages for Arch -Once this is setup, you can run `make fscrypt` to build the executable in -the root directory. See the `Makefile` for instructions on building a static +Once this is setup, you can run `make fscrypt` to build the executable in the +current directory. See the `Makefile` for instructions on building a static executable. If a Go project contains C code, the go compiler produces a dynamically linked binary by default. ## Running and Installing -`fscrypt` has the following runtime dependencies: +fscrypt has the following runtime dependencies: * Kernel support for filesystem encryption (this will depend on your kernel configuration and specific filesystem) * `libargon2` (see the above installation instructions for Argon2), unless you built a static executable. -* `libblkid` and `libuuid` (these are dependancies for `util-linux` and - `e2fsprogs` so your system almost certainly has it), unless you built a - static executable. +* `libblkid` and `libpam` (which are almost certainly already on your system), + unless you built a static executable. Installing it just requires placing it in your path or running `make install`. -Change `$GOBIN` to change the install location of `fscrypt`. By default, -`fscrypt` is installed to `$GOPATH/bin`. +Change `$GOBIN` to change the install location of fscrypt. By default, +fscrypt is installed to `$GOPATH/bin`. ## Example Usage +All these examples assumes we have ext4 filesystems mounted at `/` and +`/mnt/disk` which both support encryption and that `/mnt/disk` contains +directories we want to encrypt. + +### Setting up fscrypt on a directory + ```bash -# Setup your global configuration and filesystem -> sudo fscrypt setup global +# Check which directories on our system support encryption +>>>>> fscrypt status +2 filesystem(s) on this system support encryption + +MOUNTPOINT DEVICE FILESYSTEM STATUS +/ /dev/sda1 ext4 encryption not enabled +/mnt/disk /dev/sdb ext4 not setup with fscrypt + +# Create the global configuration file. Nothing else needs root. +>>>>> sudo fscrypt setup +Create "/etc/fscrypt.conf"? [Y/n] y +Customizing passphrase hashing difficulty for this system... Created global config file at "/etc/fscrypt.conf". -> fscrypt setup filesystem /mnt/disk/to/encrypt -Setup "/mnt/disk/to/encrypt (/dev/sda1) for use with ext4 filesystem encryption. + +# Start using fscrypt with our filesystem +>>>>> fscrypt setup /mnt/disk +Metadata directories created at "/mnt/disk/.fscrypt". +Filesystem "/mnt/disk" (/dev/sdb) ready for use with ext4 encryption. + +# Initialize encryption on a new empty directory +>>>>> mkdir /mnt/disk/dir1 +>>>>> fscrypt encrypt /mnt/disk/dir1 +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: +"/mnt/disk/dir1" is now encrypted, unlocked, and ready for use. + +# We can see this created one policy and one protector for this directory +>>>>> fscrypt status /mnt/disk +ext4 filesystem "/mnt/disk" has 1 protector(s) and 1 policy(ies) + +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" + +POLICY UNLOCKED PROTECTORS +7626382168311a9d Yes 7626382168311a9d +``` + +#### Quiet Version +```bash +>>>>> sudo fscrypt setup --quiet --force +>>>>> fscrypt setup /mnt/disk --quiet +>>>>> echo "hunter2" | fscrypt encrypt /mnt/disk/dir1 --quiet --source=custom_passphrase --name="Super Secret" +``` + +### Locking and unlocking a directory + +As noted in the troubleshooting below, we (as of now) have to unmount a +filesystem after purging its keys to clear the necessary caches. + +```bash +# 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: 16382f282d7b29ee +Unlocked: Yes + +Protected with 1 protector(s): +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" + +# Purging, unmounting, and remounting a filesystem locks all the files. +>>>>> fscrypt purge /mnt/disk +WARNING: This may make data encrypted with fscrypt inaccessible. +Purge all policy keys from "/mnt/disk" (this will lock all encrypted directories) [y/N] y +All keys purged for "/mnt/disk". +Filesystem "/mnt/disk" should now be unmounted. +>>>>> umount /mnt/disk +>>>>> mount /mnt/disk +>>>>> fscrypt status /mnt/disk/dir1 +"/mnt/disk/dir1" is encrypted with fscrypt. + +Policy: 16382f282d7b29ee +Unlocked: No + +Protected with 1 protector(s): +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" + +# Now the filenames and file contents are inaccessible +>>>>> ls /mnt/disk/dir1 +u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P +>>>>> cat /mnt/disk/dir1/u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P +cat: /mnt/disk/dir1/u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P: Required key not available + +# Unlocking the directory makes the contents available +>>>>> fscrypt unlock /mnt/disk/dir1 +Enter custom passphrase for protector "Super Secret": +"/mnt/disk/dir1" is now unlocked and ready for use. +>>>>> fscrypt status /mnt/disk/dir1 +"/mnt/disk/dir1" is encrypted with fscrypt. + +Policy: 16382f282d7b29ee +Unlocked: Yes + +Protected with 1 protector(s): +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" +>>>>> cat /mnt/disk/dir1/secret.txt +Hello World +``` + +#### Quiet Version +```bash +>>>>> fscrypt purge /mnt/disk --quiet --force +>>>>> umount /mnt/disk +>>>>> mount /mnt/disk +>>>>> printf "hunter2" | fscrypt unlock /mnt/disk/dir1 --quiet +``` + +### Protecting a directory with your login passphrase + +As noted above and in the troubleshooting below, fscrypt cannot (yet) detect +when your login passphrase changes. So if you protect a directory with your +login passphrase, you may have to do additional work when you change your system +passphrase. + +```bash +# Login passphrases also require that fscrypt is setup on the root directory +>>>>> sudo fscrypt setup / +Filesystem "/" (/dev/dm-1) ready for use with ext4 encryption. + +# Select your login passphrase as the desired source. +>>>>> mkdir /mnt/disk/dir2 +>>>>> fscrypt encrypt /mnt/disk/dir2 +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 joerichey: +"/mnt/disk/dir2" is now encrypted, unlocked, and ready for 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: fe1c92009abc1cff +Unlocked: Yes + +Protected with 1 protector(s): +PROTECTOR LINKED DESCRIPTION +6891f0a901f0065e Yes (/) login protector for joerichey +>>>>> fscrypt status /mnt/disk +ext4 filesystem "/mnt/disk" has 3 protector(s) and 3 policy(ies) + +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" +6891f0a901f0065e Yes (/) login protector for joerichey + +POLICY UNLOCKED PROTECTORS +16382f282d7b29ee Yes 7626382168311a9d +fe1c92009abc1cff Yes 6891f0a901f0065e +>>>>> fscrypt status / +ext4 filesystem "/" has 1 protector(s) and 0 policy(ies) + +PROTECTOR LINKED DESCRIPTION +6891f0a901f0065e No login protector for joerichey +``` + +#### Quiet Version +```bash +>>>>> mkdir /mnt/disk/dir2 +>>>>> echo "password" | fscrypt encrypt /mnt/disk/dir1 --source=pam_passphrase --quiet +``` + +### Changing a custom passphrase +```bash +# 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: 16382f282d7b29ee +Unlocked: Yes + +Protected with 1 protector(s): +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" + +# Now specify the protector directly to the metadata command +>>>>> fscrypt metadata change-passphrase --protector=/mnt/disk:7626382168311a9d +Enter old custom passphrase for protector "Super Secret": +Enter new custom passphrase for protector "Super Secret": +Confirm passphrase: +Passphrase for protector 7626382168311a9d successfully changed. +``` + +#### Quiet Version +```bash +>>>>> printf "hunter2\nhunter3" | fscrypt metadata change-passphrase --protector=/mnt/disk:7626382168311a9d --quiet +``` + +### Using a raw key protector + +fscrypt also supports protectors which use raw key files as the user-provided +secret. These key files must be exactly 32 bytes long and contain the raw binary +data of the key. Obviously, make sure to store the key file securely (and not in +the directory you are encrypting with it). If generating the keys on Linux make +sure you are aware of +[how randomness works](http://man7.org/linux/man-pages/man7/random.7.html) and +[some common myths](https://www.2uo.de/myths-about-urandom/). + +```bash +# 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/disk +Create new protector on "/mnt/disk" [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]: 3 +Enter a name for the new protector: Skeleton +Enter key file for protector "Skeleton": secret.key +Protector 2c75f519b9c9959d created on filesystem "/mnt/disk". +>>>>> fscrypt status /mnt/disk +ext4 filesystem "/mnt/disk" has 3 protectors and 3 policies + +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" +2c75f519b9c9959d No raw key protector "Skeleton" +6891f0a901f0065e Yes (/) login protector for joerichey + +POLICY UNLOCKED PROTECTORS +16382f282d7b29ee Yes 7626382168311a9d +fe1c92009abc1cff Yes 6891f0a901f0065e + +# Finally, we could apply this key to a directory +>>>>> mkdir /mnt/disk/dir3 +>>>>> fscrypt encrypt /mnt/disk/dir3 --protector=/mnt/disk:2c75f519b9c9959d +Enter key file for protector "Skeleton": secret.key +"/mnt/disk/dir3" is now encrypted, unlocked, and ready for use. +``` + +#### Quiet Version +```bash +>>>>> head --bytes=32 /dev/urandom > secret.key +>>>>> fscrypt encrypt /mnt/disk/dir3 --key=secret.key --source=raw_key --name=Skeleton +``` + +### Using multiple protectors for a policy + +fscrypt supports the idea of of protecting a single directory with multiple +protectors. This means having access to any of the protectors is sufficient to +decrypt the directory. This is useful for sharing data or setting up access +control systems. + +```bash +# Add an existing protector to the policy for some directory +>>>>> fscrypt status /mnt/disk +ext4 filesystem "/mnt/disk" has 3 protectors and 3 policies + +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" +2c75f519b9c9959d No raw key protector "Skeleton" +6891f0a901f0065e Yes (/) login protector for joerichey + +POLICY UNLOCKED PROTECTORS +d03fb894584a4318 No 2c75f519b9c9959d +16382f282d7b29ee No 7626382168311a9d +fe1c92009abc1cff No 6891f0a901f0065e +>>>>> fscrypt status /mnt/disk/dir1 +"/mnt/disk/dir1" is encrypted with fscrypt. + +Policy: 16382f282d7b29ee +Unlocked: No + +Protected with 1 protector: +PROTECTOR LINKED DESCRIPTION +7626382168311a9d No custom protector "Super Secret" +>>>>> fscrypt metadata add-protector-to-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee +WARNING: All files using this policy will be accessible with this protector!! +Protect policy 16382f282d7b29ee with protector 2c75f519b9c9959d? [Y/n] +Enter key file for protector "Skeleton": secret.key +Enter custom passphrase for protector "Super Secret": +Protector 2c75f519b9c9959d now protecting policy 16382f282d7b29ee. +>>>>> fscrypt status /mnt/disk/dir1 +"/mnt/disk/dir1" is encrypted with fscrypt. + +Policy: 16382f282d7b29ee +Unlocked: No + +Protected with 2 protectors: +PROTECTOR LINKED DESCRIPTION +7626382168311a9d 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/dir1 +The available protectors are: +0 - custom protector "Super Secret" +1 - raw key protector "Skeleton" +Enter the number of protector to use: 1 +Enter key file for protector "Skeleton": secret.key +"/mnt/disk/dir1" is now unlocked and ready for 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:16382f282d7b29ee +WARNING: All files using this policy will NO LONGER be accessible with this protector!! +Stop protecting policy 16382f282d7b29ee with protector 2c75f519b9c9959d? [y/N] y +Protector 2c75f519b9c9959d no longer protecting policy 16382f282d7b29ee. +``` + +#### Quiet Version +```bash +>>>>> echo "hunter2" | fscrypt metadata add-protector-to-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee --key=secret.key --quiet +>>>>> fscrypt metadata remove-protector-from-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee --quiet --force ``` ## Contributing -We would love to accept your contributions to `fscrypt`. See the +We would love to accept your contributions to fscrypt. See the `CONTRIBUTING.md` file for more information about singing the CLA and submitting a pull request. -## Known Issues +## Troubleshooting + +#### I changed my login passphrase, now all my directories are inaccessible + +We do not currently support the changing of the login passphrase. This will +change when the appropriate module is completed. Until then, you can fix it by +first finding the necessary protector (with `fscrypt status PATH`) and then +running: +``` +fscrypt metadata change-passphrase --protector=MOUNTPOINT:ID +``` -None so far! +#### I can still see Files/Filenames after running `fscrypt purge MOUNTPOINT` + +You need to unmount `MOUNTPOINT` to clear the necessary caches. See +`fscrypt purge --help` for more information + +#### Getting "encryption not enabled" on an ext4 filesystem. + +Getting this error on an ext4 system usually means the filesystem has not been +setup for encryption. To setup a filesystem to support encryption, first check +that your block size is equal to your page size by comparing the outputs of +`getconf PAGE_SIZE` and `tune2fs -l /dev/device | grep 'Block size'`. If these +are not the same, DO NOT ENABLE ENCRYPTION. + +To turn on the encryption feature flag for your filesystem, run +``` +tune2fs -O encrypt /dev/device +``` +This command may require root privileges. Once the flag is enabled, older +kernels may not be able to mount the filesystem. Note that there was a bug in an +older kernel version that allowed encryption policies to be set on ext4 +filesystems without enabling this encryption feature flag. ## Legal |