pam_zfs_key - PAM user credential module for ZFS
pam_zfs_key.so.1 [create] [homes=]
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 user's 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 the user's home directory is located on a different ZFS dataset than rpool/export/home, 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 user's login name. If the user's 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:
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.
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 user's 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 new ZFS datasets
Set the ZFS encryption property for create
Attempt a umount2(2) with a MS_FORCE of the dataset when doing PAM_DELETE_CRED.
Alternate location of ZFS datasets for user home directories. The default is rpool/export/home.
Do not provide any error messages or warnings.
The following example uses pam_zfs_key in default mode.
gdm-password auth requisite pam_authtok_get.so.1 gdm-password auth required pam_unix_cred.so.1 gdm-password auth required pam_unix_auth.so.1 gdm-password auth optional pam_zfs_key.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.1Example 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-password auth requisite pam_authtok_get.so.1 gdm-password auth required pam_unix_cred.so.1 gdm-password auth required pam_unix_auth.so.1 gdm-password auth optional pam_zfs_key.so.1 homes=tank/users \ create encryption=aes-256-gcmExample 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-password auth requisite pam_authtok_get.so.1 gdm-password auth required pam_unix_cred.so.1 gdm-password auth required pam_unix_auth.so.1 gdm-password auth required pam_zfs_key.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
See attributes(7) 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.
umount2(2), libpam(3LIB), pam(3PAM), pam_sm_chauthtok(3PAM), pam_sm_setcred(3PAM), pam.conf(5), attributes(7), zfs(8)