unix_chkpwd: Why This PAM Helper Should Not Be Run Directly

You will finish with a safe way to identify and verify the installed unix_chkpwd helper, understand what it does during PAM authentication, and investigate a related failure without typing a password into the shell. The central rule is simple: do not invoke this helper as a command-line password checker. The installed manual page says that doing so is not its intended use and logs a security violation.

Allow about ten minutes. You need a shell and, for package or file checks, an account that can read the relevant system metadata. The examples below are read-only. They do not change a password, edit PAM configuration, restart a service or alter the shadow database. The installed package here is libpam-modules-bin 1.5.3-5ubuntu5.7, so the exact packaging and diagnostic messages may differ on another Linux distribution.

1. Confirm that the helper belongs to PAM

Start by locating the executable without running it:

$ command -v unix_chkpwd
/usr/sbin/unix_chkpwd

The pathname is useful evidence, not an instruction to execute the file. The unix_chkpwd(8) manual describes it as a helper for the pam_unix module. It verifies the password of the current user and checks password and account expiry information in the shadow database. Its command-line interface and input/output format are internal to pam_unix.

Checkpoint: if command -v prints nothing, do not create a replacement in /usr/sbin. Check which package should provide the helper on your distribution, then repair that package through your normal package-management process.

2. Check the installed package and file metadata

On Debian and Ubuntu systems, ask dpkg which package owns the file and which version is installed:

$ dpkg-query -S /usr/sbin/unix_chkpwd
libpam-modules-bin: /usr/sbin/unix_chkpwd
$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules-bin
libpam-modules-bin 1.5.3-5ubuntu5.7

Your version will normally be different. Treat the version as part of the diagnosis because distributions can backport patches without changing the upstream version in the way you expect. If the first command says that no package owns the file, stop and investigate the installation rather than trusting an untracked setuid helper.

Inspect ownership and permission bits as another read-only check:

$ stat -c '%A %a %U %G %n' /usr/sbin/unix_chkpwd
-rwxr-sr-x 2755 root shadow /usr/sbin/unix_chkpwd

The installed file on this machine is owned by root, has group shadow, and has mode 2755. The setgid bit is visible as the s in the group portion and in the numeric mode. The manual says the helper is typically installed setuid root or setgid shadow. Do not copy these bits to another file and do not loosen them to make an authentication error disappear. A privileged password helper is security-sensitive.

3. Do not test it with a password

There is no documented option in unix_chkpwd(8) for a username, password, service or test mode. The synopsis is only unix_chkpwd [...], and the manual deliberately leaves the arguments and data format as an internal interface. That is a boundary, not an invitation to reverse-engineer an invocation.

Do not run unix_chkpwd directly, pipe a password to it, or put a password in a command line. Direct execution is outside the supported interface and is recorded as a security violation. Command-line arguments can also appear in process listings or shell history. A failed experiment may create an authentication alert without telling you whether the real PAM stack works.

If you need to test a login service, use that service's ordinary authentication path with a test account and follow its documented, approved procedure. Keep the test account separate from a real user's account. Do not paste a real password into a shell, a ticket, a log or this guide.

4. Understand the normal call path

During authentication, an application calls PAM. The configured pam_unix module may then invoke unix_chkpwd on behalf of the current user when the password is stored in a read-protected database. This arrangement lets applications such as a screen locker authenticate without being setuid root themselves.

The helper checks only the password of the user invoking it. It is not an administrator's tool for checking another account, and it is not a general API for applications. The surrounding PAM conversation supplies the secret through the module's internal mechanism. That is why a successful diagnosis focuses on the PAM service configuration and logs, not on constructing input for the helper.

There is also a less obvious limit: the local pam_unix(8) manual documents a maximum password length of PAM_MAX_RESP_SIZE, currently 512 bytes, when the helper is used. Text beyond that limit is ignored by the module. This is a versioned implementation boundary, not a recommendation to test by entering an unusually long password.

5. Investigate an authentication failure safely

First identify the PAM service that failed, such as an SSH login, console login or display manager. Then inspect that service's PAM configuration and system authentication logs using your distribution's normal tools. Look for a broken module path, a missing pam_unix entry, shadow-file access errors, account expiry or a deliberately restrictive policy.

For package integrity, verify the files supplied by the package without modifying anything:

$ dpkg -V libpam-modules-bin

No output means that dpkg found no differences in the package's checks it can perform. If it reports a difference, record the exact path and package version. Do not replace a security-sensitive binary with a download from an untrusted location. Reinstall or repair it through the signed repositories and operational process used by the host.

If only one PAM service fails, compare its configuration with a known-good host or the distribution's package defaults. If several services fail, check the package installation, the shadow database permissions and recent system changes. Authentication logs can contain account names and policy details, so treat them as sensitive operational data.

6. Know what can and cannot be fixed here

unix_chkpwd does not enable accounts, reset passwords, change expiry dates or repair a PAM stack. It has no documented configuration file of its own. Password changes belong in a supported account-management command or service, and PAM policy belongs in the relevant files under /etc/pam.d. Make those changes only through your normal change-control process, because a malformed PAM file can lock administrators out.

If you have already run the helper directly, stop repeating the test. Check the host's authentication or security logs for the recorded violation, note the time and command context, and tell the system owner if the event matters to your monitoring policy. There is no useful undo command for a log entry. The safest recovery is to restore testing through the real PAM service and leave the helper untouched.