lib/libpam/modules/pam_passwdqc/pam_passwdqc.8

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