Updated documentation and build system for PAM

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:
diff --git a/Makefile b/Makefile
index 4ebbe32..c5b43ce 100644
--- a/Makefile
+++ b/Makefile
@@ -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
diff --git a/README.md b/README.md
index e2df8ca..4355239 100644
--- a/README.md
+++ b/README.md
@@ -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