contrib/pam_passwdqc/pam_passwdqc.8

   1 .\" Copyright (c) 2000-2003,2005,2008 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: src/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8,v 1.4 2002/05/30 14:49:57 ru Exp $
  36 .\" $Owl: Owl/packages/pam_passwdqc/pam_passwdqc/pam_passwdqc.8,v 1.11 2008/02/12 20:33:09 solar Exp $
  37 .\"
  38 .Dd February 12, 2008
  39 .Dt PAM_PASSWDQC 8
  40 .Os
  41 .Sh NAME
  42 .Nm pam_passwdqc
  43 .Nd Password quality-control PAM module
  44 .Sh SYNOPSIS
  45 .Op Ar service-name
  46 .Ar module-type
  47 .Ar control-flag
  48 .Pa pam_passwdqc
  49 .Op Ar options
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 module is a simple password strength checking module for
  54 PAM.
  55 In addition to checking regular passwords, it offers support for
  56 passphrases and can provide randomly generated ones.
  57 .Pp
  58 The
  59 .Nm
  60 module provides functionality for only one PAM management group:
  61 password changing.
  62 In terms of the
  63 .Ar module-type
  64 parameter, this is the
  65 .Dq Li password
  66 feature.
  67 .Pp
  68 The
  69 .Fn pam_chauthtok
  70 service function may ask the user for a new password, and verify that
  71 it meets certain minimum standards.
  72 If the chosen password is unsatisfactory, the service function returns
  73 .Dv PAM_AUTHTOK_ERR .
  74 .Pp
  75 The following options may be passed to the module:
  76 .Bl -tag -width indent
  77 .It Xo
  78 .Sm off
  79 .Cm min No = Ar N0 , N1 , N2 , N3 , N4
  80 .Sm on
  81 .Xc
  82 .Sm off
  83 .Pq Cm min No = Cm disabled , No 24 , 11 , 8 , 7
  84 .Sm on
  85 The minimum allowed password lengths for different kinds of
  86 passwords/passphrases.
  87 The keyword
  88 .Cm disabled
  89 can be used to
  90 disallow passwords of a given kind regardless of their length.
  91 Each subsequent number is required to be no larger than the preceding
  92 one.
  93 .Pp
  94 .Ar N0
  95 is used for passwords consisting of characters from one character
  96 class only.
  97 The character classes are: digits, lower-case letters, upper-case
  98 letters, and other characters.
  99 There is also a special class for
 100 .No non- Ns Tn ASCII
 101 characters, which could not 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 that do not meet the requirements for a passphrase.
 106 .Pp
 107 .Ar N2
 108 is used for passphrases.
 109 Note that besides meeting this length requirement,
 110 a passphrase must also consist of a sufficient number of words (see the
 111 .Cm passphrase
 112 option below).
 113 .Pp
 114 .Ar N3
 115 and
 116 .Ar N4
 117 are used for passwords consisting of characters from three
 118 and four character classes, respectively.
 119 .Pp
 120 When calculating the number of character classes, upper-case letters
 121 used as the first character and digits used as the last character of a
 122 password are not counted.
 123 .Pp
 124 In addition to being sufficiently long, passwords are required to
 125 contain enough different characters for the character classes and
 126 the minimum length they have been checked against.
 127 .Pp
 128 .It Cm max Ns = Ns Ar N
 129 .Pq Cm max Ns = Ns 40
 130 The maximum allowed password length.
 131 This can be used to prevent users from setting passwords that may be
 132 too long for some system services.
 133 The value 8 is treated specially: if
 134 .Cm max
 135 is set to 8, passwords longer than 8 characters will not be rejected,
 136 but will be truncated to 8 characters for the strength checks and the
 137 user will be warned.
 138 This is to be used with the traditional DES-based password hashes,
 139 which truncate the password at 8 characters.
 140 .Pp
 141 It is important that you do set
 142 .Cm max Ns = Ns 8
 143 if you are using the traditional
 144 hashes, or some weak passwords will pass the checks.
 145 .It Cm passphrase Ns = Ns Ar N
 146 .Pq Cm passphrase Ns = Ns 3
 147 The number of words required for a passphrase, or 0 to disable the
 148 support for user-chosen passphrases.
 149 .It Cm match Ns = Ns Ar N
 150 .Pq Cm match Ns = Ns 4
 151 The length of common substring required to conclude that a password is
 152 at least partially based on information found in a character string,
 153 or 0 to disable the substring search.
 154 Note that the password will not be rejected once a weak substring is
 155 found; it will instead be subjected to the usual strength requirements
 156 with the weak substring removed.
 157 .Pp
 158 The substring search is case-insensitive and is able to detect and
 159 remove a common substring spelled backwards.
 160 .It Xo
 161 .Sm off
 162 .Cm similar No = Cm permit | deny
 163 .Sm on
 164 .Xc
 165 .Pq Cm similar Ns = Ns Cm deny
 166 Whether a new password is allowed to be similar to the old one.
 167 The passwords are considered to be similar when there is a sufficiently
 168 long common substring and the new password with the substring removed
 169 would be weak.
 170 .It Xo
 171 .Sm off
 172 .Cm random No = Ar N Op , Cm only
 173 .Sm on
 174 .Xc
 175 .Pq Cm random Ns = Ns 42
 176 The size of randomly-generated passphrases in bits (24 to 72),
 177 or 0 to disable this feature.
 178 Any passphrase that contains the offered randomly-generated string will be
 179 allowed regardless of other possible restrictions.
 180 .Pp
 181 The
 182 .Cm only
 183 modifier can be used to disallow user-chosen passwords.
 184 .It Xo
 185 .Sm off
 186 .Cm enforce No = Cm none | users | everyone
 187 .Sm on
 188 .Xc
 189 .Pq Cm enforce Ns = Ns Cm everyone
 190 The module can be configured to warn of weak passwords only, but not
 191 actually enforce strong passwords.
 192 The
 193 .Cm users
 194 setting will enforce strong passwords for invocations by non-root users only.
 195 .It Cm non-unix
 196 Normally,
 197 .Nm
 198 uses
 199 .Xr getpwnam 3
 200 to obtain the user's personal login information and use that during
 201 the password strength checks.
 202 This behavior can be disabled with the
 203 .Cm non-unix
 204 option.
 205 .It Cm retry Ns = Ns Ar N
 206 .Pq Cm retry Ns = Ns 3
 207 The number of times the module will ask for a new password if the user
 208 fails to provide a sufficiently strong password and enter it twice the
 209 first time.
 210 .It Cm ask_oldauthtok Ns Op = Ns Cm update
 211 Ask for the old password as well.
 212 Normally,
 213 .Nm
 214 leaves this task for subsequent modules.
 215 With no argument, the
 216 .Cm ask_oldauthtok
 217 option will cause
 218 .Nm
 219 to ask for the old password during the preliminary check phase.
 220 If the
 221 .Cm ask_oldauthtok
 222 option is specified with the
 223 .Cm update
 224 argument,
 225 .Nm
 226 will do that during the update phase.
 227 .It Cm check_oldauthtok
 228 This tells
 229 .Nm
 230 to validate the old password before giving a
 231 new password prompt.
 232 Normally, this task is left for subsequent modules.
 233 .Pp
 234 The primary use for this option is when
 235 .Cm ask_oldauthtok Ns = Ns Cm update
 236 is also specified, in which case no other module gets a chance to ask
 237 for and validate the password.
 238 Of course, this will only work with
 239 .Ux
 240 passwords.
 241 .It Cm use_first_pass , use_authtok
 242 Use the new password obtained by modules stacked before
 243 .Nm .
 244 This disables user interaction within
 245 .Nm .
 246 The only difference between
 247 .Cm use_first_pass
 248 and
 249 .Cm use_authtok
 250 is that the former is incompatible with
 251 .Cm ask_oldauthtok .
 252 .El
 253 .Sh SEE ALSO
 254 .Xr getpwnam 3 ,
 255 .Xr pam.conf 5 ,
 256 .Xr pam 8
 257 .Sh AUTHORS
 258 The
 259 .Nm
 260 module was written for Openwall GNU/*/Linux by
 261 .An Solar Designer Aq solar at openwall.com .
 262 This manual page, derived from the author's documentation, was written
 263 for the
 264 .Fx
 265 Project by
 266 ThinkSec AS and NAI Labs, the Security Research Division of Network
 267 Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
 268 .Pq Dq CBOSS ,
 269 as part of the DARPA CHATS research program.