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