README: clarify how restoring /.fscrypt directory works

Update https://github.com/google/fscrypt/issues/115

Merge pull request #310 from ebiggers/readme-updates

Readme updates

README: add section about encrypting existing files

README: consistently format section titles

Capitalize the first word only, and don't use periods.

README: add section about backup, restore, and recovery

Resolves https://github.com/google/fscrypt/issues/51
Resolves https://github.com/google/fscrypt/issues/115

README: remove note about stability

A lot of people are already using fscrypt, so in practice we haven't
been breaking backwards compatibility and aren't going to.  Just remove
the scary-sounding "Note about stability".

README: remove note about planned commands

These would still be nice to add.  However, the mention of them in the
README is misleading because people reading it might come away with the
impression that there is currently no way to back up fscrypt metadata or
to recover directories -- which isn't true.  (The fscrypt metadata is
just a directory which can be backed up like any other directory.  And
'fscrypt encrypt' already offers to generate a recovery passphrase when
the directory and protector are on different filesystems.)

Just remove this note; it doesn't really add any value.

Merge pull request #309 from ebiggers/troubleshooting

Updates to the troubleshooting documentation

README: document symlink size bug

Update https://github.com/google/fscrypt/issues/305

README: documentation tweaks

Clarify some of the troubleshooting documentation.

cli-tests: fix failure with latest bash version

README: add troubleshooting section for ENOPKG error

Inspired by https://reddit.com/r/linuxquestions/comments/n75dv4

README: add troubleshooting section for keyring linkage issue

Fixes https://github.com/google/fscrypt/issues/194
Update https://github.com/google/fscrypt/issues/100

cmd/fscrypt: fix detection of GRUB installation

Fix the GRUB detection logic to take into account that
MOUNTPOINT/boot/grub might not be on the same filesystem as MOUNTPOINT,
due to MOUNTPOINT/boot being another mountpoint.  The warning is only
appropriate when GRUB is installed on the same filesystem that
encryption is going to be enabled on.

README: improve troubleshooting tips for unlocked encrypted files

Rename the troubleshooting section "Can't log in with ssh even when
user's encrypted home directory is unlocked" to the more general "Some
processes can't access unlocked encrypted files", and rewrite it to
provide clearer directions for how to fix the problem by upgrading
encrypted directories to policy version 2.

Also add a related section "Users can access other users' unlocked
encrypted files" which covers the reverse "issue", i.e. people expecting
some processes to *not* be able to access unlocked encrypted files.

Fixes https://github.com/google/fscrypt/issues/248

README: improve troubleshooting section for login protector not in sync

Update https://github.com/google/fscrypt/issues/273

Merge pull request #292 from josephlr/mem

Only use 1/8 of the system RAM and run the Garbage Collector in the timing loop

Run the Garbage Collector in the timing loop

Running `crypto.PassphraseHash` in a loop allocates a lot of memory.
Golang is not always prudent about collecting the garbage from previous
runs, resulting in a OOM error on memory-pressured systems.

With a `maxMemoryBytes` of 128 MiB, this change reduces the maximum
resident memory for `fscrypt setup` to 141 MiB (was perviously 405 MiB)

Signed-off-by: Joe Richey <joerichey@google.com>

Only use 1/8 of the system RAM

On systems with high memory pressure, using half of the entire RAM for
hashing can result in fscrypt getting OOM killed.

Signed-off-by: Joe Richey <joerichey@google.com>

filesystem: skip TestHaveReadAccessTo() when running as root

Root can read all files, so this test fails when running as root.
Skip it instead.

Resolves https://github.com/google/fscrypt/issues/288

Specify -buildmode=c-shared after GO_FLAGS rather than before

When building pam_fscrypt.so, specify -buildmode=c-shared after
$(GO_FLAGS) so that it overrides any user-specified buildmode.

This is needed to allow -buildmode=pie to be specified in GO_FLAGS if
the packager wants to build fscrypt as a position-independent executable
(e.g. following https://wiki.archlinux.org/title/Go_package_guidelines).
Previously, trying to do this caused pam_fscrypt.so to be incorrectly
built as an executable rather than as a shared library.

cmd/fscrypt: fix word mismatch "protector" => "policy"

Fix word mismatch in usage and description of metadata create policy
command.

cmd/fscrypt: use golang.org/x/term

The golang.org/x/crypto/ssh/terminal package is deprecated and merely a
wrapper around golang.org/x/term. Thus, use the latter directly.

Makefile: Optionally avoid installation of Ubuntu-specific PAM config

This allows non Ubuntu distributions to opt out from the installation
of Ubuntu-specific PAM files.

Release version v0.3.0 (#282)

Merge pull request #283 from google/coverage

Stop generating and uploading coverage in CI

Only run CI on master branch and PRs to master

This avoids duplicate CI checks

Signed-off-by: Joe Richey <joerichey@google.com>

Stop generating and uploading coverage in CI

This is currently broken, and we don't really use the findings.

Signed-off-by: Joe Richey <joerichey@google.com>

Merge pull request #281 from ebiggers/pam_fscrypt-updates

pam_fscrypt: eliminate unnecessary options and improve documentation

README: improve PAM configuration documentation (again)

Make some more corrections:

- pam-config-framework isn't actually Ubuntu-specific but actually
  applies to Debian and any Debian derivative.

- The pam-config-framework file is indeed installed by `make install`,
  just not into the correct location.

- On Debian (and Debian derivatives), the PAM configuration isn't
  actually part of the 'fscrypt' package but rather 'libpam-fscrypt'.

- Clarify where to add the pam_fscrypt.so session hook.

README: make it clear that pam_fscrypt also handles locking

There are several mentions of pam_fscrypt handling unlocking
directories.  Make sure to mention locking alongside this.

pam_fscrypt: make "lock_policies" the default behavior

All pam_fscrypt configuration guides that I'm aware of say to use the
"lock_policies" option for the pam_fscrypt.so session hook.  The
Debian/Ubuntu pam-config-framework config file has it too.

Make locking the default behavior, since this is what everyone wants.

Existing configuration files that contain the "lock_policies" option
will continue to work, but that option won't do anything anymore.

(We could add an option "unlock_only" to restore the old default
behavior, but it's not clear that it would be useful.  So for
simplicity, leave it out for now.)

pam_fscrypt: decide cache dropping behavior automatically

Configuring whether pam_fscrypt drops caches or not isn't really
something the user should have to do, and it's also irrelevant for v2
encryption policies (the default on newer systems).  It's better to have
pam_fscrypt automatically decide whether it needs to drop caches or not.

Do this by making pam_fscrypt check whether any encryption policy keys
are being removed from a user keyring (rather than from a filesystem
keyring).  If so, it drops caches; otherwise it doesn't.  This
supersedes the "drop_caches" option, which won't do anything anymore.

pam_fscrypt/config: prioritise over other session modules

Services launched by systemd user sessions on Debian / Ubuntu systems
are often not able to access the home directory, because there is no
guarantee / requirement that pam_fscrypt is sequenced before
pam_systemd.

Although this pam-config mechanism is Debian-specific, the config file
is provided here upstream and unmodified in Debian. Raising the
priority here so that it's always ordered ahead of pam_systemd will
solve issues such as https://github.com/google/fscrypt/issues/270,
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=964951 and
https://bugs.launchpad.net/ubuntu/+source/systemd/+bug/1889416.

After a survey of pam-config files available in Debian bullseye, the
value of 100 was chosen as it appears after most other plugins that
could be involved in more explicit homedir configuration (eg pam_mount
at 128) but before those which seem unlikely to work without a home
directory (eg pam_ssh at 64).

ci.yml: always run apt-get update

In GitHub Workflows, apparently running 'apt-get update' before 'apt-get
install' is sometimes needed, and it doesn't hurt to always do it.

Avoid using the word "whitelist"

cmd/fscrypt: fix missing protector error format

Update #272

bash-completion: add completion script

README: Fix badge image

Workflow names are case-sensitive

Signed-off-by: Joe Richey <joerichey@google.com>

Switch from Travis CI to GitHub Actions

travis-ci.org is being shut down, so switch to GitHub Actions.

It should be mostly equivalent, but I did drop functionality in a couple
cases:

- Publishing release binaries.  I don't think providing Linux binaries
  is useful, since people build their own anyway.  So I left this out.

- Build and testing on ppc64le.  GitHub Actions only natively supports
  x86.  I tried uraimo/run-on-arch-action, which uses Docker and QEMU
  user-mode emulation, but the fscrypt tests can't be run because
  QEMU user-mode emulation doesn't support all the needed system calls.

cli-tests: force processes spawned by 'expect' to have 80 column-output

Otherwise the cli tests fail when executed from GitHub Actions.

README.md: add table of contents

travis.yml: upgrade to Ubuntu 20.04 and enable cli tests

Now that Travis CI supports a version of Ubuntu that has a kernel that
supports v2 encryption policies, upgrade to it and enable the cli tests.

cmd/fscrypt: fix race condition in getPassphraseKey()

Set the terminal to raw mode *before* printing the prompt.
Otherwise the user (or the automated test) might enter the
passphrase before the terminal gets put into raw mode.

This is needed for some of the CLI tests to pass reliably in Travis CI.

cli-tests/common.sh: fix _user_do()

Apparently, on some distros 'su' doesn't preserve $PATH.  So, manually
export it in the command.  Also, ensure that the shell stays as bash.

This is needed for some of the CLI tests to pass in Travis CI.

cmd/fscrypt: fix isDirUnlockedHeuristic() on latest kernels

On an "incompletely locked" directory, isDirUnlockedHeuristic() is
supposed to return true, but on Linux v5.10-rc1 and later it returns
false since now creating a subdirectory fails rather than succeeds.
This change was intentional, so make isDirUnlockedHeuristic() apply a
second heuristic too: also return true if any filenames in the directory
don't appear to be valid no-key names.

This fixes cli-tests/t_v1_encrypt on Linux v5.10-rc1 and later.

Travis-ci: added support for ppc64le (#257)

Fix nil error issue, Resolves https://github.com/google/fscrypt/issues/242

README.md: recommend 'sudo make install PREFIX=/usr' on Ubuntu (#244)

Ubuntu's PAM configuration framework only recognizes files in /usr, not
/usr/local.  So for installs from source, unfortunately we have to
recommend installing to /usr, despite this not being conventional.

Resolves https://github.com/google/fscrypt/issues/240

Release version v0.2.9 (#238)

Merge pull request #237 from ebiggers/t_v1_policy_fix

Adjust status message for v1 policies unlocked by another user and fix cli-tests/t_v1_policy

cmd/fscrypt: adjust status message for v1-encrypted dirs

When 'fscrypt status DIR' detects that a v1-encrypted directory is still
usable but its key seems to be absent, it shows the status as
"Unlocked: Partially (incompletely locked)".  But actually it can also
be the case that the directory is unlocked by another user.  Adjust the
status message accordingly.

This commit also fixes cli-tests/t_v1_policy.

cli-tests/t_v1_policy: clean up user keyrings at end of test

The test user's user keyring is still linked into root's user keyring at
the end of the test.  This is making the test flaky, as there is a
failure that only occurs the first time it is run.  Fix the test to
restore the initial state.  This makes it consistently fail (to be fixed
by the next commit).

Merge pull request #235 from ebiggers/32bit-fix

* cmd/fscrypt: fix 32-bit build
* travis.yml: build 32-bit binary

cmd/fscrypt: fix 32-bit build

statfs.Bsize actually has platform-dependent type, despite the Go
documentation listing it as int64.  Fix the build for 32-bit platforms
by casting it to int64.

Resolves https://github.com/google/fscrypt/issues/233

travis.yml: build 32-bit binary

Don't let people check in code that breaks 32-bit builds.

Update https://github.com/google/fscrypt/issues/233

Release version v0.2.8 (#230)

cmd/fscrypt: fix up path formatting in ErrDirNotEmpty suggestion (#229)

Use %q, in case the paths contain whitespace.  Also clean the directory
path to remove trailing slashes before appending the ".new" suffix.

cmd/fscrypt: link to guide when interactively creating login protector (#225)

Update https://github.com/google/fscrypt/issues/220

README.md: try to disambiguate "fscrypt" (#226)

Explicitly mention that "fscrypt" here means the userspace tool, not the
kernel part.  Also write `fscrypt` in code font to emphasize this.

README.md: further improve the "encryption not enabled" section (#227)

README.md: fix typo "nrounds" => "rounds" (#228)

Update https://github.com/google/fscrypt/issues/220

README.md: improve documentation for login protectors (#223)

Update https://github.com/google/fscrypt/issues/220

Declare instead of define variable in header file. (#224)

This fixes link error with gcc 10 which defaults to -fno-common

Merge pull request #219 from ebiggers/improve-errors

Improve error messages and suggestions

cmd/fscrypt: improve errors

In checkEncryptable(), check whether the directory is already encrypted
before checking whether it's empty.

Also improve the error message for when a directory is nonempty.

Finally, translate keyring.ErrKeyAddedByOtherUsers and
keyring.ErrKeyFilesOpen into errors which include the directory.

cmd/fscrypt: remove ErrMaxPassphrase

This isn't actually a valid error since crypto.NewKeyFromReader()
handles re-allocating the buffer to a larger size if it fills up.

filesystem: improve errors

Introduce filesystem.ErrEncryptionNotEnabled and
filesystem.ErrEncryptionNotSupported which include the Mount as context,
and translate the corresponding metadata/ errors into them.  Then make
these errors show much better suggestions.

Also replace lots of other filesystem/ errors with either custom types
or with unnamed one-off errors that include more context.  Fix backwards
wrapping in lots of cases.

Finally, don't include the mountpoint in places where it's not useful,
like OS-level errors that already include the path.

metadata: improve errors

ErrBadOwners:
Rename to ErrDirectoryNotOwned for clarity, move it from
cmd/fscrypt/ to metadata/ where it better belongs, and improve
the message.

ErrEncrypted:
Rename to ErrAlreadyEncrypted for clarity, and include the path.

ErrNotEncrypted:
Include the path.

ErrBadEncryptionOptions:
Include the path and bad options.

ErrEncryptionNotSupported:
ErrEncryptionNotEnabled:
Don't wrap with "get encryption policy %s", in preparation for
wrapping these with filesystem-level context instead.

Also avoid mixing together the error handling for the "get policy" and
"set policy" ioctls.  Make it very clear how we're handling the errors
from each ioctl.

keyring: improve errors

ErrAccessUserKeyring:
Include the user, and fix the backwards wrapping.

ErrSessionUserKeyring:
Include the user.

ErrKeyAdd:
ErrKeyRemove:
ErrKeySearch:
ErrLinkUserKeyring:
Replace these with one-off unnamed errors because they are
never checked for, and this makes it easier for the callers to
provide better messages, e.g. fixing the backwards wrapping.

crypto: improve errors

ErrKeyLock:
Rename to ErrMlockUlimit for clarity.

ErrGetrandomFail:
ErrKeyAlloc:
ErrKeyFree:
ErrNegativeLength:
Replace these with one-off unnamed errors because these were all
returned in only one place and were never checked for.  Also
these were all either wrapped backwards or discarded an
underlying error, so fix that too.

actions/policy: improve errors

ErrMissingPolicyMetadata:
Include the mount, directory path, and metadata path.  Also move
the explanation into actions/ since it doesn't refer to any CLI
command.

ErrPolicyMetadataMismatch:
Include a lot more information.  Also start checking for
consistency of the policy key descriptors, not just the
encryption options.  Add a test for this.

ErrDifferentFilesystem:
Include the mountpoints.

ErrOnlyProtector:
Clarify the message and include the protector descriptor.

ErrAlreadyProtected:
ErrNotProtected:
Include the policy and protector descriptors.

ErrAccessDeniedPossiblyV2:
Make it slightly clearer what failed.  Also move the explanation
into actions/ since it doesn't refer to any CLI command.

actions/protector: improve errors

ErrProtectorName:
Rename to ErrLoginProtectorName for clarity, and include the
name and user.

ErrMissingProtectorName:
Include the correct protector source.

ErrDuplicateName:
Rename to ErrProtectorNameExists for clarity, and remove a level
of wrapping by including the name directly.

ErrDuplicateUID:
Rename to ErrLoginProtectorExists for clarity, and remove a
level of wrapping by including the user directly.

actions/config: improve config file related errors

ErrBadConfig:
Fix backwards wrapping, include the bad config, and make it
clear that this is an internal error.

ErrBadConfigFile:
Fix backwards wrapping, include the config file location, and
adjust the suggestion slightly.

ErrConfigFileExists:
Include the config file location.

ErrNoConfigFile:
Include the config file location, and adjust the suggestion
slightly.

cmd/fscrypt: make wrapText() support code blocks

Allow the input text to contain "code blocks" denoted by lines beginning
with ">", e.g.:

    Foo bar baz:

    > echo foo
    > echo bar

Instead of squashing these lines together, preserve the line breaks
between them and add indentation, e.g.:

    Foo bar baz:

        echo foo
        echo bar

Merge pull request #217 from ebiggers/detect-incomplete-v1-locking

Try to detect incomplete locking of v1-encrypted directory

Try to detect incomplete locking of v1-encrypted directory

'fscrypt lock' on a v1-encrypted directory doesn't warn about in-use
files, as the kernel doesn't provide a way to easily detect it.

Instead, implement a heuristic where we check whether a subdirectory can
be created.  If yes, then the directory must not be fully locked.

Make both 'fscrypt lock' and 'fscrypt status' use this heuristic.

Resolves https://github.com/google/fscrypt/issues/215

keyring/user_keyring: switch to KEYCTL_UNLINK

KEYCTL_INVALIDATE has complicated semantics: it doesn't remove the key
from the keyring right away but rather marks it as being invalidated,
and then removes it asynchronously.  This nondeterministically breaks
the heuristic I'm implementing to detect v1-encrypted directories being
incompletely locked.

Instead, switch to KEYCTL_UNLINK, which has simpler semantics.

Note that Android uses KEYCTL_UNLINK too.

Merge pull request #218 from ebiggers/cli-tests

Add tests for command-line interface

Add tests that directly test the fscrypt command-line tool.

See cli-tests/README.md for information about the test framework.

The following test scripts are included:

* t_change_passphrase
* t_encrypt_custom
* t_encrypt_login
* t_encrypt_raw_key
* t_encrypt
* t_lock
* t_not_enabled
* t_not_supported
* t_passphrase_hashing
* t_setup
* t_status
* t_unlock
* t_v1_policy_fs_keyring
* t_v1_policy

Unfortunately, we can't actually make Travis CI run these tests yet because they need kernel v5.4 or later, and Travis CI doesn't support an Ubuntu version that has that yet. But for now, they can be run manually using make cli-test.

cli-tests: add t_v1_policy_fs_keyring

Test using v1 encryption policies (deprecated) with
use_fs_keyring_for_v1_policies = true.

cli-tests: add t_v1_policy

Test using v1 encryption policies (deprecated).

cli-tests: add t_unlock

Test unlocking a directory.

cli-tests: add t_status

Test getting global, filesystem, and unencrypted directory status when
the filesystem is or isn't set up for fscrypt.

cli-tests: add t_setup

Test 'fscrypt setup'.

cli-tests: add t_passphrase_hashing

Test that the passphrase hashing seems to take long enough.

cli-tests: add t_not_supported

Test that fscrypt fails when the filesystem doesn't support encryption.

cli-tests: add t_not_enabled

Test that fscrypt fails when the filesystem doesn't have the encrypt
feature enabled.  Then test enabling it.

cli-tests: add t_lock

Test locking a directory.

cli-tests: add t_encrypt_raw_key

Test encrypting a directory using a raw_key protector.

cli-tests: add t_encrypt_login

Test encrypting a directory using a login (pam_passphrase) protector.

cli-tests: add t_encrypt_custom

Test encrypting a directory using a custom_passphrase protector.

cli-tests: add t_encrypt

Add general tests for 'fscrypt encrypt'.  For protector-specific tests,
see t_encrypt_custom, t_encrypt_login, and t_encrypt_raw_key.

cli-tests: add t_change_passphrase

Test changing the passphrase of a custom_passphrase protector.

Wire up shellcheck of cli-tests/*.sh to 'make lint'

Enforce that all the cli-test scripts pass 'shellcheck'.

Add cli-tests framework

Add a framework for writing automated tests of the fscrypt command-line
tool.  See cli-tests/README.md for details.

cmd/fscrypt: add FSCRYPT_CONSISTENT_OUTPUT environmental variable

Allow setting FSCRYPT_CONSISTENT_OUTPUT=1 in the environment to cause
policies and protectors to sorted by last modification time.  The CLI
tests need this to make the output of 'fscrypt' ordered in a consistent
way with regard to the operations performed.

cmd/fscrypt: add FSCRYPT_ROOT_MNT environmental variable

Allow overriding the mountpoint where login protectors are stored by
setting the FSCRYPT_ROOT_MNT environmental variable.  The CLI tests need
this to avoid touching the real "/".

cmd/fscrypt: add FSCRYPT_CONF environmental variable

Allow overriding the location of fscrypt.conf by setting the
FSCRYPT_CONF environmental variable.  The CLI tests need this to avoid
touching the real /etc/fscrypt.conf.

travis.yml: stop overriding e2fsprogs version (#222)

There's no longer a need to override the Ubuntu version that the
Travis CI builds install e2fsprogs from, since we now use
"dist: bionic", and e2fsprogs in Bionic supports encryption.

keyring: cast FS_IOC_REMOVE_ENCRYPTION_KEY to uintptr (#221)

Since v0.2.6, fscrypt only builds for 64-bit systems.  E.g. trying to
build on Raspbian fails with the following error:

  $ go get github.com/google/fscrypt/cmd/fscrypt
  # github.com/google/fscrypt/keyring
  go/src/github.com/google/fscrypt/keyring/fs_keyring.go:231:6: constant 3225445912 overflows int
  go/src/github.com/google/fscrypt/keyring/fs_keyring.go:235:7: constant 3225445913 overflows int

Fix it by making the 'ioc' variable have type uintptr.

[EB - removed the later cast to uintptr that became unnecessary, and
 added explanation to commit message.]