docs/krb5-strength.pod

   1 =for stopwords
   2 Allbery CDB CrackLib Heimdal KDC KDCs canonicalization cracklib-format
   3 cracklib-packer heimdal-strength heimdal-history kadmind kpasswd kpasswdd
   4 krb5-strength mkdict pwqual cracklib-runtime krb5-strength-wordlist
   5
   6 =head1 NAME
   7
   8 krb5-strength - Kerberos password strength checking plugin
   9
  10 =head1 SYNOPSIS
  11
  12 MIT Kerberos:
  13
  14     [plugins]
  15       pwqual = {
  16         module = strength:@moduledir@/strength.so
  17       }
  18
  19 Heimdal:
  20
  21     [password_quality]
  22         policies         = krb5-strength
  23         policy_libraries = @moduledir@/strength.so
  24
  25 =head1 DESCRIPTION
  26
  27 F<strength.so> is a KDC plugin for Kerberos password strength checking for
  28 either MIT Kerberos or Heimdal provided as part of the krb5-strength
  29 package.  For MIT Kerberos KDCs (or, more to the point, kadmind servers),
  30 this plugin is the recommended way of enabling strength checking.  For
  31 Heimdal KDCs, you normally should use the B<heimdal-strength> external
  32 program instead, but the plugin is a supported option if you want to avoid
  33 external programs for some reason.
  34
  35 For this module to be effective for either Heimdal or MIT Kerberos, you
  36 will also need to construct a dictionary.  What type of dictionary you
  37 create depends on what backends you want to use: CrackLib, CDB, or SQLite.
  38
  39 For CrackLib, on Debian systems, you can install the cracklib-runtime
  40 package and use the B<cracklib-format> and B<cracklib-packer> utilities
  41 that come with it.  The former takes a set of wordlists and outputs a
  42 wordlist in the format required by B<cracklib-packer>, and the latter
  43 turns this into a CrackLib dictionary.  Alternately, you can use the
  44 B<mkdict> and B<packer> utilities, which are included in the krb5-strength
  45 package but not installed by default.  You can run them out of the
  46 F<cracklib> directory of the source tree after building.  (B<mkdict> is
  47 the equivalent of B<cracklib-format>.)
  48
  49 For building a CDB or SQLite dictionary, use B<krb5-strength-wordlist>.
  50
  51 =head1 CONFIGURATION
  52
  53 First, build and install either a CrackLib dictionary as described above.
  54 The CrackLib dictionary will consist of three files, one each ending in
  55 C<*.hwm>, C<*.pwd>, and C<*.pwi>.  The CDB and SQLite dictionaries will be
  56 single files, conventionally ending in C<*.cdb> and C<*.sqlite>
  57 respectively.  Install those files somewhere on your system.  Then, follow
  58 the relevant instructions below for either L</Heimdal> or L</MIT
  59 Kerberos>.
  60
  61 See L</Other Settings> below for additional F<krb5.conf> setting supported
  62 by both Heimdal and MIT Kerberos.
  63
  64 =head2 Heimdal
  65
  66 There are two options: using an external password check program, or using
  67 the plugin.  I recommend the external password check program unless you
  68 encounter speed problems with that approach that cause B<kpasswd> to time
  69 out.  If you choose to use the external program, read the
  70 B<heimdal-strength> documentation instead of this documentation.
  71
  72 If using the module, first add a stanza like the following to the
  73 C<[appdefaults]> section of your F</etc/krb5.conf> (or wherever your
  74 F<krb5.conf> file is located):
  75
  76     krb5-strength = {
  77         password_dictionary        = /path/to/cracklib/dictionary
  78         password_dictionary_cdb    = /path/to/cdb/dictionary.cdb
  79         password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite
  80     }
  81
  82 The first setting configures a CrackLib dictionary, the second a CDB
  83 dictionary, and the third a SQLite dictionary.  The provided path should
  84 be the full path to the dictionary files, omitting the trailing C<*.hwm>,
  85 C<*.pwd>, and C<*.pwi> extensions for the CrackLib dictionary (but
  86 including the extensions for the other types).  You can use any
  87 combination of the three settings.  If you use more than one, CrackLib
  88 will be checked first, then CDB, and then SQLite as appropriate.
  89
  90 When checking against a CDB database, the password, the password with the
  91 first character removed, the last character removed, the first and last
  92 characters removed, the first two characters removed, and the last two
  93 characters removed will all be checked against the dictionary.
  94
  95 When checking a SQLite database, the password will be rejected if it is
  96 within edit distance one of any word in the dictionary, meaning that the
  97 database word can be formed from the password by deleting, adding, or
  98 changing a single character.
  99
 100 Then, add a new section (or modify the existing C<[password_quality]>
 101 section) like the following:
 102
 103     [password_quality]
 104         policies         = krb5-strength
 105         policy_libraries = @moduledir@/strength.so
 106
 107 in either F<krb5.conf> or F<kdc.conf>.  Note that some older versions of
 108 Heimdal have a bug in the support for loading modules when
 109 C<policy_libraries> is set.  If you get an error like:
 110
 111     didn't find `kadm5_password_verifier' symbol in `(null)'
 112
 113 you may have to omit C<policy_libraries> in your configuration and instead
 114 pass the C<--check-library argument> to B<kpasswdd> specifying the library
 115 to load.
 116
 117 If you want to also enable history checking, see L<heimdal-history(1)> for
 118 further instructions.
 119
 120 =head2 MIT Kerberos
 121
 122 To add this module to the list of password quality checks, add a section
 123 to F<krb5.conf> (or to a separate F<kdc.conf> if you use that) like:
 124
 125     [plugins]
 126       pwqual = {
 127         module = strength:@moduledir@/strength.so
 128       }
 129
 130 to register the plugin.
 131
 132 There are two ways to tell where the dictionary is.  One option is to use
 133 F<krb5.conf> (and in this case you must use F<krb5.conf>, even if you use
 134 a separate F<kdc.conf> file).  For this approach, add the following to the
 135 C<[appdefaults]> section:
 136
 137     krb5-strength = {
 138         password_dictionary        = /path/to/cracklib/dictionary
 139         password_dictionary_cdb    = /path/to/cdb/dictionary.cdb
 140         password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite
 141     }
 142
 143 The first setting configures a CrackLib dictionary, the second a CDB
 144 dictionary, and the third a SQLite dictionary.  The provided path should
 145 be the full path to the dictionary files, omitting the trailing C<*.hwm>,
 146 C<*.pwd>, and C<*.pwi> extensions for the CrackLib dictionary (but
 147 including the extensions for the other types).  You can use any
 148 combination of the three settings.  If you use more than one, CrackLib
 149 will be checked first, then CDB, and then SQLite as appropriate.
 150
 151 When checking against a CDB database, the password, the password with the
 152 first character removed, the last character removed, the first and last
 153 characters removed, the first two characters removed, and the last two
 154 characters removed will all be checked against the dictionary.
 155
 156 When checking a SQLite database, the password will be rejected if it is
 157 within edit distance one of any word in the dictionary, meaning that the
 158 database word can be formed from the password by deleting, adding, or
 159 changing a single character.
 160
 161 The second option is to use the normal C<dict_path> setting.  In the
 162 C<[realms]> section of your F<krb5.conf> or F<kdc.conf>, under the
 163 appropriate realm or realms, specify the path to the dictionary:
 164
 165     dict_file = /path/to/cracklib/dictionary
 166
 167 This will be taken as a CrackLib dictionary path, the same as the setting
 168 for password_dictionary above.  The provided path should be the full path
 169 to the dictionary files, omitting the trailing C<*.hwm>, C<*.pwd>, or
 170 C<*.pwi> extension.  However, be aware that, if you use this approach, you
 171 will probably want to disable the built-in standard dict pwqual plugin by
 172 adding the line:
 173
 174     disable = dict
 175
 176 to the C<pwqual> block of the C<[plugins]> section as shown above.
 177 Otherwise, it will also try to load a dictionary at the same path to do
 178 simple dictionary matching.
 179
 180 You can also mix and match these settings, by using C<dict_path> for the
 181 CrackLib dictionary path and F<krb5.conf> for the CDB or SQLite dictionary
 182 paths.  If both settings are used for the CrackLib path, F<krb5.conf>
 183 overrides the C<dict_path> setting (so that C<dict_path> can be used for
 184 other password quality modules).  There is no way to specify a CDB or
 185 SQLite dictionary via the C<dict_path> setting.
 186
 187 =head2 Other Settings
 188
 189 The following additional settings are supported in the C<[appdefaults]>
 190 section of F<krb5.conf> when running under either Heimdal or MIT Kerberos.
 191
 192 =over 4
 193
 194 =item cracklib_maxlen
 195
 196 Normally, all passwords are checked with CrackLib if a CrackLib dictionary
 197 is defined.  However, CrackLib's rules were designed for a world in which
 198 most passwords were four to eight characters long, and tends to spuriously
 199 reject a lot of passphrases.  If this option is set to something other
 200 than its default of 0, passwords longer than that length bypass CrackLib
 201 checks.  (Using a SQLite dictionary for longer passwords is strongly
 202 recommended.)
 203
 204 =item minimum_different
 205
 206 If set to a numeric value, passwords with fewer than this number of unique
 207 characters will be rejected.  This can be used to reject, for example,
 208 passwords that are long strings of the same character or repetitions of
 209 small numbers of characters, which may be too easy to guess.
 210
 211 =item minimum_length
 212
 213 If set to a numeric value, passwords with fewer than that number of
 214 characters will be rejected, independent of any length restrictions in
 215 CrackLib.  Note that this setting does not bypass the minimum length
 216 requirements in CrackLib itself (which, for the version embedded in this
 217 package, is eight characters).
 218
 219 =item require_ascii_printable
 220
 221 If set to a true boolean value, rejects any password that contains
 222 non-ASCII characters or ASCII control characters.  Spaces are allowed;
 223 tabs are not (at least assuming the POSIX C locale).  No canonicalization
 224 or character set is defined for Kerberos passwords in general, so you may
 225 want to reject non-ASCII characters to avoid interoperability problems
 226 with computers with different default character sets or Unicode
 227 normalization forms.
 228
 229 =item require_classes
 230
 231 This option allows specification of more complex character class
 232 requirements.  The value of this parameter should be one or more
 233 whitespace-separated rule.  Each rule has the syntax:
 234
 235     [<min>-<max>:]<class>[,<class>...]
 236
 237 where <class> is one of C<upper>, C<lower>, C<digit>, or C<symbol>
 238 (without quote marks), or an integer representing a minimum number of
 239 character classes.  The symbol class includes all characters other than
 240 alphanumeric characters, including space.  The listed classes must appear
 241 in the password.  Separate multiple required classes with a comma (and no
 242 space).
 243
 244 The character class checks will be done in whatever locale the plugin or
 245 password check program is run in, which will normally be the POSIX C
 246 locale but may be different depending on local configuration.
 247
 248 A simple example:
 249
 250     require_classes = upper,lower,digit
 251
 252 This requires all passwords contain at least one uppercase letter, at
 253 least one lowercase letter, and at least one digit.
 254
 255 If present, <min> and <max> specify the minimum password length and
 256 maximum password length to which this rule applies.  This allows one to
 257 specify character class requirements that change with password length.
 258 So, for example:
 259
 260     require_classes = 8-19:upper,lower 8-15:digit 8-11:symbol
 261
 262 requires all passwords from 8 to 11 characters long contain all four
 263 character classes, passwords from 12 to 15 characters long contain upper
 264 and lower case and a digit, and passwords from 16 to 19 characters long
 265 contain both upper and lower case.  Passwords longer than 20 characters
 266 have no character class restrictions.  (This example is probably used in
 267 conjunction with C<minimum_length = 8>.)
 268
 269 C<require_classes> also supports specifying the minimum number of
 270 character classes a password should contain.  For example:
 271
 272     require_classes = 3
 273
 274 would require all passwords to have a minimum of any three of the
 275 character classes.
 276
 277 This can also be used with <min> and <max> ranges, as above.  For example:
 278
 279     require_classes = 8-11:3 12-19:2
 280
 281 requires all passwords from 8 to 11 characters contain at least three
 282 different character classes, and passwords from 12 to 19 characters
 283 contain at least two different character classes.  Ranges can overlap, as
 284 in the examples above, but this makes less sense when specifying a minimum
 285 number of classes.
 286
 287 Minimum numbers of character classes can be combined with specific
 288 character classes.  For example:
 289
 290     require_classes = symbol,3
 291
 292 requires all passwords contain three distinct character classes and must
 293 contain a symbol character.
 294
 295 =item require_non_letter
 296
 297 If set to a true boolean value, the password must contain at least one
 298 character that is not a letter (uppercase or lowercase) or a space.  This
 299 may be helpful in combination with passphrases; users may choose a stock
 300 English phrase, and this will force at least some additional complexity.
 301
 302 =back
 303
 304 You can omit any dictionary setting and only use the above settings, in
 305 which case only the above checks and checks for passwords based on the
 306 principal will be done, bypassing any dictionary check.  (But for that
 307 simple style of password strength checking, there are probably better
 308 strength checking plugins already available.)
 309
 310 =head1 AUTHOR
 311
 312 Russ Allbery <eagle@eyrie.org>
 313
 314 =head1 COPYRIGHT AND LICENSE
 315
 316 Copyright 2016 Russ Allbery <eagle@eyrie.org>
 317
 318 Copyright 2006, 2007, 2009, 2010, 2012, 2013, 2014 The Board of Trustees
 319 of the Leland Stanford Junior University
 320
 321 Copying and distribution of this file, with or without modification, are
 322 permitted in any medium without royalty provided the copyright notice and
 323 this notice are preserved.  This file is offered as-is, without any
 324 warranty.
 325
 326 =head1 SEE ALSO
 327
 328 L<cracklib-format(8)>, L<cracklib-packer(8)>, L<heimdal-strength(1)>,
 329 L<krb5-strength-wordlist(1)>
 330
 331 =cut