From abdd12ff9efa98af245b91517398ad84b42fd90e Mon Sep 17 00:00:00 2001 From: "Joe Richey joerichey@google.com" Date: Wed, 21 Jun 2017 12:52:21 -0700 Subject: [PATCH] Update Makefile and README This commit updates the README and Makefile to get them ready for external release. This includes adding some common pitfalls, including example usage, and allowing for tarball creation. Change-Id: I442338c7aff613a14bae449dbf091bfcaf73ed9d --- .gitignore | 2 +- Makefile | 10 +- README.md | 511 +++++++++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 464 insertions(+), 59 deletions(-) diff --git a/.gitignore b/.gitignore index d60aa9a..01f4f15 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ /fscrypt -fscrypt.sublime-* +fscrypt.* diff --git a/Makefile b/Makefile index ab5cad0..09d5558 100644 --- a/Makefile +++ b/Makefile @@ -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) diff --git a/README.md b/README.md index caad7fe..24f603e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,13 @@ # fscrypt - -`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 --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 + +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 -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 -- 2.39.5