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.It Cm max Ns = Ns Ar N 127.Pq Cm max Ns = Ns 40 128The maximum allowed password length. 129This can be used to prevent users from setting passwords which may be 130too long for some system services. 131The value 8 is treated specially: if 132.Cm max 133is set to 8, passwords longer than 8 characters will not be rejected, 134but will be truncated to 8 characters for the strength checks and the 135user will be warned. 136This is for compatibility with the traditional DES password hashes, 137which truncate the password at 8 characters. 138.Pp 139It is important that you do set 140.Cm max Ns = Ns 8 141if you are using the traditional 142hashes, or some weak passwords will pass the checks. 143.It Cm passphrase Ns = Ns Ar N 144.Pq Cm passphrase Ns = Ns 3 145The number of words required for a passphrase, or 0 to disable 146passphrase support. 147.It Cm match Ns = Ns Ar N 148.Pq Cm match Ns = Ns 4 149The length of common substring required to conclude that a password is 150at least partially based on information found in a character string, 151or 0 to disable the substring search. 152Note that the password will not be rejected once a weak substring is 153found; it will instead be subjected to the usual strength requirements 154with the weak substring removed. 155.Pp 156The substring search is case-insensitive and is able to detect and 157remove a common substring spelled backwards. 158.It Xo 159.Sm off 160.Cm similar No = Cm permit | deny 161.Sm on 162.Xc 163.Pq Cm similar Ns = Ns Cm deny 164Whether a new password is allowed to be similar to the old one. 165The passwords are considered to be similar when there is a sufficiently 166long common substring and the new password with the substring removed 167would be weak. 168.It Xo 169.Sm off 170.Cm random No = Ar N Op , Cm only 171.Sm on 172.Xc 173.Pq Cm random Ns = Ns 42 174The size of randomly-generated passwords in bits, or 0 to disable this 175feature. 176Passwords that contain the offered randomly-generated string will be 177allowed regardless of other possible restrictions. 178.Pp 179The 180.Cm only 181modifier can be used to disallow user-chosen passwords. 182.It Xo 183.Sm off 184.Cm enforce No = Cm none | users | everyone 185.Sm on 186.Xc 187.Pq Cm enforce Ns = Ns Cm everyone 188The module can be configured to warn of weak passwords only, but not 189actually enforce strong passwords. 190The 191.Cm users 192setting will enforce strong passwords for non-root users only. 193.It Cm non-unix 194Normally, 195.Nm 196uses 197.Xr getpwnam 3 198to obtain the user's personal login information and use that during 199the password strength checks. 200This behavior can be disabled with the 201.Cm non-unix 202option. 203.It Cm retry Ns = Ns Ar N 204.Pq Cm retry Ns = Ns 3 205The number of times the module will ask for a new password if the user 206fails to provide a sufficiently strong password and enter it twice the 207first time. 208.It Cm ask_oldauthtok Ns Op = Ns Cm update 209Ask for the old password as well. 210Normally, 211.Nm 212leaves this task for subsequent modules. 213With no argument, the 214.Cm ask_oldauthtok 215option will cause 216.Nm 217to ask for the old password during the preliminary check phase. 218If the 219.Cm ask_oldauthtok 220option is specified with the 221.Cm update 222argument, 223.Nm 224will do that during the update phase. 225.It Cm check_oldauthtok 226This tells 227.Nm 228to validate the old password before giving a 229new password prompt. 230Normally, this task is left for subsequent modules. 231.Pp 232The primary use for this option is when 233.Cm ask_oldauthtok Ns = Ns Cm update 234is also specified, in which case no other modules gets a chance to ask 235for and validate the password. 236Of course, this will only work with 237.Ux 238passwords. 239.It Cm use_first_pass , use_authtok 240Use the new password obtained by modules stacked before 241.Nm . 242This disables user interaction within 243.Nm . 244The only difference between 245.Cm use_first_pass 246and 247.Cm use_authtok 248is that the former is incompatible with 249.Cm ask_oldauthtok . 250.El 251.Sh SEE ALSO 252.Xr getpwnam 3 , 253.Xr pam.conf 5 , 254.Xr pam 8 255.Sh AUTHORS 256The 257.Nm 258module was written by 259.An Solar Designer Aq Mt solar@openwall.com . 260This manual page, derived from the author's documentation, was written 261for the 262.Fx 263Project by 264ThinkSec AS and NAI Labs, the Security Research Division of Network 265Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 266.Pq Dq CBOSS , 267as part of the DARPA CHATS research program. 268