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