KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #open-source #agent-skills #ai #dsh-plugin #llm #windows

libpam-policycache

★ 35 Open GitHub ↗

Password caching module with advanced policies for PAM.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Overview

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.

# Module Configuration

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`.

## Example

```
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
```

# Policy Configuration

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 return `new_authtok_req` instead of `success`. 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.

## TODO

* 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.

## Example

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
```

# Cache Storage

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'>}
```

# User Applications

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. It checks in
advance that the user calling it is the same user as the one who should be
authenticated so it doesn't work for cases like web oder mail servers who check
system users.

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.

## Example

```
# /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
```

# Building

Built with autotools and includes an autogen.sh script:

1. ./autogen.sh (not needed when using source tarball)
2. ./configure
3. make
4. make check
5. sudo make install

Dependencies:

* GLib
* Linux-PAM
* libscrypt
* Autoconf, Automake, Libtool

libpam-policycache

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README