Skip to content
Combine ZFS and PAM to encrypt home directories on Linux
C Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
include
src
test
.gitignore
LICENSE
Makefile
README.md

README.md

zfscrypt

zfscrypt implements a Linux Pluggable Authentication Module that encrypts users home directories with their login password leveraging ZFS native encryption. The concept was heavily inspired by Google's fscrypt.

Warning: This is my first project written in C. It might contain severe security issues.

Building & Installing

Build dependencies

zfscrypt has the following build dependencies:

  • gcc or clang
  • make
  • libpam headers
  • libzfs headers
  • libnvpair headers

Depending on your distribution the libraries might be packaged as libpam-dev, libzfs-devel or something similar.

Runtime dependencies

zfscrypt requires ZFS v0.8.0 or later. You can check the version with:

zfs -V

Additionally following libraries must be present:

  • libpam.so
  • libzfs.so
  • libnvpair.so

This libraries should be almost certainly already on your system. As long as you use ZFS at least.

Setup

Note: zfscrypt was tested on Arch Linux with pam v1.3.1 and zfs v0.8.2.

Build the PAM module.

make

Install (or update) the module.

sudo make install

Unfortunately PAM configuration is a bit of a mess, because every distribution configures PAM differently. So you have to adapt the following example to your distribution.

Append this line to the auth section in /etc/pam.d/system-login:

auth optional pam_zfscrypt.so

And append this two lines to the session section:

session [success=1 default=ignore] pam_succeed_if.so service = systemd-user quiet
session optional pam_zfscrypt.so

The first line is needed to work around some quirks in systemd.

ZFS encryption enforces a minimum password length of eight characters. So if you use pam_unix.so and/or pam_cracklib.so add minlen=8 to their module arguments in /etc/pam.d/passwd. It should look something like this:

password required pam_unix.so sha512 shadow minlen=8

Finally append the next line to etc/pam.d/passwd:

password optional pam_zfscrypt.so

Having problems with PAM? Maybe the official documentation or one of this Arch Wiki pages pam, fscrypt can help you.

Configuration

The behaivor of zfscrypt can be altered with the following, optional module arguments:

Argument Description
runtime_dir where to store session counters, defaults to /run/zfscrypt
free_inodes enables freeing of reclaimable inodes and dentries on logout, which might bring security benefits and/or performance problems
debug enables verbose logging

Example entry in /etc/pam.d/system-login:

session optional pam_zfscrypt.so runtime_dir=/tmp/zfscrypt free_inodes debug

Features & Usage

All datasets with the following properties will be automatically unlocked when the corresponding user logs in (and locked after logout).

Property Value
io.github.benkerry:zfscrypt_user user name
encryption not off
keyformat passphrase
keylocation prompt
canmount not off

Create a new user with zfscrypt

The encryption key and the login password must be the same, otherwise automatic unlocking won't work. Future password changes will update the encryption key automatically.

zfs create -o mountpoint=/home tank/home
zfs create -o io.github.benkerry:zfscrypt_user=ben -o encryption=on -o keyformat=passphrase -o keylocation=prompt -o canmount=noauto tank/home/ben
zfs mount tank/home
zfs mount tank/home/ben
useradd --create-home ben
zfs allow -u ben load-key,change-key,mount tank/home/ben 
passwd ben

Migrate an existing user to zfscrypt

mv /home/ben /home/_ben
zfs create -o io.github.benkerry:zfscrypt_user=ben -o encryption=on -o keyformat=passphrase -o keylocation=prompt -o canmount=noauto -o mountpoint=/home/ben tank/home/ben
zfs allow -u ben load-key,change-key,mount tank/home/ben
zfs mount tank/home/ben
chown ben:ben /home/ben
chmod 0700 /home/ben
cp -ar /home/_ben/. /home/ben/
rm -rf /home/_ben
You can’t perform that action at this time.