1 .\" Copyright (c) 2000-2002 Solar Designer.
2 .\" All rights reserved.
3 .\" Copyright (c) 2001 Networks Associates Technology, Inc.
4 .\" All rights reserved.
6 .\" Portions of this software were developed for the FreeBSD Project by
7 .\" ThinkSec AS and NAI Labs, the Security Research Division of Network
8 .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
9 .\" ("CBOSS"), as part of the DARPA CHATS research program.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
19 .\" 3. The name of the author may not be used to endorse or promote
20 .\" products derived from this software without specific prior written
23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
40 .Nd Password quality-control PAM module
50 module is a simple password strength checking module for
52 In addition to checking regular passwords, it offers support for
53 passphrases and can provide randomly generated passwords.
57 module provides functionality for only one PAM category:
61 parameter, this is the
67 service function will ask the user for a new password, and verify that
68 it meets certain minimum standards.
69 If the chosen password is unsatisfactory, the service function returns
72 The following options may be passed to the authentication module:
73 .Bl -tag -width indent
76 .Cm min No = Ar N0 , N1 , N2 , N3 , N4
80 .Pq Cm min No = Cm disabled , No 24 , 12 , 8 , 7
82 The minimum allowed password lengths for different kinds of
83 passwords/passphrases.
87 disallow passwords of a given kind regardless of their length.
88 Each subsequent number is required to be no larger than the preceding
92 is used for passwords consisting of characters from one character
94 The character classes are: digits, lower-case letters, upper-case
95 letters, and other characters.
96 There is also a special class for
98 characters which could not
99 be classified, but are assumed to be non-digits.
102 is used for passwords consisting of characters from two character
103 classes, which do not meet the requirements for a passphrase.
106 is used for passphrases.
107 A passphrase must consist of sufficient words (see the
114 are used for passwords consisting of characters from three
115 and four character classes, respectively.
117 When calculating the number of character classes, upper-case letters
118 used as the first character and digits used as the last character of a
119 password are not counted.
121 In addition to being sufficiently long, passwords are required to
122 contain enough different characters for the character classes and
123 the minimum length they have been checked against.
124 .It Cm max Ns = Ns Ar N
125 .Pq Cm max Ns = Ns 40
126 The maximum allowed password length.
127 This can be used to prevent users from setting passwords which may be
128 too long for some system services.
129 The value 8 is treated specially: if
131 is set to 8, passwords longer than 8 characters will not be rejected,
132 but will be truncated to 8 characters for the strength checks and the
134 This is for compatibility with the traditional DES password hashes,
135 which truncate the password at 8 characters.
137 It is important that you do set
139 if you are using the traditional
140 hashes, or some weak passwords will pass the checks.
141 .It Cm passphrase Ns = Ns Ar N
142 .Pq Cm passphrase Ns = Ns 3
143 The number of words required for a passphrase, or 0 to disable
145 .It Cm match Ns = Ns Ar N
146 .Pq Cm match Ns = Ns 4
147 The length of common substring required to conclude that a password is
148 at least partially based on information found in a character string,
149 or 0 to disable the substring search.
150 Note that the password will not be rejected once a weak substring is
151 found; it will instead be subjected to the usual strength requirements
152 with the weak substring removed.
154 The substring search is case-insensitive and is able to detect and
155 remove a common substring spelled backwards.
158 .Cm similar No = Cm permit | deny
161 .Pq Cm similar Ns = Ns Cm deny
162 Whether a new password is allowed to be similar to the old one.
163 The passwords are considered to be similar when there is a sufficiently
164 long common substring and the new password with the substring removed
168 .Cm random No = Ar N Op , Cm only
171 .Pq Cm random Ns = Ns 42
172 The size of randomly-generated passwords in bits, or 0 to disable this
174 Passwords that contain the offered randomly-generated string will be
175 allowed regardless of other possible restrictions.
179 modifier can be used to disallow user-chosen passwords.
182 .Cm enforce No = Cm none | users | everyone
185 .Pq Cm enforce Ns = Ns Cm everyone
186 The module can be configured to warn of weak passwords only, but not
187 actually enforce strong passwords.
190 setting will enforce strong passwords for non-root users only.
196 to obtain the user's personal login information and use that during
197 the password strength checks.
198 This behavior can be disabled with the
201 .It Cm retry Ns = Ns Ar N
202 .Pq Cm retry Ns = Ns 3
203 The number of times the module will ask for a new password if the user
204 fails to provide a sufficiently strong password and enter it twice the
206 .It Cm ask_oldauthtok Ns Op = Ns Cm update
207 Ask for the old password as well.
210 leaves this task for subsequent modules.
211 With no argument, the
215 to ask for the old password during the preliminary check phase.
218 option is specified with the
222 will do that during the update phase.
223 .It Cm check_oldauthtok
226 to validate the old password before giving a
228 Normally, this task is left for subsequent modules.
230 The primary use for this option is when
231 .Cm ask_oldauthtok Ns = Ns Cm update
232 is also specified, in which case no other modules gets a chance to ask
233 for and validate the password.
234 Of course, this will only work with
237 .It Cm use_first_pass , use_authtok
238 Use the new password obtained by modules stacked before
240 This disables user interaction within
242 The only difference between
246 is that the former is incompatible with
256 module was written by
257 .An Solar Designer Aq Mt solar@openwall.com .
258 This manual page, derived from the author's documentation, was written
262 ThinkSec AS and NAI Labs, the Security Research Division of Network
263 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
265 as part of the DARPA CHATS research program.