2 (Kerberos password strength checking plugin)
4 Maintained by Russ Allbery <eagle@eyrie.org>
6 Copyright 2006, 2007, 2009, 2010, 2012, 2013 The Board of Trustees of
7 the Leland Stanford Junior University. Portions copyright 1993 Alec
8 Muffett. Developed by Derrick Brashear and Ken Hornstein of Sine Nomine
9 Associates, on behalf of Stanford University. This software is
10 distributed under a BSD-style license and under the Artistic License.
11 Please see the section LICENSE for more information.
15 krb5-strength provides a password quality plugin for the MIT Kerberos
16 KDC (specifically the kadmind server) and an external password quality
17 program for use with the Heimdal kpasswdd server. Passwords can be
18 tested with CrackLib, checked against a CDB database of known weak
19 passwords, checked for length, checked for non-printable or non-ASCII
20 characters that may be difficult to enter reproducibly, required to
21 contain a non-alphabetic character, or any combination of these tests.
22 It supports both Heimdal and MIT Kerberos (1.9 or later).
26 Heimdal includes a capability to plug in external password quality
27 checks and comes with an example that checks passwords against CrackLib.
28 However, in testing at Stanford, we found that CrackLib with its default
29 transform rules does not catch passwords that can be guessed using the
30 same dictionary with other tools, such as Jack the Ripper.
32 This plugin provides the ability to check password quality against the
33 standard version of CrackLib, or against a modified version of CrackLib
34 that only passes passwords that resist attacks from both Crack and Jack
35 the Ripper using the same rule sets. For Heimdal, it includes both a
36 program usable as an external password quality check and a plugin that
37 implements the dynamic module API. For MIT Kerberos (1.9 or later), it
38 includes a plugin for the password quality (pwqual) plugin API.
40 krb5-strength can be built with either the system CrackLib or with the
41 modified version of CrackLib included in this package. Note, however,
42 that if you're building against the system CrackLib, Heimdal includes in
43 the distribution a strength-checking plugin and an external password
44 check program that use the system CrackLib. With Heimdal, it would
45 probably be easier to use that plugin or program than build this package
46 unless you want the modified CrackLib.
48 For information about the changes to the CrackLib included in this
49 toolkit, see cracklib/HISTORY. The primary changes are tighter rules,
50 which are more aggressive at finding dictionary words with characters
51 appended and prepended, which tighten the requirements for password
52 entropy, and which add stricter rules for longer passwords. They are
53 also minor changes to fix portability issues and remove some code that
54 doesn't make sense in the kadmind context.
56 Ideally, the changes to CrackLib should be added to the standard
57 CrackLib distribution by adding an additional interface to configure its
58 behavior, at which point this package can likely wither away in favor of
59 much simpler plugins that link to the standard CrackLib library.
63 For Heimdal, you may use either the external password quality check
64 tool, installed as heimdal-strength, or the plugin as you choose. It
65 has been tested with Heimdal 1.2.1 and later, but has not recently been
66 tested with versions prior to 1.5.
68 For MIT Kerberos, version 1.9 or higher is required for the password
69 quality plugin interface. MIT Kerberos does not support an external
70 password quality check tool directly, so you will need to install the
73 You can optionally build against the system CrackLib library. Any
74 version should be supported, but note that some versions, particularly
75 older versions close to the original code, do things like printing
76 diagnostics to stderr, calling exit, and otherwise not being
77 well-behaved for use inside plugins or libraries. If using a system
78 CrackLib library, use version 2.8.22 or later to avoid these problems.
80 You can also optionally build against the TinyCDB library, which
81 provides support for simpler and faster password checking against a CDB
82 dictionary file. Building a CDB dictionary with cdbmake-wordlist
83 (included) requires Perl 5.006 or later and the CDB utility that comes
86 For this module to be effective for either Heimdal or MIT Kerberos, you
87 will also need to construct a dictionary. The mkdict and packer
88 utilities to build a CrackLib dictionary from a word list are included
89 in this toolkit but not installed by default. You can run them out of
90 the cracklib directory after building. You can also use the utilities
91 that come with the stock CrackLib package (often already packaged in a
92 Linux distribution); the database format is compatible. For building a
93 CDB dictionary, use the provided cdbmake-wordlist program. The CDB
94 utility must be on your PATH.
96 For a word list to use as source for the dictionary, you can use
97 /usr/share/dict/words if it's available on your system, but it would be
98 better to find a more comprehensive word list. Since word lists are
99 bulky, often covered by murky copyrights, and easily locatable on the
100 Internet with a modicum of searching, none are included in this toolkit.
102 To run the test suite, you will also need Perl 5.006 or later. The
103 following additional Perl modules will be used by the test suite if
115 All are available on CPAN. Those tests will be skipped if the modules
118 To enable tests that may be sensitive to the local environment or that
119 produce a lot of false positives without uncovering many problems, set
120 RRA_MAINTAINER_TESTS to a true value.
122 To bootstrap from a Git checkout, or If you change the Automake files
123 and need to regenerate Makefile.in, you will need Automake 1.11 or
124 later. For bootstrap or if you change configure.ac or any of the m4
125 files it includes and need to regenerate configure or config.h.in, you
126 will need Autoconf 2.64 or later.
128 COMPILING AND INSTALLING
130 You can build and install the plugin with the standard commands:
136 Pass --enable-silent-rules to configure for a quieter build (similar to
137 the Linux kernel). Use make warnings instead of make to build with full
138 GCC compiler warnings (requires a relatively current version of GCC).
140 The last step will probably have to be done as root. By default, the
141 plugin is installed as /usr/local/lib/krb5/plugins/pwqual/strength.so
142 and the Heimdal external password check function is installed as
143 /usr/local/bin/heimdal-strength. You can change these paths with the
144 --prefix, --libdir, and --bindir options to configure.
146 To build with the system version of CrackLib, pass --with-cracklib to
147 configure. You can optionally add a directory, giving the root
148 directory where CrackLib was installed, or separately set the include
149 and library path with --with-cracklib-include and --with-cracklib-lib.
151 krb5-strength will automatically build with TinyCDB if it is found. To
152 specify the installation path of TinyCDB, use --with-tinycdb. You can
153 also separately set the include and library path with
154 --with-tinycdb-include and --with-tinycdb-lib.
156 Normally, configure will use krb5-config to determine the flags to use
157 to compile with your Kerberos libraries. If krb5-config isn't found, it
158 will look for the standard Kerberos libraries in locations already
159 searched by your compiler. If the the krb5-config script first in your
160 path is not the one corresponding to the Kerberos libraries you want to
161 use or if your Kerberos libraries and includes aren't in a location
162 searched by default by your compiler, you need to specify a different
163 Kerberos installation root via --with-krb5=PATH. For example:
165 ./configure --with-krb5=/usr/pubsw
167 You can also individually set the paths to the include directory and the
168 library directory with --with-krb5-include and --with-krb5-lib. You may
169 need to do this if Autoconf can't figure out whether to use lib, lib32,
170 or lib64 on your platform.
172 To specify a particular krb5-config script to use, either set the
173 PATH_KRB5_CONFIG environment variable or pass it to configure like:
175 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
177 To not use krb5-config and force library probing even if there is a
178 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
181 ./configure PATH_KRB5_CONFIG=/nonexistent
183 krb5-config is not used and library probing is always done if either
184 --with-krb5-include or --with-krb5-lib are given.
186 You can pass the --enable-reduced-depends flag to configure to try to
187 minimize the shared library dependencies encoded in the binaries. This
188 omits from the link line all the libraries included solely because the
189 Kerberos libraries depend on them and instead links the programs only
190 against libraries whose APIs are called directly. This will only work
191 with shared Kerberos libraries and will only work on platforms where
192 shared libraries properly encode their own dependencies (such as Linux).
193 It is intended primarily for building packages for Linux distributions
194 to avoid encoding unnecessary shared library dependencies that make
195 shared library migrations more difficult. If none of the above made any
196 sense to you, don't bother with this flag.
200 First, build and install either a CrackLib dictionary as described in
201 REQUIREMENTS above, or build a CDB dictionary with cdbmake-wordlist.
202 (Or both.) The CrackLib dictionary will consist of three files, one
203 each ending in *.hwm, *.pwd, and *.pwi. The CDB dictionary will consist
204 of a single file ending in *.cdb. Install those files somewhere on your
205 system. Then, follow the relevant instructions below for either Heimdal
208 See "Other Settings" below for additional krb5.conf setting supported by
209 both Heimdal and MIT Kerberos.
213 There are two options: using an external password check program, or
214 using the plugin. I recommend the external password check program
215 unless you encounter speed problems with that approach that cause
218 For either approach, first add a stanza like the following to the
219 [appdefaults] section of your /etc/krb5.conf (or wherever your krb5.conf
223 password_dictionary = /path/to/cracklib/dictionary
224 password_dictionary_cdb = /path/to/cdb/dictionary.cdb
227 The first setting configures a CrackLib dictionary and the second a CDB
228 dictionary. The provided path should be the full path to the dictionary
229 files, omitting the trailing *.hwm, *.pwd, and *.pwi extensions for the
230 CrackLib dictionary. You can use either or both settings. If you use
231 both, CrackLib will be checked first, and then CDB.
233 Then, for the external password checking program, add a new section (or
234 modify the existing [password_quality] section) to look like the
238 policies = external-check
239 external_program = /usr/local/bin/heimdal-strength
241 You can, of course, combine this policy with others. Replace the path
242 with the full path to wherever you have installed heimdal-strength. You
243 can put this section in your kdc.conf instead of krb5.conf if you
246 If you want to instead use the module, use the following section
250 policies = krb5-strength
251 policy_libraries = /usr/local/lib/krb5/plugins/pwqual/strength.so
253 in either krb5.conf or kdc.conf. Note that some older versions of
254 Heimdal have a bug in the support for loading modules when
255 policy_libraries is set. If you get an error like:
257 didn't find `kadm5_password_verifier' symbol in `(null)'
259 you may have to omit policy_libraries in your configuration and instead
260 pass the --check-library argument to kpasswdd specifying the library to
265 To add this module to the list of password quality checks, add a section
266 to krb5.conf (or to a separate kdc.conf if you use that) like:
270 module = strength:/usr/local/lib/krb5/plugins/pwqual/strength.so
273 to register the plugin.
275 There are two ways to tell where the dictionary is. One option is to
276 use krb5.conf (and in this case you must use krb5.conf, even if you use
277 a separate kdc.conf file). For this approach, add the following to the
278 [appdefaults] section:
281 password_dictionary = /path/to/cracklib/dictionary
282 password_dictionary_cdb = /path/to/cdb/dictionary.cdb
285 The first setting configures a CrackLib dictionary and the second a CDB
286 dictionary. The provided path should be the full path to the dictionary
287 files, omitting the trailing *.hwm, *.pwd, and *.pwi extensions for the
288 CrackLib dictionary. You can use either or both settings. If you use
289 both, CrackLib will be checked first, and then CDB.
291 The second option is to use the normal dict_path setting. In the
292 [realms] section of your krb5.conf kdc.conf, under the appropriate realm
293 or realms, specify the path to the dictionary:
295 dict_file = /path/to/cracklib/dictionary
297 This will be taken as a CrackLib dictionary path, the same as the
298 setting for password_dictionary above. The provided path should be the
299 full path to the dictionary files, omitting the trailing *.hwm, *.pwd,
300 or *.pwi extension. However, be aware that, if you use this approach,
301 you will probably want to disable the built-in standard dict pwqual
302 plugin by adding the line:
306 to the pwqual block of the [plugins] section as shown above. Otherwise,
307 it will also try to load a dictionary at the same path to do simple
310 You can also mix and match these settings, by using dict_path for the
311 CrackLib dictionary path and krb5.conf for the CDB dictionary path. If
312 both settings are used, krb5.conf overrides the dict_path setting (so
313 that dict_path can be used for other password quality modules). There
314 is no way to specify a CDB dictionary via the dict_path setting.
318 The following additional settings are supported in the [appdefaults]
319 section of krb5.conf when running under either Heimdal or MIT Kerberos.
323 If set to a numeric value, passwords with fewer than that number of
324 characters will be rejected, independent of any length restrictions
325 in CrackLib. Note that this setting does not bypass the minimum
326 length requirements in CrackLib itself (which, for the version
327 embedded in this package, is eight characters).
329 require_ascii_printable
331 If set to a true boolean value, rejects any password that contains
332 non-ASCII characters or ASCII control characters. Spaces are
333 allowed; tabs are not (at least assuming the POSIX C locale). No
334 canonicalization or character set is defined for Kerberos passwords
335 in general, so you may want to reject non-ASCII characters to avoid
336 interoperability problems with computers with different default
337 character sets or Unicode normalization forms.
341 If set to a true boolean value, the password must contain at least
342 one character that is not a letter (uppercase or lowercase) or a
343 space. This may be helpful in combination with passphrases; users
344 may choose a stock English phrase, and this will force at least some
345 additional complexity.
347 You can omit any dictionary setting and only use the above settings, in
348 which case only the above checks and checks for passwords based on the
349 principal will be done, bypassing any dictionary check. (But for that
350 simple style of password strength checking, there are probably better
351 strength checking plugins already available.)
355 The krb5-strength web page at:
357 http://www.eyrie.org/~eagle/software/krb5-strength/
359 will always have the current version of this package, the current
360 documentation, and pointers to any additional resources.
362 I welcome bug reports and patches for this package at eagle@eyrie.org.
363 However, please be aware that I tend to be extremely busy and work
364 projects often take priority. I'll save your mail and get to it as soon
365 as I can, but it may take me a couple of months.
369 krb5-strength is maintained using Git. You can access the current
370 source by cloning the repository at:
372 git://git.eyrie.org/kerberos/krb5-strength.git
374 or view the repository via the web at:
376 http://git.eyrie.org/?p=kerberos/krb5-strength.git
378 When contributing modifications, either patches (possibly generated by
379 git format-patch) or Git pull requests are welcome.
383 The krb5-strength package as a whole is covered by the following
384 copyright statement and license:
386 Copyright 2006, 2007, 2009, 2010, 2012, 2013
387 The Board of Trustees of the Leland Stanford Junior University
389 Permission is hereby granted, free of charge, to any person obtaining
390 a copy of this software and associated documentation files (the
391 "Software"), to deal in the Software without restriction, including
392 without limitation the rights to use, copy, modify, merge, publish,
393 distribute, sublicense, and/or sell copies of the Software, and to
394 permit persons to whom the Software is furnished to do so, subject to
395 the following conditions:
397 The above copyright notice and this permission notice shall be
398 included in all copies or substantial portions of the Software.
400 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
401 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
402 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
403 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
404 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
405 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
406 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
408 The embedded version of CrackLib (all files in the cracklib
409 subdirectory) is covered by the Artistic license. See the file
410 cracklib/LICENCE for more information. Combined derivative works that
411 include this code, such as binaries built with the embedded CrackLib,
412 will need to follow the terms of the Artistic license as well as the
415 All other individual files without an explicit exception below are
416 released under this license. Some files may have additional copyright
417 holders as noted in those files. There is detailed information about
418 the licensing of each file in the LICENSE file in this distribution.
420 Some files in this distribution are individually released under
421 different licenses, all of which are compatible with the above general
422 package license but which may require preservation of additional
423 notices. All required notices are preserved in the LICENSE file.