diff options
Diffstat (limited to 'contrib/pam_modules/pam_passwdqc/README')
| -rw-r--r-- | contrib/pam_modules/pam_passwdqc/README | 150 |
1 files changed, 99 insertions, 51 deletions
diff --git a/contrib/pam_modules/pam_passwdqc/README b/contrib/pam_modules/pam_passwdqc/README index ca2af89955da..0561070e30e4 100644 --- a/contrib/pam_modules/pam_passwdqc/README +++ b/contrib/pam_modules/pam_passwdqc/README @@ -1,8 +1,8 @@ pam_passwdqc is a simple password strength checking module for PAM-aware password changing programs, such as passwd(1). In addition to checking regular passwords, it offers support for passphrases and -can provide randomly generated passwords. All features are optional -and can be (re-)configured without rebuilding. +can provide randomly generated ones. All features are optional and +can be (re-)configured without rebuilding. This module should be stacked before your usual password changing module (such as pam_unix or pam_pwdb) in the password management group @@ -15,27 +15,35 @@ are inconsistent with pam_passwdqc's, you may tell pam_passwdqc to ask for the old password as well, with "ask_oldauthtok". In that case the option to use with the password changing module is "use_first_pass". -There's a number of supported options which can be used to modify the +There are a number of supported options, which can be used to modify the behavior of pam_passwdqc (defaults are given in square brackets): - min=N0,N1,N2,N3,N4 [min=disabled,24,12,8,7] + config=FILE [] -The minimum allowed password lengths, separately for different kinds -of passwords/passphrases. The special word "disabled" can be used to -disallow passwords of a given kind regardless of their length. Each -subsequent number is required to be no larger than the preceding one. +Load the specified configuration FILE, which must be in the +passwdqc.conf format (described in the passwdqc.conf(5) manual page). +This file may define any options described in here, including load of +yet another configuration file, but loops are not allowed. + + min=N0,N1,N2,N3,N4 [min=disabled,24,11,8,7] + +The minimum allowed password lengths for different kinds of passwords +and passphrases. The keyword "disabled" can be used to disallow +passwords of a given kind regardless of their length. Each subsequent +number is required to be no larger than the preceding one. N0 is used for passwords consisting of characters from one character -class only. (The character classes are: digits, lower-case letters, -upper-case letters, and other characters. There's also the special -class for non-ASCII characters which couldn't be classified, but are -assumed to be non-digits.) +class only. The character classes are: digits, lower-case letters, +upper-case letters, and other characters. There is also a special +class for non-ASCII characters, which could not be classified, but are +assumed to be non-digits. N1 is used for passwords consisting of characters from two character -classes, which don't meet the requirements for a passphrase. +classes that do not meet the requirements for a passphrase. -N2 is used for passphrases. A passphrase must consist of sufficient -words (see the "passphrase" option, below). +N2 is used for passphrases. Note that besides meeting this length +requirement, a passphrase must also consist of a sufficient number of +words (see the "passphrase" option below). N3 and N4 are used for passwords consisting of characters from three and four character classes, respectively. @@ -46,35 +54,36 @@ password are not counted. In addition to being sufficiently long, passwords are required to contain enough different characters for the character classes and -the minimum length they've been checked against. +the minimum length they have been checked against. - max=N [max=40] + max=N [max=72] The maximum allowed password length. This can be used to prevent -users from setting passwords which may be too long for some system +users from setting passwords that may be too long for some system services. -The value 8 is treated specially. Passwords longer than 8 characters -will not be rejected, but will be truncated to 8 characters for the -strength checks and the user will be warned. This is to be used with -the traditional crypt(3) password hashes. +The value 8 is treated specially: with max=8, passwords longer than 8 +characters will not be rejected, but will be truncated to 8 characters +for the strength checks and the user will be warned. This is to be +used with the traditional DES-based password hashes, which truncate +the password at 8 characters. -It is important that you do set max=8 if you're using the traditional +It is important that you do set max=8 if you are using the traditional hashes, or some weak passwords will pass the checks. passphrase=N [passphrase=3] The number of words required for a passphrase, or 0 to disable the -support for passphrases. +support for user-chosen passphrases. match=N [match=4] The length of common substring required to conclude that a password is at least partially based on information found in a character string, or 0 to disable the substring search. Note that the password will not -be rejected once a weak substring is found. Instead, the password -will be subjected to the usual strength requirements with the weak -substring removed. +be rejected once a weak substring is found; it will instead be +subjected to the usual strength requirements with the weak substring +partially discounted. The substring search is case-insensitive and is able to detect and remove a common substring spelled backwards. @@ -82,29 +91,65 @@ remove a common substring spelled backwards. similar=permit|deny [similar=deny] Whether a new password is allowed to be similar to the old one. The -passwords are considered to be similar when there's a sufficiently -long common substring and the new password with the substring removed -would be weak. - - random=N[,only] [random=42] - -The size of randomly-generated passwords in bits, or 0 to disable this -feature. Passwords that contain the offered randomly-generated string -will be allowed regardless of other possible restrictions. +passwords are considered to be similar when there is a sufficiently +long common substring and the new password with the substring partially +discounted would be weak. + + wordlist=FILE [] + +Deny passwords that are based on lines of a tiny external text file, +which can reasonably be e.g. a list of a few thousand common passwords. +Common dictionary words may also reasonably be included, especially in a +local language other than English, or longer yet common English words. +(passwdqc includes a list of a few thousand common English words of +lengths from 3 to 6 built in. Any word list possibly specified with +this option is used in addition to the built-in word list.) + +Substring matching and discounting will be used if the "match" setting +above is non-zero. Please note that this is very inefficient, and isn't +to be used with large wordlists. + + denylist=FILE [] + +Deny passwords or passphrases directly appearing in a tiny external text +file. That file can reasonably be e.g. a list of common passwords if +only a relaxed policy is desired and stricter checks are thus disabled +(using their separate options). Such policy would only be somewhat +effective against online/remote attacks, but not against offline attacks +on hashed passwords. + + filter=FILE [] + +Deny passwords or passphrases directly appearing in a maybe huge binary +filter file created with pwqfilter. This is very efficient, needing at +most two random disk reads per query. A filter created from millions of +leaked passwords can reasonably be used on top of passwdqc's other +checks to further reduce the number of passing yet weak passwords +without causing unreasonable inconvenience (as e.g. higher minimum +lengths and character set requirements could). + + random=N[,only] [random=47] + +The size of randomly-generated passphrases in bits (24 to 136), or 0 to +disable this feature. Any passphrase that contains the offered +randomly-generated string will be allowed regardless of other possible +restrictions. The "only" modifier can be used to disallow user-chosen passwords. enforce=none|users|everyone [enforce=everyone] The module can be configured to warn of weak passwords only, but not -actually enforce strong passwords. The "users" setting will enforce -strong passwords for non-root users only. +actually enforce strong passwords. The "users" setting is like +"everyone" for all PAM services except "chpasswd" and "passwd". +For these two PAM services "users" will enforce strong passwords +for invocations by non-root users only. non-unix [] -By default, the module uses getpwnam(3) to obtain the user's personal +Normally, the module uses getpwnam(3) to obtain the user's personal login information and use that during the password strength checks. -This behavior can be disabled with "non-unix". +This behavior can be disabled with the "non-unix" option. retry=N [retry=3] @@ -115,20 +160,20 @@ first time. ask_oldauthtok[=update] [] Ask for the old password as well. Normally, pam_passwdqc leaves this -task for the password changing module. A simple "ask_oldauthtok" will -cause pam_passwdqc to ask for the old password during the preliminary -check phase. With "ask_oldauthtok=update", pam_passwdqc will do that -during the update phase. +task for subsequent modules. With no argument, the "ask_oldauthtok" +option will cause pam_passwdqc to ask for the old password during the +preliminary check phase. With "ask_oldauthtok=update", pam_passwdqc +will do that during the update phase. check_oldauthtok [] This tells pam_passwdqc to validate the old password before giving a -new password prompt. Normally, this task is left for the password -changing module. +new password prompt. Normally, this task is left for subsequent +modules. -The primary use for this option is with "ask_oldauthtok=update" in -which case no other modules have a chance to run and validate the -password between the prompts. Of course, this will only work with +The primary use for this option is when "ask_oldauthtok=update" is +also specified, in which case no other module gets a chance to ask +for and validate the password. Of course, this will only work with Unix passwords. use_first_pass [] @@ -139,5 +184,8 @@ This disables user interaction within pam_passwdqc. With this module, the only difference between "use_first_pass" and "use_authtok" is that the former is incompatible with "ask_oldauthtok". --- -Solar Designer <solar@openwall.com> + noaudit [] + +If audit is enabled at build time, the PAM module logs audit events once +user tries to change their credentials. This option disables that audit +logging. |