Enforcing Linux Password Policy with pam_pwquality and pwquality.conf

pam_pwquality is the Pluggable Authentication Modules (PAM) module that checks the strength of new passwords whenever a user runs passwd or an administrator resets an account. Its global defaults live in /etc/security/pwquality.conf, where directives such as minlen = 14 set a minimum length and negative “credit” values such as dcredit = -1 require specific character classes. Because the module sits in a PAM stack, the control flag on its line (requisite, required, and so on) decides what happens when a candidate password fails the checks.

What pam_pwquality actually does

PAM splits authentication work into four management groups: auth, account, session, and password. The password group handles credential changes, and that is where pam_pwquality plugs in. When a user submits a new password, the module runs it through a series of quality tests — length, character-class mix, dictionary words, similarity to the old password, repeated characters — before the password ever reaches pam_unix.so, the module that actually writes the hash to /etc/shadow.

On Red Hat–family systems the stack lives in /etc/pam.d/system-auth (and password-auth); on Debian and Ubuntu it lives in /etc/pam.d/common-password. A typical line looks like this:

password    requisite    pam_pwquality.so retry=3

The retry=3 argument is a module option, not a config-file directive: it gives the user three attempts to supply an acceptable password within a single passwd run before the module returns failure.

pam_pwquality replaced the older pam_cracklib module on modern distributions and inherits most of its option names, which is why documentation for the two overlaps so heavily.

Where the settings live

The module reads its global defaults from /etc/security/pwquality.conf on virtually every modern distribution. Options can also be supplied inline on the PAM stack line (like retry=3 above), and inline options override the file. Many distributions additionally support drop-in files under /etc/security/pwquality.conf.d/, which is the cleaner way to layer site policy on top of vendor defaults.

The file format is plain key = value, one directive per line, with # comments. A policy requiring 14-character minimum length is exactly:

minlen = 14

The same pattern applies for any length floor — a 12-character policy is minlen = 12 in /etc/security/pwquality.conf. No service restart is needed; the file is read each time a password change runs.

The core directives

• minlen — minimum acceptable password size, after credits are applied (more on credits below). The compiled-in floor is 6; you cannot set it lower.
• minclass — minimum number of character classes (lowercase, uppercase, digits, other) that must appear. minclass = 3 demands any three of the four.
• difok — how many characters in the new password must differ from the old one.
• maxrepeat — maximum allowed run of identical consecutive characters (maxrepeat = 3 rejects aaaa).
• dictcheck — when set to 1 (the default), rejects passwords found by a dictionary check against the cracklib dictionaries.
• usercheck — rejects passwords containing the username in some form.
• enforce_for_root — by default root is warned about a weak password but not blocked; this directive makes the checks binding for root too.

Credit values: positive vs negative

The four credit directives — dcredit (digits), ucredit (uppercase), lcredit (lowercase), ocredit (other/special) — are the part of pwquality.conf that trips people up, because the sign of the value flips the meaning entirely.

Setting	Positive value (e.g. dcredit = 1)	Negative value (e.g. dcredit = -1)
Meaning	Optional bonus: each digit adds up to N credits toward minlen	Hard requirement: password must contain at least N digits
Effect on length	A digit-containing password can be shorter than minlen characters typed	No effect on effective length; classes are simply mandatory
Enforcement	Nothing is required — credits only make compliance easier	Change is rejected outright if the class count isn’t met
Typical use	Legacy/looser policies	Compliance baselines (CIS, STIG-style hardening)

So dcredit = -1 means “at least one digit, no credit given.” Combine ucredit = -1 with lcredit = -1 and every compliant password must contain at least one uppercase letter and at least one lowercase letter. Because negative values grant no credits, they pair naturally with a strict minlen: the length floor stays exactly what you set.

If you leave credits at positive values, remember that minlen is measured in credits, not raw characters — a password with a digit, an uppercase letter, and a symbol could satisfy minlen = 14 while being only 11 characters long. Auditors usually want credits set to 0 or negative for that reason.

How the PAM stack changes what “failure” means

The control flag on the pam_pwquality line is as important as the directives:

• requisite — on failure, PAM returns failure to the application immediately and skips every remaining module in the stack.
• required — failure is recorded, but the rest of the stack still runs before the failure is reported.
• sufficient — success here ends the stack successfully (if no earlier required module failed).

Consider this common Red Hat–style stack:

password    requisite    pam_pwquality.so retry=3
password    sufficient   pam_unix.so use_authtok sha512 shadow

If a user’s new password fails the quality checks on all three retries, the requisite flag aborts the stack on the spot. pam_unix.so never executes, nothing is written to /etc/shadow, and the account keeps its old password. The use_authtok argument on pam_unix tells it to accept the token already validated by pam_pwquality rather than prompting again — which is exactly why pwquality must run first and why its failure must stop the stack.

For the wider exam picture of where PAM fits among Linux security controls — alongside topics like persistent journald logging and secure data destruction — the XK0-006 study guide maps the full Security domain. Which-file-do-you-edit questions reward repetition — drill them in the practice bank before exam day.

How the XK0-006 exam tests this

• Write-the-directive scenarios: a policy states a minimum length (12, 14) and asks which file and line enforce it — the answer pattern is minlen = N in /etc/security/pwquality.conf, not a pam.d edit.
• Credit-sign interpretation: you’re shown dcredit = -1 or a ucredit/lcredit pair and asked what a compliant password must contain. Negative means required class, positive means length credit.
• Stack-behavior questions: a requisite pam_pwquality.so line followed by sufficient pam_unix.so use_authtok, with a user failing all retries — the exam wants you to know the change aborts and the old password survives.
• “Where are the defaults?” questions that distinguish /etc/security/pwquality.conf from /etc/pam.d/*, /etc/login.defs (aging, not complexity), and /etc/shadow (storage, not policy).

Quick reference

• Global defaults: /etc/security/pwquality.conf; inline options on the PAM line override the file.
• minlen = 14 → minimum 14 characters (measured in credits if positive credits are in play).
• Negative credit (dcredit = -1) → at least one of that class required; positive credit → optional length bonus.
• ucredit = -1 + lcredit = -1 → password must include both an uppercase and a lowercase letter.
• retry=N is a module argument in /etc/pam.d/, giving N attempts per passwd run.
• requisite failure aborts the stack immediately — pam_unix.so never runs, old password stays.
• Root bypasses enforcement unless enforce_for_root is set.
• Password aging (expiry, warning days) is chage//etc/login.defs territory — pwquality only judges complexity.