unix_chkpwd Is Not a Password Checker

Typing unix_chkpwd straight into a shell to test a password gets logged as a security violation, not a login. This guide shows how to identify and verify the installed helper, understand what it actually does during PAM authentication, and investigate a related failure without ever typing a password into the shell. Do not invoke this helper as a command-line password checker.

• Time: about ten minutes.
• You need: a shell and, for package or file checks, an account that can read the relevant system metadata.
• Package used here: libpam-modules-bin 1.5.3-5ubuntu5.7. Exact packaging and diagnostic messages may differ on another Linux distribution.

Every command below is read-only. None of them changes a password, edits PAM configuration, restarts a service or alters the shadow database.

1. Confirm that the helper belongs to PAM

Start by locating the executable without running it:

$ command -v unix_chkpwd
/usr/sbin/unix_chkpwd

That pathname is 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.

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 differ. Record it anyway: distributions can backport patches without bumping the upstream version in the way you might expect. If the first command says 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

On this machine the file is owned by root, has group shadow, and mode 2755. The setgid bit shows up as the s in both the group letters and 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 never loosen them just to make an authentication error disappear. A privileged password helper is security-sensitive by design.

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.

If you need to test a login service, use that service's ordinary authentication path with a test account and its documented, approved procedure. Keep the test account separate from any real user's account, and never 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 an application such as a screen locker authenticate without being setuid root itself.

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, which is why a real diagnosis focuses on the PAM service configuration and logs, not on constructing input for the helper.

There is also a less obvious limit worth knowing: 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 simply ignored by the module. That is a versioned implementation boundary, not a suggestion to go test it with 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 with 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 dpkg found no differences in the checks it is able to perform. If it reports a difference, record the exact path and package version. Never replace a security-sensitive binary with a download from an untrusted location; reinstall or repair it through the signed repositories and process your host normally uses.

If only one PAM service fails, compare its configuration with a known-good host or the distribution's package defaults. If several fail at once, check the package installation, shadow database permissions and any 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, and 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: a malformed PAM file can lock administrators out.