diff options
| -rw-r--r-- | CONTRIBUTING.md | 7 | ||||
| -rw-r--r-- | Makefile | 34 | ||||
| -rw-r--r-- | README.md | 68 |
3 files changed, 91 insertions, 18 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1470fa4..7272b10 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,9 +30,10 @@ these commands when writing your code. ### Building and Testing -As mentioned in `README.md`, running `make` will build the fscrypt executable. -Running `make go` will build each package and run the tests, but just running -`make go` with nothing else will skip the integration tests. +As mentioned in `README.md`, running `make` will build the fscrypt executable +and the PAM module `pam_fscrypt.so`. Running `make go` will build each package +and run the tests, but just running `make go` with nothing else will skip the +integration tests. To run the integration tests, you will need a filesystem that supports encryption. If you already have some empty filesystem at `/foo/bar`, just run: @@ -16,11 +16,16 @@ # the License. NAME = fscrypt +PAM_NAME = pam_$(NAME) +PAM_MODULE = $(PAM_NAME).so -INSTALL = install -DESTDIR = /usr/local/bin +INSTALL ?= install +DESTDIR ?= /usr/local/bin +PAM_MODULE_DIR ?= /lib/security +PAM_CONFIG_DIR ?= /usr/share/pam-configs CMD_PKG = github.com/google/$(NAME)/cmd/$(NAME) +PAM_PKG = github.com/google/$(NAME)/$(PAM_NAME) SRC_FILES = $(shell find . -type f -name '*.go' -o -name "*.h" -o -name "*.c") GO_FILES = $(shell find . -type f -name '*.go' -not -path "./vendor/*") @@ -81,15 +86,20 @@ override GO_LINK_FLAGS += $(VERSION_FLAG) $(DATE_FLAG) -extldflags "$(LDFLAGS)" override GO_FLAGS += --ldflags '$(GO_LINK_FLAGS)' .PHONY: default all -default: $(NAME) + +default: $(NAME) $(PAM_MODULE) all: update format lint default test $(NAME): $(SRC_FILES) go build $(GO_FLAGS) -o $(NAME) $(CMD_PKG) +$(PAM_MODULE): $(SRC_FILES) + go build -buildmode=c-shared $(GO_FLAGS) -o $(PAM_MODULE) $(PAM_PKG) + rm -f $(PAM_NAME).h + .PHONY: clean clean: - rm -rf $(NAME) $(IMAGE) + rm -f $(NAME) $(PAM_MODULE) $(IMAGE) # Make sure go files build and tests pass. .PHONY: test @@ -129,14 +139,22 @@ lint: @golint $(GO_PKGS) | grep -v "pb.go" | ./input_fail.py @megacheck -unused.exported $(GO_PKGS) -.PHONY: install -install: $(NAME) +###### Installation commands ##### +.PHONY: install_bin install_pam install uninstall +install_bin: $(NAME) $(INSTALL) -d $(DESTDIR) $(INSTALL) $(NAME) $(DESTDIR) -.PHONY: uninstall +install_pam: $(PAM_MODULE) + $(INSTALL) -d $(PAM_MODULE_DIR) + $(INSTALL) $(PAM_MODULE) $(PAM_MODULE_DIR) + $(INSTALL) -d $(PAM_CONFIG_DIR) + $(INSTALL) $(PAM_NAME)/config $(PAM_CONFIG_DIR)/$(NAME) + +install: install_bin install_pam + uninstall: - rm -rf $(DESTDIR)/$(NAME) + rm -f $(DESTDIR)/$(NAME) $(PAM_MODULE_DIR)/$(PAM_MODULE) $(PAM_CONFIG_DIR)/$(NAME) # Install the go tools used for checking/generating the code .PHONY: go-tools @@ -99,7 +99,6 @@ The following functionality is planned: * `fscrypt backup` - Manages backups of the fscrypt metadata * `fscrypt recovery` - Manages recovery keys for directories * `fscrypt cleanup` - Scans filesystem for unused policies/protectors -* A PAM module to support login passphrase changes (see below) See the example usage section below or run `fscrypt COMMAND --help` for more information about each of the commands. @@ -109,7 +108,7 @@ information about each of the commands. fscrypt has the following build dependencies: * [Go](https://golang.org/doc/install) * A C compiler (`gcc` or `clang`) -* `make` +* `make` * The [Argon2 Passphrase Hash](https://github.com/P-H-C/phc-winner-argon2) library, which can be [directly installed on Artful Ubuntu](https://packages.ubuntu.com/artful/libargon2-0-dev), @@ -155,6 +154,50 @@ fscrypt has the following runtime dependencies: The dynamic libraries are not needed if you built a static executable. +### Setting up the PAM module + +Note that to make use of the installed PAM module, your +[PAM configuration files](http://www.linux-pam.org/Linux-PAM-html/sag-configuration.html) +in `/etc/pam.d` must be modified to add fscrypt. + +#### Automatic setup on Ubuntu + +fscrypt automatically installs the +[PAM config file](https://wiki.ubuntu.com/PAMConfigFrameworkSpec) +`pam_fscrypt/config` to `/usr/share/pam-configs/fscrypt`. This file contains +reasonable defaults for the PAM module. To automatically apply these changes, +run `sudo pam-auth-update` and follow the on-screen instructions. + +#### Manual setup + +The fscrypt PAM module implements the Auth, Session, and Password +[types](http://www.linux-pam.org/Linux-PAM-html/sag-configuration-file.html). + +The Password functionality of `pam_fscrypt.so` is used to automatically rewrap +a user's login protector when their unix passphrase changes. An easy way to get +the working is to add the line: +``` +password optional pam_fscrypt.so +``` +after `pam_unix.so` in `/etc/pam.d/common-password` or similar. + +The Auth and Session functionality of `pam_fscrypt.so` are used to automatically +unlock directories when logging in as a user. An easy way to get this working is +to add the line: +``` +auth optional pam_fscrypt.so +``` +after `pam_unix.so` in `/etc/pam.d/common-password` or similar, and to add the +line: +``` +session optional pam_fscrypt.so drop_caches +``` +after `pam_unix.so` in `/etc/pam.d/common-session` or similar. The `drop_caches` +option tells fscrypt to clear the filesystem caches on session closes if some +directories were unlocked. This ensures all unlocked data is inaccessible after +session close. All the types also support the `debug` option which prints +additional debug information to the syslog. + ## Note about stability fscrypt follows [semantic versioning](http://semver.org). As such, all versions @@ -507,14 +550,25 @@ best to help. #### 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: +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. + +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: ``` -fscrypt metadata change-passphrase --protector=MOUNTPOINT:ID +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. + #### I can still see files or filenames after running `fscrypt purge MOUNTPOINT` You need to unmount `MOUNTPOINT` to clear the necessary caches. See |