Use pam_timestamp to Cache a Recent PAM Authentication

pam_timestamp lets a PAM service accept a recently successful authentication without asking for the password again. This guide configures it for one service, keeps the normal password module in the stack, checks the five-minute default, and shows how to clear the cache. The result is a deliberately small authentication window, not a replacement for password authentication.

These instructions match the installed Linux-PAM package on this machine, libpam-modules:amd64 1.5.3-5ubuntu5.7. Allow about 15 minutes if you already know the PAM service you are changing. You need root access, a second root-capable session for recovery, and a service whose PAM configuration you have identified. Do not experiment first with sshd, a display manager, or a login service on your only access path.

Checkpoint 1: identify the service

PAM configuration is selected by service name. A file such as /etc/pam.d/example-admin is read when the application opens the example-admin PAM service. The module line belongs in that file, not in a shell profile and not in the application's command line.

Choose a real service and inspect its existing stack as root:

sudo sed -n '1,200p' /etc/pam.d/EXAMPLE_SERVICE

Replace EXAMPLE_SERVICE with the file's basename. Find the existing auth line that performs the ordinary password check, usually a line using pam_unix.so. Also find the session stack. Save a copy before editing:

sudo cp -p /etc/pam.d/EXAMPLE_SERVICE /etc/pam.d/EXAMPLE_SERVICE.before-pam-timestamp

That backup is your first recovery path. PAM syntax and ordering matter, so preserve the distribution's existing lines and make the smallest possible addition.

Checkpoint 2: add the cache to the PAM stack

Put the authentication line immediately before the ordinary password module, then add the session line after the service's existing session modules. The resulting shape is:

auth sufficient pam_timestamp.so verbose
auth required   pam_unix.so

session required pam_unix.so
session optional pam_timestamp.so

sufficient means a valid recent timestamp can finish the authentication stack when no earlier required module has failed. If the timestamp is absent or expired, pam_timestamp fails and PAM continues to pam_unix.so, which asks for the password. The session module creates or updates the timestamp after a successful session. The two module types are separate: adding only the auth line does not create a useful cache.

The verbose option asks the module to inform the user when access is granted. Keep it while testing so a skipped password prompt is visible. If the service has several authentication stacks, edit only the one belonging to the operation you intend to change. Use elevated privileges for the edit:

sudoedit /etc/pam.d/EXAMPLE_SERVICE

There is no general PAM configuration checker that can prove a stack is safe for every application. Treat a syntax or ordering mistake as a possible lockout. Keep the second administrative session open until you have tested both the cached and uncached paths.

Checkpoint 3: set a deliberate timeout

The module's default timestamp_timeout is 300 seconds, or five minutes, measured from the timestamp file's last modification time. You can leave that default explicit in the module line, or choose a shorter period:

auth sufficient pam_timestamp.so timestamp_timeout=120 verbose

This example permits the cached authentication for 120 seconds. The value is in seconds. A longer value makes the convenience window larger and the unattended-session risk larger with it. Do not treat the cache as a way to make a privileged service permanently passwordless.

By default the module stores timestamp files below /var/run/pam_timestamp/.... An alternate timestampdir=directory can be supplied, but changing the directory changes where authentication state is kept and may require matching ownership and permissions. Use the default unless you have a specific operational reason and have checked the directory policy on this host.

Checkpoint 4: verify both paths

Start with a fresh cache. The installed helper checks the default timestamp and reports validity through its exit status. It is a setuid-root utility; its manual page lists status 2 when it is not installed with that privilege:

pam_timestamp_check
printf 'exit=%s\n' "$?"

Before a successful authentication, the expected result is normally exit=7, meaning that the timestamp is not valid. The helper can also check a target user when authentication is being performed as another user:

pam_timestamp_check TARGET_USER
printf 'exit=%s\n' "$?"

Run the configured service once and enter the password. Then check again:

pam_timestamp_check
printf 'exit=%s\n' "$?"

A valid cache returns exit=0. Repeat the service operation within the timeout and confirm that its password prompt is skipped. Watch for the verbose notification rather than typing a password automatically; the module documentation warns that users can begin typing before noticing that no prompt appeared.

After the timeout has elapsed, or after you remove the cache, the same operation should ask for the password again. A session failure may return PAM_SESSION_ERR when the timestamp file cannot be created or updated. Check permissions, the runtime directory, and system logs before changing the PAM stack further.

Clear the cache and recover

Clearing the timestamp is safe and reversible: the next authentication must use the normal stack. Use the helper's -k option:

pam_timestamp_check -k
printf 'exit=%s\n' "$?"

The command normally prints nothing. A zero exit status means the removal operation succeeded. If a service becomes unusable after the edit, use the second administrative session and restore the backup:

sudo cp -p /etc/pam.d/EXAMPLE_SERVICE.before-pam-timestamp /etc/pam.d/EXAMPLE_SERVICE

Do not delete files recursively from /var/run to clear timestamps. The helper knows the timestamp naming rules and can remove the default entry without disturbing unrelated runtime state. If you supplied timestampdir=, use the matching configuration when investigating that cache.

Common traps

• A valid timestamp is not a password. It is a short-lived authentication decision associated with the user and, when relevant, the target user.
• Putting pam_timestamp.so after a required password module does not avoid that password prompt. The sufficient line must be reached before the password module.
• Adding the auth line without the session line can leave no timestamp to validate. Keep both module types in the intended service stack.
• Do not assume every PAM application invokes session management in the same way. Test the actual operation that users perform.
• pam_timestamp_check -d loops indefinitely and prints status. It is not a one-shot validity check.