Skip to content

Commit

Permalink
Merge 813dc7f into d4d2823
Browse files Browse the repository at this point in the history
  • Loading branch information
@ebiggers
ebiggers committed May 10, 2020
2 parents d4d2823 + 813dc7f commit 5167ce8
Showing 1 changed file with 110 additions and 40 deletions.
150 changes: 110 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,17 @@ 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 protector types are:
1. Your login passphrase, through [PAM](http://www.linux-pam.org/Linux-PAM-html)
2. A custom passphrase
3. A raw key file

1. Your login passphrase, through [PAM](http://www.linux-pam.org/Linux-PAM-html).
The included PAM module (`pam_fscrypt.so`) can automatically unlock login
protectors when you log in. __IMPORTANT:__ before using a login protector,
follow [Setting up for login protectors](#setting-up-for-login-protectors).

2. A custom passphrase. This passphrase is hashed with
[Argon2id](https://en.wikipedia.org/wiki/Argon2), by default calibrated to
use all CPUs and take about 1 second.

3. A raw key file. See [Using a raw key protector](#using-a-raw-key-protector).

These protectors are mutable, so the information can change without needing to
update any of your encrypted directories.
Expand Down Expand Up @@ -142,7 +150,7 @@ simply run:
go get github.com/google/fscrypt/cmd/fscrypt
```

### Runtime Dependencies
## Runtime Dependencies

To run, fscrypt needs the following libraries:
* `libpam.so` (almost certainly already on your system)
Expand Down Expand Up @@ -185,7 +193,7 @@ If you configure fscrypt to use non-default features, other kernel
prerequisites may be needed too. See [Configuration
file](#configuration-file).

### Configuration file
## Configuration file

Running `sudo fscrypt setup` will create the configuration file
`/etc/fscrypt.conf` if it doesn't already exist. It's a JSON file
Expand Down Expand Up @@ -264,15 +272,64 @@ The fields are:
setting and instead (re-)create your encrypted directories with
`"policy_version": "2"`.

### PAM configuration
## Setting up for login protectors

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 installed `fscrypt` from source rather than from your distro's package
manager, you may also need to allow `fscrypt` to check your login passphrase.

### Securing your login passphrase

Although `fscrypt` uses a strong passphrase hash algorithm, the security of
login protectors is also limited by the strength of your system's passphrase
hashing in `/etc/shadow`. On most Linux distributions, `/etc/shadow` by default
uses SHA-512 with 5000 rounds, which is much weaker than what `fscrypt` uses.

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

If using a strong login passphrase is annoying because it needs to be entered
frequently to run `sudo`, consider increasing the `sudo` timeout. That can be
done by adding the following to `/etc/sudoers`:
```
Defaults timestamp_timeout=60
```

You should also increase the number of rounds that your system's passphrase
hashing uses (though this doesn't increase security as much as choosing a strong
passphrase). To do this, find the line in `/etc/pam.d/passwd` that looks like:
```
password required pam_unix.so sha512 shadow nullok
```

Append `nrounds=1000000` (or another number of your choice; the goal is to make
the passphrase hashing take about 1 second, similar to `fscrypt`'s default):
```
password required pam_unix.so sha512 shadow nullok nrounds=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 old
passphrase hash may still be recoverable from disk), use `sudo passwd $USER`
instead. This re-hashes your existing passphrase with the new `nrounds`.

### Enabling the PAM module

If you want any encrypted directories to be protected by your login
passphrase and be automatically unlocked when you log in, you'll need
to edit your [PAM configuration
files](http://www.linux-pam.org/Linux-PAM-html/sag-configuration.html)
to enable the PAM module (`pam_fscrypt`).
To enable the PAM module `pam_fscrypt.so`, follow the directions for your Linux
distro below. Enabling the PAM module is needed for login passphrase-protected
directories to be automatically unlocked when you log in, and for login
passphrase-protected directories to remain accessible when you change your login
passphrase.

#### On Ubuntu
#### Enabling the PAM module on Ubuntu

Both the official `fscrypt` package for Ubuntu and `sudo make install`
will install a configuration file for [Ubuntu's PAM configuration
Expand All @@ -281,17 +338,17 @@ framework](https://wiki.ubuntu.com/PAMConfigFrameworkSpec) to
defaults for the PAM module. To automatically apply these defaults,
run `sudo pam-auth-update` and follow the on-screen instructions.

#### On Arch Linux
#### Enabling the PAM module on Arch Linux

On Arch Linux, follow the recommendations at the [Arch Linux
Wiki](https://wiki.archlinux.org/index.php/Fscrypt#Auto-unlocking_directories).

We recommend using the Arch Linux package, either `fscrypt` (official)
or `fscrypt-git` (AUR). If you instead install `fscrypt` manually
using `sudo make install`, then in addition to the steps on the Wiki
you'll also need to create `/etc/pam.d/fscrypt` as described below.
We recommend using the Arch Linux package, either `fscrypt` (official) or
`fscrypt-git` (AUR). If you instead install `fscrypt` manually using `sudo make
install`, then in addition to the steps on the Wiki you'll also need to [create
`/etc/pam.d/fscrypt`](#allowing-fscrypt-to-check-your-login-passphrase).

#### On other Linux distros
#### Enabling the PAM module on other Linux distros

On all other Linux distros, follow the general guidance below to edit
your PAM configuration files.
Expand Down Expand Up @@ -326,13 +383,16 @@ locked data is inaccessible; this only needed for v1 encryption policies.
All the types also support the `debug` option which prints additional
debug information to the syslog.

Finally, some Linux distros use restrictive settings in
`/etc/pam.d/other` that prevent non-whitelisted programs from checking
your login passphrase. This prevents `fscrypt` from creating any login
passphrase-protected directories, even without auto-unlocking. To
ensure that `fscrypt` will work properly (if you didn't install an
official `fscrypt` package from your distro, which should have already
handled this), also create a file `/etc/pam.d/fscrypt` containing:
### Allowing `fscrypt` to check your login passphrase

This step is only needed if you installed `fscrypt` from source code.

Some Linux distros use restrictive settings in `/etc/pam.d/other` that prevent
non-whitelisted programs from checking your login passphrase. This prevents
`fscrypt` from creating any login passphrase-protected directories, even without
auto-unlocking. To ensure that `fscrypt` will work properly (if you didn't
install an official `fscrypt` package from your distro, which should have
already handled this), also create a file `/etc/pam.d/fscrypt` containing:
```
auth required pam_unix.so
```
Expand Down Expand Up @@ -470,6 +530,11 @@ Hello World

### Protecting a directory with your login passphrase

First, ensure that you have properly [set up your system for login
protectors](#setting-up-for-login-protectors).

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

```bash
# Select your login passphrase as the desired source.
>>>>> mkdir /mnt/disk/dir2
Expand Down Expand Up @@ -679,28 +744,33 @@ guidelines in `CONTRIBUTING.md`. We will try our best to help.

#### I changed my login passphrase, now all my directories are inaccessible

The PAM module provided by fscrypt (`pam_fscrypt.so`) should automatically
detect changes to a user's login passphrase so that they can still access their
encrypted directories. However, sometimes the login passphrase can become
desynchronized from a user's login protector. This usually happens when the PAM
passphrase is managed by an external system, if the PAM module is not installed,
or if the PAM module is not properly configured.
The PAM module `pam_fscrypt.so` should automatically detect changes to a user's
login passphrase so that they can still access their encrypted directories.
However, sometimes a user's login passphrase can become desynchronized from
their login protector. This can happen if their login passphrase is managed by
an external system, if the PAM module is not installed, or if the PAM module is
not properly configured. See [Enabling the PAM
module](#enabling-the-pam-module) for how to configure the PAM module.

To fix your login protector, you first should find the appropriate protector ID
by running `fscrypt status "/"`. Then, change the passphrase for this protector
by running:
To fix a user's login protector, find the corresponding protector ID by running
`fscrypt status "/"`. Then, change this protector's passphrase by running:
```
fscrypt metadata change-passphrase --protector=/:ID
```

#### Directories using my login passphrase are not automatically unlocking.

Either the PAM module is not installed correctly, or your login passphrase
changed and things got out of sync. Another reason that these directories might
not unlock is if your session starts without password authentication. The most
common case of this is public-key ssh login.

To trigger a password authentication event, run `su $(whoami) -c exit`.
First, directories won't unlock if your session starts without password
authentication. The most common case of this is public-key ssh login. To
trigger a password authentication event, run `su $USER -c exit`.

If your session did start with password authentication, then either the PAM
module is not correctly installed and configured, or your login passphrase
changed and got out of sync with your login protector. Ensure you have
correctly [configured the PAM module](#enabling-the-pam-module). Then, if
necessary, [manually change your login protector's
passphrase](#i-changed-my-login-passphrase-now-all-my-directories-are-inaccessible)
to get it back in sync with your actual login passphrase.

#### Getting "encryption not enabled" on an ext4 filesystem.

Expand Down

0 comments on commit 5167ce8

Please sign in to comment.