Caches passwords from other PAM modules and bypasses those modules based on a configurable policy.
Why use libpam-policycache?
- Allows users to login when network is down.
- Reduces latency and load on remote login services.
- Restricts cache usage to specific users and groups.
- Enforces policies like cached password lifetime and rotation.
Arguments:
action=check
: Prompt the user for a password and check it against the cache.action=update
: Set the user's cached password to the last successful password in the stack.try_first_pass
: Try to use the password from a previous module (check only).use_first_pass
: Only use the password from a previous module (check only).policy=<path-glob>
: Default path-glob is/etc/libpam-policycache.d/*.policy
.storage=<path>
: Default path is/var/cache/libpam-policycache
.
auth [success=2 new_authtok_reqd=ok default=ignore] pam_policycache.so action=check
auth [success=ok new_authtok_reqd=ok default=die] pam_krb5.so use_first_pass
auth [default=ignore] pam_policycache.so action=update
Each policy file is INI-style with one section for each potential policy. The first of the most specific matching sections is chosen.
The section's name describes who the policy applies to:
user:<name>
group:<name>
netgroup:<name>
Each section has a combination of attributes:
tries
: Maximum number of failed attempts before entry is invalid.refresh
: Duration (1h, 5d, 3w) an entry stays valid between successful uses (action=check).renew
: Duration after the last update (action=update) when a successful use (action=check) will returnnew_authtok_req
instead ofsuccess
. Used when a password should be tried against another module opportunistically before the entry expires.expire
: Duration after the last update (action=update) when the cache entry is marked invalid.
- Add a
backoff
timer to rate-limit renew attempts. - Add a
reset-tries
timer to reset the try count on an entry. - Choose between "best-match" and "first-match" for the preferred policy.
In the following example policy, user "janedoe" may be the owner of the machine and her login experience is similar to having a password in /etc/shadow. Her password only needs to be checked by another module once a year.
Others in the "users" group may also use the cache, but only for a short time. Their entries are evicted from the cache after an hour without use or two days without being verified again using another module.
# /etc/libpam-policycache.d/foo.policy
[user:janedoe]
renew: 1w
expire: 52w
[group:users]
tries: 3
refresh: 1h
renew: 1d
expire: 2d
Policy entries are stored in /var/cache/libpam-policycache by default. Each entry is stored in a file for the user it belongs to.
The cache entry format is human-readable for easier debugging:
{'version': <1>, 'tries': <0>, 'algorithm': <'SHA256'>, 'salt': <'0B8BAA809CDCA339910EE8F6F9FE22A5'>, 'hash': <'14BABCBC943B302EFDCC137419F7D3FB736602D77CF42975A6778A5B7F2D63CD'>, 'last_verified': <'2014-03-28T23:14:21Z'>, 'last_used': <'2014-03-28T23:14:21Z'>, 'last_tried': <'2014-03-28T23:14:21Z'>}
Applications like screensavers that try to use the cache directly will be
denied, since the cache directory is only usable by root. Those applications
should use pam_escalate.so
instead, which proxies the authentication prompt(s)
through a pipe to a setuid-root helper called pam-escalate-helper
. The helper
calls pam_start()
and pam_authenticate()
just like an application would, and
it always uses /etc/pam.d/escalate
for the service configuration.
The escalate module clears all environment variables, ignores some PAM items,
and only implements pam_sm_authenticate()
so it may not cover all use cases.
At some point before or during the 1.0 release, the escalate module will be moved to its own project.
# /etc/pam.d/gnome-screensaver
auth requisite pam_escalate.so
# /etc/pam.d/escalate
# Include common-auth where cache check/update and other auth modules live.
@include common-auth
Built with autotools and includes an autogen.sh script:
- ./autogen.sh (not needed when using source tarball)
- ./configure
- make
- make check
- sudo make install
Dependencies:
- GLib
- Linux-PAM
- Autoconf, Automake, Libtool