| blob | 82476528255272c05c29b9151b0b38cdf781dd87 |
1 .\" Copyright (c) 2000-2003,2005,2008 Solar Designer.
2 .\" All rights reserved.
3 .\" Copyright (c) 2001 Networks Associates Technology, Inc.
4 .\" All rights reserved.
5 .\"
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.
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
13 .\" are met:
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
21 .\" permission.
22 .\"
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
33 .\" SUCH DAMAGE.
34 .\"
35 .\" $FreeBSD: src/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8,v 1.4 2002/05/30 14:49:57 ru Exp $
36 .\" $Owl: Owl/packages/pam_passwdqc/pam_passwdqc/pam_passwdqc.8,v 1.11 2008/02/12 20:33:09 solar Exp $
37 .\"
38 .Dd February 12, 2008
39 .Dt PAM_PASSWDQC 8
40 .Os
41 .Sh NAME
42 .Nm pam_passwdqc
43 .Nd Password quality-control PAM module
44 .Sh SYNOPSIS
45 .Op Ar service-name
46 .Ar module-type
47 .Ar control-flag
48 .Pa pam_passwdqc
49 .Op Ar options
50 .Sh DESCRIPTION
51 The
52 .Nm
53 module is a simple password strength checking module for
54 PAM.
55 In addition to checking regular passwords, it offers support for
56 passphrases and can provide randomly generated ones.
57 .Pp
58 The
59 .Nm
60 module provides functionality for only one PAM management group:
61 password changing.
62 In terms of the
63 .Ar module-type
64 parameter, this is the
65 .Dq Li password
66 feature.
67 .Pp
68 The
69 .Fn pam_chauthtok
70 service function may ask the user for a new password, and verify that
71 it meets certain minimum standards.
72 If the chosen password is unsatisfactory, the service function returns
73 .Dv PAM_AUTHTOK_ERR .
74 .Pp
75 The following options may be passed to the module:
76 .Bl -tag -width indent
77 .It Xo
78 .Sm off
79 .Cm min No = Ar N0 , N1 , N2 , N3 , N4
80 .Sm on
81 .Xc
82 .Sm off
83 .Pq Cm min No = Cm disabled , No 24 , 11 , 8 , 7
84 .Sm on
85 The minimum allowed password lengths for different kinds of
86 passwords/passphrases.
87 The keyword
88 .Cm disabled
89 can be used to
90 disallow passwords of a given kind regardless of their length.
91 Each subsequent number is required to be no larger than the preceding
92 one.
93 .Pp
94 .Ar N0
95 is used for passwords consisting of characters from one character
96 class only.
97 The character classes are: digits, lower-case letters, upper-case
98 letters, and other characters.
99 There is also a special class for
100 .No non- Ns Tn ASCII
101 characters, which could not be classified, but are assumed to be non-digits.
102 .Pp
103 .Ar N1
104 is used for passwords consisting of characters from two character
105 classes that do not meet the requirements for a passphrase.
106 .Pp
107 .Ar N2
108 is used for passphrases.
109 Note that besides meeting this length requirement,
110 a passphrase must also consist of a sufficient number of words (see the
111 .Cm passphrase
112 option below).
113 .Pp
114 .Ar N3
115 and
116 .Ar N4
117 are used for passwords consisting of characters from three
118 and four character classes, respectively.
119 .Pp
120 When calculating the number of character classes, upper-case letters
121 used as the first character and digits used as the last character of a
122 password are not counted.
123 .Pp
124 In addition to being sufficiently long, passwords are required to
125 contain enough different characters for the character classes and
126 the minimum length they have been checked against.
127 .Pp
128 .It Cm max Ns = Ns Ar N
129 .Pq Cm max Ns = Ns 40
130 The maximum allowed password length.
131 This can be used to prevent users from setting passwords that may be
132 too long for some system services.
133 The value 8 is treated specially: if
134 .Cm max
135 is set to 8, passwords longer than 8 characters will not be rejected,
136 but will be truncated to 8 characters for the strength checks and the
137 user will be warned.
138 This is to be used with the traditional DES-based password hashes,
139 which truncate the password at 8 characters.
140 .Pp
141 It is important that you do set
142 .Cm max Ns = Ns 8
143 if you are using the traditional
144 hashes, or some weak passwords will pass the checks.
145 .It Cm passphrase Ns = Ns Ar N
146 .Pq Cm passphrase Ns = Ns 3
147 The number of words required for a passphrase, or 0 to disable the
148 support for user-chosen passphrases.
149 .It Cm match Ns = Ns Ar N
150 .Pq Cm match Ns = Ns 4
151 The length of common substring required to conclude that a password is
152 at least partially based on information found in a character string,
153 or 0 to disable the substring search.
154 Note that the password will not be rejected once a weak substring is
155 found; it will instead be subjected to the usual strength requirements
156 with the weak substring removed.
157 .Pp
158 The substring search is case-insensitive and is able to detect and
159 remove a common substring spelled backwards.
160 .It Xo
161 .Sm off
162 .Cm similar No = Cm permit | deny
163 .Sm on
164 .Xc
165 .Pq Cm similar Ns = Ns Cm deny
166 Whether a new password is allowed to be similar to the old one.
167 The passwords are considered to be similar when there is a sufficiently
168 long common substring and the new password with the substring removed
169 would be weak.
170 .It Xo
171 .Sm off
172 .Cm random No = Ar N Op , Cm only
173 .Sm on
174 .Xc
175 .Pq Cm random Ns = Ns 42
176 The size of randomly-generated passphrases in bits (24 to 72),
177 or 0 to disable this feature.
178 Any passphrase that contains the offered randomly-generated string will be
179 allowed regardless of other possible restrictions.
180 .Pp
181 The
182 .Cm only
183 modifier can be used to disallow user-chosen passwords.
184 .It Xo
185 .Sm off
186 .Cm enforce No = Cm none | users | everyone
187 .Sm on
188 .Xc
189 .Pq Cm enforce Ns = Ns Cm everyone
190 The module can be configured to warn of weak passwords only, but not
191 actually enforce strong passwords.
192 The
193 .Cm users
194 setting will enforce strong passwords for invocations by non-root users only.
195 .It Cm non-unix
196 Normally,
197 .Nm
198 uses
199 .Xr getpwnam 3
200 to obtain the user's personal login information and use that during
201 the password strength checks.
202 This behavior can be disabled with the
203 .Cm non-unix
204 option.
205 .It Cm retry Ns = Ns Ar N
206 .Pq Cm retry Ns = Ns 3
207 The number of times the module will ask for a new password if the user
208 fails to provide a sufficiently strong password and enter it twice the
209 first time.
210 .It Cm ask_oldauthtok Ns Op = Ns Cm update
211 Ask for the old password as well.
212 Normally,
213 .Nm
214 leaves this task for subsequent modules.
215 With no argument, the
216 .Cm ask_oldauthtok
217 option will cause
218 .Nm
219 to ask for the old password during the preliminary check phase.
220 If the
221 .Cm ask_oldauthtok
222 option is specified with the
223 .Cm update
224 argument,
225 .Nm
226 will do that during the update phase.
227 .It Cm check_oldauthtok
228 This tells
229 .Nm
230 to validate the old password before giving a
231 new password prompt.
232 Normally, this task is left for subsequent modules.
233 .Pp
234 The primary use for this option is when
235 .Cm ask_oldauthtok Ns = Ns Cm update
236 is also specified, in which case no other module gets a chance to ask
237 for and validate the password.
238 Of course, this will only work with
239 .Ux
240 passwords.
241 .It Cm use_first_pass , use_authtok
242 Use the new password obtained by modules stacked before
243 .Nm .
244 This disables user interaction within
245 .Nm .
246 The only difference between
247 .Cm use_first_pass
248 and
249 .Cm use_authtok
250 is that the former is incompatible with
251 .Cm ask_oldauthtok .
252 .El
253 .Sh SEE ALSO
254 .Xr getpwnam 3 ,
255 .Xr pam.conf 5 ,
256 .Xr pam 8
257 .Sh AUTHORS
258 The
259 .Nm
260 module was written for Openwall GNU/*/Linux by
261 .An Solar Designer Aq solar at openwall.com .
262 This manual page, derived from the author's documentation, was written
263 for the
264 .Fx
265 Project by
266 ThinkSec AS and NAI Labs, the Security Research Division of Network
267 Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
268 .Pq Dq CBOSS ,
269 as part of the DARPA CHATS research program.