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