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