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 18n 76.It Cm min Ns = Ns Ar N0 Ns , Ns Ar N1 Ns , Ns Ar N2 Ns , Ns Ar N3 Ns , Ns Ar N4 77(min=disabled,24,12,8,7) 78The minimum allowed password lengths for different kinds of passwords 79/ passphrases. 80The keyword 81.Dq disabled 82can be used to 83disallow passwords of a given kind regardless of their length. 84Each subsequent number is required to be no larger than the preceding 85one. 86.Pp 87N0 is used for passwords consisting of characters from one character 88class only. 89The character classes are: digits, lower-case letters, upper-case 90letters, and other characters. 91There is also a special class for non-ASCII characters which couldn't 92be classified, but are assumed to be non-digits. 93.Pp 94N1 is used for passwords consisting of characters from two character 95classes, which don't meet the requirements for a passphrase. 96.Pp 97N2 is used for passphrases. 98A passphrase must consist of sufficient words (see the 99.Cm passphrase 100option below). 101.Pp 102N3 and N4 are used for passwords consisting of characters from three 103and four character classes, respectively. 104.Pp 105When calculating the number of character classes, upper-case letters 106used as the first character and digits used as the last character of a 107password are not counted. 108.Pp 109In addition to being sufficiently long, passwords are required to 110contain enough different characters for the character classes and 111the minimum length they've been checked against. 112.Pp 113.It Cm max Ns = Ns Ar N 114(max=40) 115The maximum allowed password length. 116This can be used to prevent users from setting passwords which may be 117too long for some system services. 118The value 8 is treated specially: if 119.Cm max 120is set to 8, passwords longer than 8 characters will not be rejected, 121but will be truncated to 8 characters for the strength checks and the 122user will be warned. 123This is for compatibility with the traditional DES password hashes, 124which truncate the password at 8 characters. 125.Pp 126It is important that you do set max=8 if you're using the traditional 127hashes, or some weak passwords will pass the checks. 128.It Cm passphrase Ns = Ns Ar N 129(passphrase=3) 130The number of words required for a passphrase, or 0 to disable 131passphrase support. 132.It Cm match Ns = Ns Ar N 133(match=4) 134The length of common substring required to conclude that a password is 135at least partially based on information found in a character string, 136or 0 to disable the substring search. 137Note that the password will not be rejected once a weak substring is 138found; it will instead be subjected to the usual strength requirements 139with the weak substring removed. 140.Pp 141The substring search is case-insensitive and is able to detect and 142remove a common substring spelled backwards. 143.It Cm similar Ns = Ns Ar permit Ns | Ns Ar deny 144(similar=deny) 145Whether a new password is allowed to be similar to the old one. 146The passwords are considered to be similar when there's a sufficiently 147long common substring and the new password with the substring removed 148would be weak. 149.It Cm random Ns = Ns Ar N Ns Op , Ns Ar only 150(random=42) 151The size of randomly-generated passwords in bits, or 0 to disable this 152feature. 153Passwords that contain the offered randomly-generated string will be 154allowed regardless of other possible restrictions. 155.Pp 156The 157.Dq only 158modifier can be used to disallow user-chosen passwords. 159.It Cm enforce Ns = Ns Ar none Ns | Ns Ar users Ns | Ns Ar everyone 160(enforce=everyone) 161The module can be configured to warn of weak passwords only, but not 162actually enforce strong passwords. 163The 164.Dq users 165setting will enforce strong passwords for non-root users only. 166.It Cm non-unix 167Normally, 168.Nm 169uses 170.Xr getpwnam 3 171to obtain the user's personal login information and use that during 172the password strength checks. 173This behavior can be disabled with the 174.Cm non-unix 175option. 176.It Cm retry Ns = Ns Ar N 177(retry = 3) 178The number of times the module will ask for a new password if the user 179fails to provide a sufficiently strong password and enter it twice the 180first time. 181.It Cm ask_oldauthtok Ns Op = Ns Ar update 182Ask for the old password as well. 183Normally, pam_passwdqc leaves this task for subsequent modules. 184With no argument, the 185.Cm ask_oldauthtok 186option will cause 187.Nm 188to ask for the old password during the preliminary check phase. 189If the 190.Cm ask_oldauthtok 191option is specified with the 192.Dq update 193argument, 194.Nm 195will do that during the update phase. 196.It Cm check_oldauthtok 197This tells pam_passwdqc to validate the old password before giving a 198new password prompt. 199Normally, this task is left for subsequent modules. 200.Pp 201The primary use for this option is when 202.Cm ask_oldauthtok Ns = Ns Ar update 203is also specified, in which case no other modules gets a chance to ask 204for and validate the password. 205Of course, this will only work with Unix passwords. 206.It Cm use_first_pass Ns , Ns Cm use_authtok 207Use the new password obtained by modules stacked before 208.Nm . 209This disables user interaction within 210.Nm . 211The only difference between 212.Cm use_first_pass 213and 214.Cm use_authtok 215is that the former is incompatible with 216.Cm ask_oldauthtok . 217.El 218.Sh SEE ALSO 219.Xr getpwnam 3 , 220.Xr pam.conf 5 , 221.Xr pam 8 222.Sh AUTHORS 223The 224.Nm 225module was written by 226.An Solar Designer Aq solar@openwall.com . 227This manual page, derived from the author's documentation, was written 228for the 229.Fx 230Project by 231ThinkSec AS and NAI Labs, the Security Research Division of Network 232Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 233.Pq Dq CBOSS , 234as part of the DARPA CHATS research program. 235