pam_pwhistory

This is a PAM module, configured in PAM service files.
Typical usage in /etc/pam.d/ files under the password stack:

password control pam_pwhistory.so [options]

Where control can be required, requisite, sufficient, or optional, defining the module's success/failure behavior within the PAM stack. options are module-specific arguments.

remember=N
    Specifies the number of previous passwords to remember for each user. An attempt to set a password that matches any of the N remembered passwords will be rejected. The default value is typically 10.

enforce_for_root
    By default, the root user is exempt from password history checks. This option forces pam_pwhistory to apply the history check to the root user as well.

dir=/path/to/dir
    Specifies an alternative directory where the password history file (opasswd) is stored. The default location is /etc/security.

fail_no_update
    If this option is set, the password change will fail if the password history cannot be successfully updated (e.g., due to permissions issues or disk space problems). Without this, the password change might proceed, but the history will not be updated.

debug
    Enables verbose debugging information, which is typically logged to syslog for troubleshooting purposes.

use_authtok
    Instructs the module to use the password provided by the auth stack rather than interactively prompting the user for a new password. Useful for non-interactive password changes.

store_hashes=algorithm
    (Deprecated) Specifies the hashing algorithm (e.g., md5, sha512) to use when storing old passwords. It is recommended to rely on libpwquality for robust password hashing.

The pam_pwhistory module is a Pluggable Authentication Module (PAM) component designed to enhance system security by preventing users from reusing their old passwords. When integrated into the PAM password stack (typically within files like /etc/pam.d/passwd or /etc/pam.d/system-auth), it remembers a user's previous passwords. During a password change operation, pam_pwhistory checks the newly provided password against a stored history of hashes of the user's past passwords. If the new password matches any of the remembered ones, the module prevents the password change, forcing the user to choose a truly new password. This mechanism significantly reduces the risk associated with password recycling, a common weak security practice that makes accounts vulnerable to brute-force attacks or dictionary attacks if an old password is ever compromised.

File Permissions: The password history file (/etc/security/opasswd or the specified dir) must have strict permissions, typically owned by root with 600 or 640 permissions, to prevent unauthorized access to hashed old passwords.

Scalability: For systems with a very large number of local users, the opasswd file can grow significantly, potentially impacting performance or disk space. Centralized identity management systems (like LDAP, FreeIPA) often have their own built-in password history mechanisms that may be more scalable.

Root Exemption: Remember to use the enforce_for_root option if you wish to apply password history policies to the root user, as they are exempt by default.

When pam_pwhistory is invoked as part of the password change process, it takes the user's new password and hashes it. It then compares this hash against a list of hashes of the user's previously used passwords, which are typically stored in the /etc/security/opasswd file (or a specified alternative directory). If a match is found, the password change is rejected. If the change is allowed, the hash of the new password is added to the user's history list, and the oldest hash is removed to maintain the specified 'remember' count. Only password hashes are stored, not the plain-text passwords.

To enable pam_pwhistory and remember 5 previous passwords for all users (including root), you might add or modify a line in your /etc/pam.d/passwd or /etc/pam.d/system-auth file (depending on your distribution's PAM setup) under the password stack:

password required pam_pwhistory.so remember=5 enforce_for_root

The required control flag means that this module must succeed for the overall password change operation to succeed, and its failure will cause the entire password change to fail.

PAM (Pluggable Authentication Modules) was originally developed by Sun Microsystems in the mid-1990s to provide a flexible authentication framework. The Linux-PAM project brought this architecture to Linux systems. The pam_pwhistory module emerged as a crucial component to enforce a fundamental security policy: preventing users from reusing old passwords. This addresses a common vulnerability where users might cycle between a small set of passwords, making them easier to guess or crack if an old password is compromised. Its development reflects the ongoing effort to improve password security practices on Unix-like systems, emphasizing policy enforcement at the authentication layer.

pam(8), pam.conf(5), passwd(1), pam_unix(8), libpwquality(3)