NAME

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

SYNOPSIS

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.