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