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