pam_zfs_key

- PAM user credential module for ZFS

Synopsis

pam_zfs_key.so.1 [create] [homes=]

Description

The pam_zfs_key module implements pam_sm_setcred(3PAM) and pam_sm_chauthtok(3PAM).

The pam_zfs_key module provides functions that allow loading and changing of the ZFS encryption passphrase for encrypted file systems that are mounted at the users home directory location. Authentication service modules must implement both pam_sm_authenticate() and pam_sm_setcred().

pam_sm_authenticate() in this module always returns PAM_IGNORE. If they are located at a different location then the module option, homes= can be used to specify that. It is the ZFS dataset name, not the mountpoint, which would usually be /export/home/.

The last component of the ZFS dataset name must match the value of PAM_USER, that is, the users login name. If the users home directory is a local ZFS filesystem with encryption enabled and the ZFS keysource property is set to passphrase,prompt, on pam_sm_setcred() this module manages the keys as follows:

PAM_DELETE_CRED

Attempts to umount the filesystem and unload the key. This often fails because there are still processes with the user's home directory as the current working directory. A force module option is provided to attempt a forced unmount first.

PAM_ESTABLISH_CRED

Attempts to use the value of PAM_AUTHTOK to load the key for the ZFS dataset and mount it.

If PAM_AUTHTOK is not the correct passphrase, the user is prompted once for an alternate. This value is never stored in PAM_AUTHTOK, even if it is the correct passphrase for the ZFS dataset that is the users home directory. This is equivalent to:

zfs key -l rpool/export/home/$USER

If no ZFS file system exists for the user and the create module option is provided, a new one is created. The ZFS encryption property defaults to on in this case unless the encryption= property is set for the module to override it.

If the create module option is not provided and no ZFS file system exists for the user, the module returns PAM_IGNORE.

The newly created ZFS file system has the following ZFS delegations specified for the user for which it is created: key,keychange,mount. In these cases keysource is always set to passphrase,prompt.

When pam_sm_chauthtok(3PAM) is called, for example, on password change, this module attempts to change the passphrase for the ZFS dataset to match the value in PAM_AUTHTOK. This is equivalent to running:

zfs key -c rpool/export/home/$USER

This requires that the user have the keychange delegation, as password change usually runs as the user.

The following mount options are supported:

create

Create new ZFS datasets

encryption

Set the ZFS encryption property for create

force

Attempt a umount2(2) with a MS_FORCE of the dataset when doing PAM_DELETE_CRED.

homes=

Alternate location of ZFS datasets for user home directories. The default is rpool/export/home.

nowarn

Do not provide any error messages or warnings.

Examples

Example 1 Using pam_zfs_key in Default Mode

The following example uses pam_zfs_key in default mode.

gdm     auth requisite          pam_authtok_get.so.1
gdm     auth required           pam_dhkeys.so.1
gdm     auth required           pam_unix_cred.so.1
gdm     auth required           pam_unix_auth.so.1
gdm     auth optional           pam_zfs_key.so.1

other   password required       pam_dhkeys.so.1
other   password requisite      pam_authtok_get.so.1
other   password requisite      pam_authtok_check.so.1
other   password required       pam_authtok_store.so.1
other   password optional       pam_zfs_key.so.1

Example 2 Specifying an Alternate ZFS Dataset

The following example specifies an alternate ZFS dataset location for the home directory file systems. New entries should be created if they are not present using aes-256-gcm as the ZFS encryption property setting.

gdm auth requisite  pam_authtok_get.so.1
gdm auth required   pam_dhkeys.so.1
gdm auth required   pam_unix_cred.so.1
gdm auth required   pam_unix_auth.so.1
gdm auth optional   pam_zfs_key.so.1 homes=tank/users \
create encryption=aes-256-gcm

Example 3 Making it Mandatory for the ZFS Dataset to Mount

The following example makes it mandatory for the ZFS dataset to mount and ensures the passphrase always stays in sync with the login password.

gdm     auth requisite          pam_authtok_get.so.1
gdm     auth required           pam_dhkeys.so.1
gdm     auth required           pam_unix_cred.so.1
gdm     auth required           pam_unix_auth.so.1
gdm     auth required           pam_zfs_key.so.1

other   password required       pam_dhkeys.so.1
other   password requisite      pam_authtok_get.so.1
other   password requisite      pam_authtok_check.so.1
other   password requisite      pam_zfs_key.so.1
other   password required       pam_authtok_store.so.1

Attributes

See attributes(5) for descriptions of the following attributes:

The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle.

See Also

zfs(1M), umount2(2), pam.conf(4), libpam(3LIB), pam(3PAM), pam_sm_chauthtok(3PAM), pam_sm_setcred(3PAM), attributes(5)