2 (Kerberos password strength checking plugin)
3 Maintained by Russ Allbery <eagle@eyrie.org>
5 Copyright 2016 Russ Allbery <eagle@eyrie.org>. Copyright 2006-2007,
6 2009-2010, 2012-2014 The Board of Trustees of the Leland Stanford Junior
7 University. Copyright 1993 Alec Muffett. This software is distributed
8 under a BSD-style license. Please see the section LICENSE below for
13 krb5-strength provides a password quality plugin for the MIT Kerberos
14 KDC (specifically the kadmind server) and Heimdal KDC, an external
15 password quality program for use with Heimdal, and a per-principal
16 password history implementation for Heimdal. Passwords can be tested
17 with CrackLib, checked against a CDB or SQLite database of known weak
18 passwords with some transformations, checked for length, checked for
19 non-printable or non-ASCII characters that may be difficult to enter
20 reproducibly, required to contain particular character classes, or any
21 combination of these tests.
25 Heimdal includes a capability to plug in external password quality
26 checks and comes with an example that checks passwords against CrackLib.
27 However, in testing at Stanford, we found that CrackLib with its default
28 transform rules does not catch passwords that can be guessed using the
29 same dictionary with other tools, such as Jack the Ripper. We then
30 discovered other issues with CrackLib with longer passwords, such as
31 some bad assumptions about how certain measures of complexity will
32 scale, and wanted to impose other limitations that it didn't support.
34 This plugin provides the ability to check password quality against the
35 standard version of CrackLib, or against a modified version of CrackLib
36 that only passes passwords that resist attacks from both Crack and Jack
37 the Ripper using the same rule sets. It also supports doing simpler
38 dictionary checks against a CDB database, which is fast with very large
39 dictionaries, or a SQLite database, which can reject all passwords
40 within edit distance one of a dictionary word. It can also impose other
41 programmatic checks on passwords such as character class requirements.
43 If you're just now starting with password checking, I recommend using
44 the SQLite database with a large wordlist and minimum password lengths.
45 We found this produced the best results with the least user frustration.
47 For Heimdal, krb5-strength includes both a program usable as an external
48 password quality check and a plugin that implements the dynamic module
49 API. For MIT Kerberos (1.9 or later), it includes a plugin for the
50 password quality (pwqual) plugin API.
52 krb5-strength can be built with either the system CrackLib or with the
53 modified version of CrackLib included in this package. Note, however,
54 that if you're building against the system CrackLib, Heimdal includes in
55 the distribution a strength-checking plugin and an external password
56 check program that use the system CrackLib. With Heimdal, it would
57 probably be easier to use that plugin or program than build this package
58 unless you want the modified CrackLib, one of the other dictionary
59 types, or the additional character class and length checks.
61 For information about the changes to the CrackLib included in this
62 toolkit, see cracklib/HISTORY. The primary changes are tighter rules,
63 which are more aggressive at finding dictionary words with characters
64 appended and prepended, which tighten the requirements for password
65 entropy, and which add stricter rules for longer passwords. They are
66 also minor changes to fix portability issues, remove some code that
67 doesn't make sense in the kadmind context, and close a few security
68 issues. The standard CrackLib distribution on at least some Linux
69 distributions now supports an additional interface to configure its
70 behavior, and krb5-strength should change in the future to use that
71 interface and drop the embedded copy.
73 krb5-strength also includes a password history implementation for
74 Heimdal. This is separate from the password strength implementation but
75 can be stacked with it so that both strength and history checks are
76 performed. This history implementation is available only via the
77 Heimdal external password quality interface. MIT Kerberos includes its
78 own password history implementation.
82 For Heimdal, you may use either the external password quality check
83 tool, installed as heimdal-strength, or the plugin as you choose. It
84 has been tested with Heimdal 1.2.1 and later, but has not recently been
85 tested with versions prior to 1.5.
87 For MIT Kerberos, version 1.9 or higher is required for the password
88 quality plugin interface. MIT Kerberos does not support an external
89 password quality check tool directly, so you will need to install the
92 You can optionally build against the system CrackLib library. Any
93 version should be supported, but note that some versions, particularly
94 older versions close to the original code, do things like printing
95 diagnostics to stderr, calling exit, and otherwise not being
96 well-behaved for use inside plugins or libraries. They also have known
97 security vulnerabilities. If using a system CrackLib library, use
98 version 2.8.22 or later to avoid these problems.
100 You can also optionally build against the TinyCDB library, which
101 provides support for simpler and faster password checking against a CDB
102 dictionary file, and the SQLite library (a version new enough to support
103 the sqlite3_open_v2 API; 3.7 should be more than sufficient), which
104 provides support for checking whether passwords are within edit distance
105 one of a dictionary word.
107 For this module to be effective for either Heimdal or MIT Kerberos, you
108 will also need to construct a dictionary. The mkdict and packer
109 utilities to build a CrackLib dictionary from a word list are included
110 in this toolkit but not installed by default. You can run them out of
111 the cracklib directory after building. You can also use the utilities
112 that come with the stock CrackLib package (often already packaged in a
113 Linux distribution); the database format is compatible.
115 For building a CDB or SQLite dictionary, use the provided
116 krb5-strength-wordlist program. For CDB dictionries, the cdb utility
117 must be on your PATH. For SQLite, the DBI and DBD::SQLite Perl modules
118 are required. krb5-strength-wordlist requires Perl 5.006 or later.
120 For a word list to use as source for the dictionary, you can use
121 /usr/share/dict/words if it's available on your system, but it would be
122 better to find a more comprehensive word list. Since word lists are
123 bulky, often covered by murky copyrights, and easily locatable on the
124 Internet with a modicum of searching, none are included in this toolkit.
126 The password history program, heimdal-history, requires Perl 5.010 or
127 later plus the following CPAN modules:
131 * Getopt::Long::Descriptive
136 and their dependencies.
138 To run the test suite, you will need Perl 5.010 or later and the
139 dependencies of the heimdal-history program. The following additional
140 Perl modules will also be used by the test suite if present:
143 * Test::MinimumVersion
149 All are available on CPAN. Some tests will be skipped if the modules
152 To enable tests that don't detect functionality problems but are used to
153 sanity-check the release, set the environment variable RELEASE_TESTING
154 to a true value. To enable tests that may be sensitive to the local
155 environment or that produce a lot of false positives without uncovering
156 many problems, set the environment variable AUTHOR_TESTING to a true
159 To bootstrap from a Git checkout, or if you change the Automake files
160 and need to regenerate Makefile.in, you will need Automake 1.11 or
161 later. For bootstrap or if you change configure.ac or any of the m4
162 files it includes and need to regenerate configure or config.h.in, you
163 will need Autoconf 2.64 or later. You will also need Perl 5.010 or
164 later and the DBI, DBD::SQLite, JSON, Perl6::Slurp, and Readonly modules
165 (from CPAN) to generate man pages and bootstrap the test suite data from
168 BUILDING AND INSTALLATION
170 You can build and install krb5-strength with the standard commands:
176 If you are building from a Git clone, first run ./bootstrap in the
177 source directory to generate the build files. make install will
178 probably have to be done as root. Building outside of the source
179 directory is also supported, if you wish, by creating an empty directory
180 and then running configure with the correct relative path.
182 By default, the Heimdal external password check function is installed as
183 /usr/local/bin/heimdal-strength, and the plugin is installed as
184 /usr/local/lib/krb5/plugins/pwqual/strength.so. You can change these
185 paths with the --prefix, --libdir, and --bindir options to configure.
187 By default, the embedded version of CrackLib will be used. To build
188 with the system version of CrackLib, pass --with-cracklib to configure.
189 You can optionally add a directory, giving the root directory where
190 CrackLib was installed, or separately set the include and library path
191 with --with-cracklib-include and --with-cracklib-lib. You can also
192 build without any CrackLib support by passing --without-cracklib to
195 krb5-strength will automatically build with TinyCDB if it is found. To
196 specify the installation path of TinyCDB, use --with-tinycdb. You can
197 also separately set the include and library path with
198 --with-tinycdb-include and --with-tinycdb-lib.
200 Similarly, krb5-strength will automatically build with SQLite if it is
201 found. To specify the installation path of SQLite, use --with-sqlite.
202 You can also separately set the include and library path with
203 --with-sqlite-include and --with-sqlite-lib.
205 Normally, configure will use krb5-config to determine the flags to use
206 to compile with your Kerberos libraries. To specify a particular
207 krb5-config script to use, either set the PATH_KRB5_CONFIG environment
208 variable or pass it to configure like:
210 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
212 If krb5-config isn't found, configure will look for the standard
213 Kerberos libraries in locations already searched by your compiler. If
214 the the krb5-config script first in your path is not the one
215 corresponding to the Kerberos libraries you want to use, or if your
216 Kerberos libraries and includes aren't in a location searched by default
217 by your compiler, you need to specify a different Kerberos installation
218 root via --with-krb5=PATH. For example:
220 ./configure --with-krb5=/usr/pubsw
222 You can also individually set the paths to the include directory and the
223 library directory with --with-krb5-include and --with-krb5-lib. You may
224 need to do this if Autoconf can't figure out whether to use lib, lib32,
225 or lib64 on your platform.
227 To not use krb5-config and force library probing even if there is a
228 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
231 ./configure PATH_KRB5_CONFIG=/nonexistent
233 krb5-config is not used and library probing is always done if either
234 --with-krb5-include or --with-krb5-lib are given.
236 Pass --enable-silent-rules to configure for a quieter build (similar to
237 the Linux kernel). Use make warnings instead of make to build with full
238 GCC compiler warnings (requires a relatively current version of GCC).
240 You can pass the --enable-reduced-depends flag to configure to try to
241 minimize the shared library dependencies encoded in the binaries. This
242 omits from the link line all the libraries included solely because other
243 libraries depend on them and instead links the programs only against
244 libraries whose APIs are called directly. This will only work with
245 shared libraries and will only work on platforms where shared libraries
246 properly encode their own dependencies (this includes most modern
247 platforms such as all Linux). It is intended primarily for building
248 packages for Linux distributions to avoid encoding unnecessary shared
249 library dependencies that make shared library migrations more difficult.
250 If none of the above made any sense to you, don't bother with this flag.
252 After installing this software, see the man pages for krb5-strength,
253 heimdal-strength, and heimdal-history for configuration information.
257 krb5-strength comes with a test suite, which you can run after building
262 If a test fails, you can run a single test with verbose output via:
264 tests/runtests -o <name-of-test>
266 Do this instead of running the test program directly since it will
267 ensure that necessary environment variables are set up.
271 The krb5-strength web page at:
273 https://www.eyrie.org/~eagle/software/krb5-strength/
275 will always have the current version of this package, the current
276 documentation, and pointers to any additional resources.
278 For bug tracking, use the issue tracker on GitHub:
280 https://github.com/rra/krb5-strength/issues
282 However, please be aware that I tend to be extremely busy and work
283 projects often take priority. I'll save your report and get to it as
284 soon as I can, but it may take me a couple of months.
288 krb5-strength is maintained using Git. You can access the current
291 https://github.com/rra/krb5-strength
293 or by cloning the repository at:
295 https://git.eyrie.org/git/kerberos/krb5-strength.git
297 or view the repository via the web at:
299 https://git.eyrie.org/?p=kerberos/krb5-strength.git
301 The eyrie.org repository is the canonical one, maintained by the author,
302 but using GitHub is probably more convenient for most purposes. Pull
303 requests are gratefully reviewed and normally accepted.
307 The krb5-strength package as a whole is covered by the following
308 copyright statement and license:
310 Copyright 2016 Russ Allbery <eagle@eyrie.org>
311 Copyright 2006-2007, 2009-2010, 2012-2014
312 The Board of Trustees of the Leland Stanford Junior University
313 Copyright 1993 Alec Muffett
315 Permission is hereby granted, free of charge, to any person obtaining
316 a copy of this software and associated documentation files (the
317 "Software"), to deal in the Software without restriction, including
318 without limitation the rights to use, copy, modify, merge, publish,
319 distribute, sublicense, and/or sell copies of the Software, and to
320 permit persons to whom the Software is furnished to do so, subject to
321 the following conditions:
323 The above copyright notice and this permission notice shall be
324 included in all copies or substantial portions of the Software.
326 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
327 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
328 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
329 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
330 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
331 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
332 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
334 Developed by Derrick Brashear and Ken Hornstein of Sine Nomine
335 Associates, on behalf of Stanford University.
337 The embedded version of CrackLib (all files in the cracklib
338 subdirectory) is covered by the Artistic license. See the file
339 cracklib/LICENCE for more information. Combined derivative works that
340 include this code, such as binaries built with the embedded CrackLib,
341 will need to follow the terms of the Artistic license as well as the
344 Some files in this distribution are individually released under
345 different licenses, all of which are compatible with the above general
346 package license but which may require preservation of additional
347 notices. All required notices, and detailed information about the
348 licensing of each file, are recorded in the LICENSE file.
350 For any copyright range specified by files in this package as YYYY-ZZZZ,
351 the range specifies every single year in that closed interval.