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.
193 krb5-strength will automatically build with TinyCDB if it is found. To
194 specify the installation path of TinyCDB, use --with-tinycdb. You can
195 also separately set the include and library path with
196 --with-tinycdb-include and --with-tinycdb-lib.
198 Similarly, krb5-strength will automatically build with SQLite if it is
199 found. To specify the installation path of SQLite, use --with-sqlite.
200 You can also separately set the include and library path with
201 --with-sqlite-include and --with-sqlite-lib.
203 Normally, configure will use krb5-config to determine the flags to use
204 to compile with your Kerberos libraries. To specify a particular
205 krb5-config script to use, either set the PATH_KRB5_CONFIG environment
206 variable or pass it to configure like:
208 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
210 If krb5-config isn't found, configure will look for the standard
211 Kerberos libraries in locations already searched by your compiler. If
212 the the krb5-config script first in your path is not the one
213 corresponding to the Kerberos libraries you want to use, or if your
214 Kerberos libraries and includes aren't in a location searched by default
215 by your compiler, you need to specify a different Kerberos installation
216 root via --with-krb5=PATH. For example:
218 ./configure --with-krb5=/usr/pubsw
220 You can also individually set the paths to the include directory and the
221 library directory with --with-krb5-include and --with-krb5-lib. You may
222 need to do this if Autoconf can't figure out whether to use lib, lib32,
223 or lib64 on your platform.
225 To not use krb5-config and force library probing even if there is a
226 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
229 ./configure PATH_KRB5_CONFIG=/nonexistent
231 krb5-config is not used and library probing is always done if either
232 --with-krb5-include or --with-krb5-lib are given.
234 Pass --enable-silent-rules to configure for a quieter build (similar to
235 the Linux kernel). Use make warnings instead of make to build with full
236 GCC compiler warnings (requires a relatively current version of GCC).
238 You can pass the --enable-reduced-depends flag to configure to try to
239 minimize the shared library dependencies encoded in the binaries. This
240 omits from the link line all the libraries included solely because other
241 libraries depend on them and instead links the programs only against
242 libraries whose APIs are called directly. This will only work with
243 shared libraries and will only work on platforms where shared libraries
244 properly encode their own dependencies (this includes most modern
245 platforms such as all Linux). It is intended primarily for building
246 packages for Linux distributions to avoid encoding unnecessary shared
247 library dependencies that make shared library migrations more difficult.
248 If none of the above made any sense to you, don't bother with this flag.
250 After installing this software, see the man pages for krb5-strength,
251 heimdal-strength, and heimdal-history for configuration information.
255 krb5-strength comes with a test suite, which you can run after building
260 If a test fails, you can run a single test with verbose output via:
262 tests/runtests -o <name-of-test>
264 Do this instead of running the test program directly since it will
265 ensure that necessary environment variables are set up.
269 The krb5-strength web page at:
271 https://www.eyrie.org/~eagle/software/krb5-strength/
273 will always have the current version of this package, the current
274 documentation, and pointers to any additional resources.
276 For bug tracking, use the issue tracker on GitHub:
278 https://github.com/rra/krb5-strength/issues
280 However, please be aware that I tend to be extremely busy and work
281 projects often take priority. I'll save your report and get to it as
282 soon as I can, but it may take me a couple of months.
286 krb5-strength is maintained using Git. You can access the current
289 https://github.com/rra/krb5-strength
291 or by cloning the repository at:
293 https://git.eyrie.org/git/kerberos/krb5-strength.git
295 or view the repository via the web at:
297 https://git.eyrie.org/?p=devel/krb5-strength.git
299 The eyrie.org repository is the canonical one, maintained by the author,
300 but using GitHub is probably more convenient for most purposes. Pull
301 requests are gratefully reviewed and normally accepted.
305 The krb5-strength package as a whole is covered by the following
306 copyright statement and license:
308 Copyright 2016 Russ Allbery <eagle@eyrie.org>
309 Copyright 2006-2007, 2009-2010, 2012-2014
310 The Board of Trustees of the Leland Stanford Junior University
311 Copyright 1993 Alec Muffett
313 Permission is hereby granted, free of charge, to any person obtaining
314 a copy of this software and associated documentation files (the
315 "Software"), to deal in the Software without restriction, including
316 without limitation the rights to use, copy, modify, merge, publish,
317 distribute, sublicense, and/or sell copies of the Software, and to
318 permit persons to whom the Software is furnished to do so, subject to
319 the following conditions:
321 The above copyright notice and this permission notice shall be
322 included in all copies or substantial portions of the Software.
324 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
325 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
326 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
327 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
328 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
329 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
330 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
332 Developed by Derrick Brashear and Ken Hornstein of Sine Nomine
333 Associates, on behalf of Stanford University.
335 The embedded version of CrackLib (all files in the cracklib
336 subdirectory) is covered by the Artistic license. See the file
337 cracklib/LICENCE for more information. Combined derivative works that
338 include this code, such as binaries built with the embedded CrackLib,
339 will need to follow the terms of the Artistic license as well as the
342 Some files in this distribution are individually released under
343 different licenses, all of which are compatible with the above general
344 package license but which may require preservation of additional
345 notices. All required notices, and detailed information about the
346 licensing of each file, are recorded in the LICENSE file.
348 For any copyright range specified by files in this package as YYYY-ZZZZ,
349 the range specifies every single year in that closed interval.