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