pam_zxcvbn

A PAM module for password strength estimation using zxcvbn-c. It can be plugged in to enforce password entropy, requiring a minimum for the average number of guesses an attacker would need to make to brute-force the password. This module only implements the password stack. It is meant as a replacement for pam_pwquality or pam_cracklib.

The library uses pattern matching and conservative estimation, to recognize and weigh 30,000 common passwords, common names and surnames according to US census data, popular English words from Wikipedia and US television and movies, and other common patterns like dates, repeats (aaa), sequences (abcd), keyboard patterns (qwertyuiop), and l33t speak alternatives for all of the above.

The sequence of actions are as follows:

Prompt the user for a new password (or pull it from use_first_pass or try_first_pass, if set and this is the first time prompting)
Test the password for strength based on defaults or configured limits. On failure, return to step 1.
Prompt the user to verify their password
If the passwords do not match, return to step 1.
Pass the new password on for use in modules stacked below this one in the password stack.

Usage

In the simplest case, this module provides reasonable defaults and requires no arguments:

password	required	pam_zxcvbn.so

A more common usage might look something like this:

password	required	pam_zxcvbn.so try_first_pass tries=3 authtok_type=

Available Options

debug

Enable debugging information to syslog. Does not log passwords, but provides helpful information about what the module is doing. Specifying this option first will allow debugging of following options.

tries=<N>

Prompt user at most N times before returning with error. The default is 1.

retry=<N>

Kept for backward compatibility. An alias for tries.

min_score=<N>

Minimum zxcvbn score for the password:

Too guessable: risky password. (guesses < 10³)
Very guessable: protection from throttled online attacks. (guesses < 10⁶)
Somewhat guessable: protection from unthrottled online attacks. (guesses < 10⁸)
Safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10¹⁰)
Very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10¹⁰)

The default is 3.

NOTE: if both min_score and min_entropy are specified, only min_entropy will be used.

min_entropy=<F.FF>

Minimum entropy for the password for finer grained control, expressed as the log₁₀(guesses).

NOTE: if both min_score and min_entropy are specified, only min_entropy will be used.

enforce_for_root

By default when root is setting a password the min_score and min_entropy failures are treated as warnings. This option turns them back into errors.

local_users_only

Users must be in the local password file to have their passwords tested. Users will still be prompted for their password, so that modules later in the stack can use it with use_authtok option. This option is disabled by default.

local_users_file=<FILE>

The passwd-style file used to search for local users if local_users_only is enabled. Defaults to /etc/passwd.

authtok_type=<TYPE>

The default action is for the module to use the following prompts when requesting passwords:

New UNIX
    password:

and Retype UNIX password: . The example word UNIX can be replaced with this option, by default it is empty.

try_first_pass

Before prompting the user for their password, first try a previous stacked module’s password.

use_first_pass

Force the use of a previous stacked module’s password. If no password is available or the password is not appropriate, the user will be denied access.

use_authtok

When changing a user password, force the module to set the new token to the one provided by a previously stacked password module. If no token is available token changing will fail.

References

Original CoffeeScript library implementation: zxcvbn.

C library port: zxcvbn-c

erikogan/pam_zxcvbn

pam_zxcvbn

Usage

Available Options

References

License