UNIX-SELFAUTH-HELPER(8)

NAME
unix-selfauth-helper - local self-authentication for pam_exec

SYNOPSIS
unix-selfauth-helper

DESCRIPTION
The unix-selfauth-helper utility is designed to be called by pam_exec(8) and enables unprivileged authentication against the local passwd(5) database for the user calling it. This is useful especially for screen lockers that would otherwise need their own suid-root helper.

To use it, add it to the auth stack as sufficient above pam_unix(8). Required options for pam_exec(8) are return_prog_exit_status and expose_authtok.

ENVIRONMENT

PAM_SM_FUNC
    must be set to pam_sm_authenticate, every other value is ignored with an error exit status.

PAM_USER
    the name of the user to authenticate, must match the user attempting the authentication.

FILES

/usr/local/etc/pam.d/unix-selfauth
    An example PAM policy prepending unix-selfauth-helper to the auth facility and delegating anything else to system. This can be used with include in your own policy or you can just set a symlink if it is all you need.

EXAMPLES

    auth		sufficient	pam_exec.so	\
    		return_prog_exit_status expose_authtok \
    		/usr/local/libexec/unix-selfauth-helper
    auth		include		system
    # account	include		system
    # session	include		system
    # password	include		system

This PAM configuration enables self-authentication in addition to whatever is configured system-wide for PAM. It must be placed in /usr/local/etc/pam.d, named like the PAM service policy.

Only the auth facility is active in this example, the others are commented. Add them if your service policy needs them.

Hint for port maintainers: If you want to include a service policy in your port, replace /usr/local with %%LOCALBASE%% and include the file in SUB_FILES. Alternatively, you can either include or symlink to the unix-selfauth PAM policy installed with this utility, it delegates everything to system and just prepends the unix-selfauth-helper to auth.

SEE ALSO
passwd(5), pam_exec(8), pam_unix(8)

AUTHORS
Felix Palmen <zirias@FreeBSD.org>

BUGS
This is a hack that shouldn't be necessary.

The underlying problem is that PAM authentication might require root privileges, depending on the modules used. This is typically true for pam_unix(8) because it needs to read the passwd(5) database.

A clean solution could be an authentication service in base that's queried by pam_unix(8) instead of accessing the passwd(5) database directly.

SECURITY CONSIDERATIONS
The unix-selfauth-helper utility is installed suid-root, so it can access the passwd(5) database. It drops privileges as early as possible, but it could be used for guessing the password of a user, if an attacker has access to an unlocked session of that user.