2 (Kerberos password strength checking plugin)
3 Maintained by Russ Allbery <eagle@eyrie.org>
5 Copyright 2016, 2020 Russ Allbery <eagle@eyrie.org>. Copyright
6 2006-2007, 2009-2010, 2012-2014 The Board of Trustees of the Leland
7 Stanford Junior University. Copyright 1993 Alec Muffett. This software
8 is distributed under a BSD-style license. Please see the section
9 LICENSE below for more information.
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 7.0.
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.010 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 bootstrap from a Git checkout, or if you change the Automake files
139 and need to regenerate Makefile.in, you will need Automake 1.11 or
140 later. For bootstrap or if you change configure.ac or any of the m4
141 files it includes and need to regenerate configure or config.h.in, you
142 will need Autoconf 2.64 or later. You will also need Perl 5.010 or
143 later and the DBI, DBD::SQLite, JSON, Perl6::Slurp, and Readonly modules
144 (from CPAN) to generate man pages and bootstrap the test suite data from
147 BUILDING AND INSTALLATION
149 You can build and install krb5-strength with the standard commands:
155 If you are building from a Git clone, first run ./bootstrap in the
156 source directory to generate the build files. make install will
157 probably have to be done as root. Building outside of the source
158 directory is also supported, if you wish, by creating an empty directory
159 and then running configure with the correct relative path.
161 By default, the Heimdal external password check function is installed as
162 /usr/local/bin/heimdal-strength, and the plugin is installed as
163 /usr/local/lib/krb5/plugins/pwqual/strength.so. You can change these
164 paths with the --prefix, --libdir, and --bindir options to configure.
166 By default, the embedded version of CrackLib will be used. To build
167 with the system version of CrackLib, pass --with-cracklib to configure.
168 You can optionally add a directory, giving the root directory where
169 CrackLib was installed, or separately set the include and library path
170 with --with-cracklib-include and --with-cracklib-lib. You can also
171 build without any CrackLib support by passing --without-cracklib to
174 krb5-strength will automatically build with TinyCDB if it is found. To
175 specify the installation path of TinyCDB, use --with-tinycdb. You can
176 also separately set the include and library path with
177 --with-tinycdb-include and --with-tinycdb-lib.
179 Similarly, krb5-strength will automatically build with SQLite if it is
180 found. To specify the installation path of SQLite, use --with-sqlite.
181 You can also separately set the include and library path with
182 --with-sqlite-include and --with-sqlite-lib.
184 Normally, configure will use krb5-config to determine the flags to use
185 to compile with your Kerberos libraries. To specify a particular
186 krb5-config script to use, either set the PATH_KRB5_CONFIG environment
187 variable or pass it to configure like:
189 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
191 If krb5-config isn't found, configure will look for the standard
192 Kerberos libraries in locations already searched by your compiler. If
193 the the krb5-config script first in your path is not the one
194 corresponding to the Kerberos libraries you want to use, or if your
195 Kerberos libraries and includes aren't in a location searched by default
196 by your compiler, you need to specify a different Kerberos installation
197 root via --with-krb5=PATH. For example:
199 ./configure --with-krb5=/usr/pubsw
201 You can also individually set the paths to the include directory and the
202 library directory with --with-krb5-include and --with-krb5-lib. You may
203 need to do this if Autoconf can't figure out whether to use lib, lib32,
204 or lib64 on your platform.
206 To not use krb5-config and force library probing even if there is a
207 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
210 ./configure PATH_KRB5_CONFIG=/nonexistent
212 krb5-config is not used and library probing is always done if either
213 --with-krb5-include or --with-krb5-lib are given.
215 Pass --enable-silent-rules to configure for a quieter build (similar to
216 the Linux kernel). Use make warnings instead of make to build with full
217 compiler warnings (requires either GCC or Clang and may require a
218 relatively current version of the compiler).
220 You can pass the --enable-reduced-depends flag to configure to try to
221 minimize the shared library dependencies encoded in the binaries. This
222 omits from the link line all the libraries included solely because other
223 libraries depend on them and instead links the programs only against
224 libraries whose APIs are called directly. This will only work with
225 shared libraries and will only work on platforms where shared libraries
226 properly encode their own dependencies (this includes most modern
227 platforms such as all Linux). It is intended primarily for building
228 packages for Linux distributions to avoid encoding unnecessary shared
229 library dependencies that make shared library migrations more difficult.
230 If none of the above made any sense to you, don't bother with this flag.
232 After installing this software, see the man pages for krb5-strength,
233 heimdal-strength, and heimdal-history for configuration information.
237 krb5-strength comes with a test suite, which you can run after building
242 If a test fails, you can run a single test with verbose output via:
244 tests/runtests -o <name-of-test>
246 Do this instead of running the test program directly since it will
247 ensure that necessary environment variables are set up.
249 To run the test suite, you will need Perl 5.010 or later and the
250 dependencies of the heimdal-history program. The following additional
251 Perl modules will also be used by the test suite if present:
254 * Test::MinimumVersion
260 All are available on CPAN. Some tests will be skipped if the modules
263 To enable tests that don't detect functionality problems but are used to
264 sanity-check the release, set the environment variable RELEASE_TESTING
265 to a true value. To enable tests that may be sensitive to the local
266 environment or that produce a lot of false positives without uncovering
267 many problems, set the environment variable AUTHOR_TESTING to a true
272 The krb5-strength web page at:
274 https://www.eyrie.org/~eagle/software/krb5-strength/
276 will always have the current version of this package, the current
277 documentation, and pointers to any additional resources.
279 For bug tracking, use the issue tracker on GitHub:
281 https://github.com/rra/krb5-strength/issues
283 However, please be aware that I tend to be extremely busy and work
284 projects often take priority. I'll save your report and get to it as
285 soon as I can, but it may take me a couple of months.
289 krb5-strength is maintained using Git. You can access the current
292 https://github.com/rra/krb5-strength
294 or by cloning the repository at:
296 https://git.eyrie.org/git/kerberos/krb5-strength.git
298 or view the repository via the web at:
300 https://git.eyrie.org/?p=kerberos/krb5-strength.git
302 The eyrie.org repository is the canonical one, maintained by the author,
303 but using GitHub is probably more convenient for most purposes. Pull
304 requests are gratefully reviewed and normally accepted.
308 The krb5-strength package as a whole is covered by the following
309 copyright statement and license:
311 Copyright 2016, 2020 Russ Allbery <eagle@eyrie.org>
312 Copyright 2006-2007, 2009-2010, 2012-2014
313 The Board of Trustees of the Leland Stanford Junior University
314 Copyright 1993 Alec Muffett
316 Permission is hereby granted, free of charge, to any person obtaining
317 a copy of this software and associated documentation files (the
318 "Software"), to deal in the Software without restriction, including
319 without limitation the rights to use, copy, modify, merge, publish,
320 distribute, sublicense, and/or sell copies of the Software, and to
321 permit persons to whom the Software is furnished to do so, subject to
322 the following conditions:
324 The above copyright notice and this permission notice shall be
325 included in all copies or substantial portions of the Software.
327 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
328 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
329 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
330 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
331 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
332 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
333 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
335 Developed by Derrick Brashear and Ken Hornstein of Sine Nomine
336 Associates, on behalf of Stanford University.
338 The embedded version of CrackLib (all files in the cracklib
339 subdirectory) is covered by the Artistic license. See the file
340 cracklib/LICENCE for more information. Combined derivative works that
341 include this code, such as binaries built with the embedded CrackLib,
342 will need to follow the terms of the Artistic license as well as the
345 Some files in this distribution are individually released under
346 different licenses, all of which are compatible with the above general
347 package license but which may require preservation of additional
348 notices. All required notices, and detailed information about the
349 licensing of each file, are recorded in the LICENSE file.
351 Files covered by a license with an assigned SPDX License Identifier
352 include SPDX-License-Identifier tags to enable automated processing of
353 license information. See https://spdx.org/licenses/ for more
356 For any copyright range specified by files in this package as YYYY-ZZZZ,
357 the range specifies every single year in that closed interval.