- krb5-strength 0.5
- (kadmind password strength checking plugin)
+ krb5-strength 2.1
+ (Kerberos password strength checking plugin)
- Maintained by Russ Allbery <rra@stanford.edu>
+ Maintained by Russ Allbery <eagle@eyrie.org>
- Copyright 2006, 2007 Board of Trustees, Leland Stanford Jr. University.
- Portions copyright 1993 Alec Muffett. Developed by Derrick Brashear and
- Ken Hornstein of Sine Nomine Associates, on behalf of Stanford
- University.
-
- This software is distributed under a BSD-style license and under the
- Artistic License. Please see the section LICENSE for more information.
-
- This should be considered beta-quality code. It is not currently
- running anywhere in production. Feedback and improvements will be
- gratefully accepted.
+ Copyright 2006, 2007, 2009, 2010, 2012, 2013 The Board of Trustees of
+ the Leland Stanford Junior University. Portions copyright 1993 Alec
+ Muffett. Developed by Derrick Brashear and Ken Hornstein of Sine Nomine
+ Associates, on behalf of Stanford University. This software is
+ distributed under a BSD-style license and under the Artistic License.
+ Please see the section LICENSE for more information.
BLURB
- krb5-strength is a toolkit for checking the strength of passwords
- against an external dictionary, applying more transforms and checks than
- kadmind supports by default. It is implemented as a patch to kadmind
- and a plugin module that is called on each password change. It embeds a
- slightly modified copy of Alec Muffett's CrackLib to do the password
- checking.
+ krb5-strength provides a password quality plugin for the MIT Kerberos
+ KDC (specifically the kadmind server) and an external password quality
+ program for use with the Heimdal kpasswdd server. Passwords can be
+ tested with CrackLib, checked against a CDB database of known weak
+ passwords, checked for length, checked for non-printable or non-ASCII
+ characters that may be difficult to enter reproducibly, required to
+ contain particular character classes, or any combination of these tests.
+ It supports both Heimdal and MIT Kerberos (1.9 or later).
DESCRIPTION
- The MIT kadmind supports password strength checking against a dictionary
- out of the box. Unfortunately, that support loads the entire dictionary
- into memory, requires uncompressed dictionaries, and doesn't apply any
- transformations to the password before checking it against the
- dictionary. CrackLib provides more sophisticated strength checking and
- an optimized, compressed on-disk database format. This toolkit provides
- a way to check the strength of Kerberos passwords using CrackLib before
- allowing them.
-
- This toolkit consists of two pieces:
-
- * A patch to MIT Kerberos to add a plugin system for password strength
- checking. This patch adds initialization and shutdown hooks plus a
- hook that's run prior to each password change. The code in kadmind
- is independent of what the plugin might do.
-
- * A kadmind plugin that is a simple wrapper around the CrackLib
- password checking call. Included in this toolkit is a slightly
- modified version of CrackLib.
-
- Currently, the embedded CrackLib is built unconditionally. In a future
- release, I hope to add support for building against an already-installed
- CrackLib if so desired.
+ Heimdal includes a capability to plug in external password quality
+ checks and comes with an example that checks passwords against CrackLib.
+ However, in testing at Stanford, we found that CrackLib with its default
+ transform rules does not catch passwords that can be guessed using the
+ same dictionary with other tools, such as Jack the Ripper. We then
+ discovered other issues with CrackLib with longer passwords, such as
+ some bad assumptions about how certain measures of complexity will
+ scale, and wanted to impose other limitations that it didn't support.
+
+ This plugin provides the ability to check password quality against the
+ standard version of CrackLib, or against a modified version of CrackLib
+ that only passes passwords that resist attacks from both Crack and Jack
+ the Ripper using the same rule sets. It also supports doing simpler
+ dictionary checks against a CDB database, which is fast with very large
+ dictionaries, and imposing other programmatic checks on passwords such
+ as character class requirements.
+
+ For Heimdal, it includes both a program usable as an external password
+ quality check and a plugin that implements the dynamic module API. For
+ MIT Kerberos (1.9 or later), it includes a plugin for the password
+ quality (pwqual) plugin API.
+
+ krb5-strength can be built with either the system CrackLib or with the
+ modified version of CrackLib included in this package. Note, however,
+ that if you're building against the system CrackLib, Heimdal includes in
+ the distribution a strength-checking plugin and an external password
+ check program that use the system CrackLib. With Heimdal, it would
+ probably be easier to use that plugin or program than build this package
+ unless you want the modified CrackLib.
For information about the changes to the CrackLib included in this
- toolkit, see cracklib/HISTORY. They are minor changes to tighten the
- rules in some places, be stricter with longer passwords, fix portability
- issues, and remove some code that doesn't make sense in the kadmind
- context.
-
- Future versions of MIT Kerberos are expected to provide an improved
- plugin interface for this sort of check that is not compatible with the
- one added by this patch. As soon as that interface is available, this
- package will be updated to work with it.
+ toolkit, see cracklib/HISTORY. The primary changes are tighter rules,
+ which are more aggressive at finding dictionary words with characters
+ appended and prepended, which tighten the requirements for password
+ entropy, and which add stricter rules for longer passwords. They are
+ also minor changes to fix portability issues and remove some code that
+ doesn't make sense in the kadmind context.
+
+ Ideally, the changes to CrackLib should be added to the standard
+ CrackLib distribution by adding an additional interface to configure its
+ behavior, at which point this package can likely wither away in favor of
+ much simpler plugins that link to the standard CrackLib library.
REQUIREMENTS
- To use this plugin, you will need to apply the patch in the patches
- directory to MIT Kerberos and rebuild. Due to how kadmind is
- constructed, the changes are actually in the libkadm5srv library, not in
- the kadmind binary, so you'll need to install the modified libraries.
-
- For this module to be effective, you will also need to construct a
- dictionary. The mkdict and packer utilities to build a CrackLib
- dictionary from a word list are included in this toolkit but not
- installed by default. You can run them out of the cracklib directory
- after building. You can also use the utilities that come with the stock
- CrackLib package (often already packaged in a Linux distribution).
+ For Heimdal, you may use either the external password quality check
+ tool, installed as heimdal-strength, or the plugin as you choose. It
+ has been tested with Heimdal 1.2.1 and later, but has not recently been
+ tested with versions prior to 1.5.
+
+ For MIT Kerberos, version 1.9 or higher is required for the password
+ quality plugin interface. MIT Kerberos does not support an external
+ password quality check tool directly, so you will need to install the
+ plugin.
+
+ You can optionally build against the system CrackLib library. Any
+ version should be supported, but note that some versions, particularly
+ older versions close to the original code, do things like printing
+ diagnostics to stderr, calling exit, and otherwise not being
+ well-behaved for use inside plugins or libraries. If using a system
+ CrackLib library, use version 2.8.22 or later to avoid these problems.
+
+ You can also optionally build against the TinyCDB library, which
+ provides support for simpler and faster password checking against a CDB
+ dictionary file.
+
+ For this module to be effective for either Heimdal or MIT Kerberos, you
+ will also need to construct a dictionary. The mkdict and packer
+ utilities to build a CrackLib dictionary from a word list are included
+ in this toolkit but not installed by default. You can run them out of
+ the cracklib directory after building. You can also use the utilities
+ that come with the stock CrackLib package (often already packaged in a
+ Linux distribution); the database format is compatible.
+
+ For building a CDB dictionary, use the provided cdbmake-wordlist
+ program. The CDB utility must be on your PATH. cdbmake-wordlist
+ requires Perl 5.006 or later.
For a word list to use as source for the dictionary, you can use
/usr/share/dict/words if it's available on your system, but it would be
- better to find a more comprehensive word list (or even better, find
- every word list you can locate on the Internet and combine them). Since
- word lists are bulky, often covered by murky copyrights, and easily
- locatable on the Internet with a modicum of searching, none are included
- in this toolkit.
+ better to find a more comprehensive word list. Since word lists are
+ bulky, often covered by murky copyrights, and easily locatable on the
+ Internet with a modicum of searching, none are included in this toolkit.
+
+ To run the test suite, you will also need Perl 5.006 or later. The
+ following additional Perl modules will be used by the test suite if
+ present:
+
+ IPC::Run
+ JSON
+ Perl6::Slurp
+ Test::MinimumVersion
+ Test::Perl::Critic
+ Test::Pod
+ Test::Spelling
+ Test::Strict
+
+ All are available on CPAN. Those tests will be skipped if the modules
+ are not available.
+
+ To enable tests that may be sensitive to the local environment or that
+ produce a lot of false positives without uncovering many problems, set
+ RRA_MAINTAINER_TESTS to a true value.
+
+ To bootstrap from a Git checkout, or If you change the Automake files
+ and need to regenerate Makefile.in, you will need Automake 1.11 or
+ later. For bootstrap or if you change configure.ac or any of the m4
+ files it includes and need to regenerate configure or config.h.in, you
+ will need Autoconf 2.64 or later. You will also need Perl 5.010 or
+ later and the JSON, Perl6::Slurp, and Readonly modules (from CPAN) to
+ bootstrap the test suite data from a Git checkout.
COMPILING AND INSTALLING
- First, patch MIT Kerberos with the patch provided in the patches
- directory and install the new libkadm5srv library. See patches/README
- for more information about the patch. If you're using a different
- version of MIT Kerberos, you may need to adjust the patch accordingly.
-
- Then, you can build and install the plugin with the standard commands:
+ You can build and install the plugin with the standard commands:
./configure
make
make install
+ Pass --enable-silent-rules to configure for a quieter build (similar to
+ the Linux kernel). Use make warnings instead of make to build with full
+ GCC compiler warnings (requires a relatively current version of GCC).
+
The last step will probably have to be done as root. By default, the
- plugin is installed as /usr/local/lib/kadmind/passwd_strength.so. You
- can change this path with the --prefix and --libdir options to
- configure.
+ plugin is installed as /usr/local/lib/krb5/plugins/pwqual/strength.so
+ and the Heimdal external password check function is installed as
+ /usr/local/bin/heimdal-strength. You can change these paths with the
+ --prefix, --libdir, and --bindir options to configure.
+
+ To build with the system version of CrackLib, pass --with-cracklib to
+ configure. You can optionally add a directory, giving the root
+ directory where CrackLib was installed, or separately set the include
+ and library path with --with-cracklib-include and --with-cracklib-lib.
+
+ krb5-strength will automatically build with TinyCDB if it is found. To
+ specify the installation path of TinyCDB, use --with-tinycdb. You can
+ also separately set the include and library path with
+ --with-tinycdb-include and --with-tinycdb-lib.
+
+ Normally, configure will use krb5-config to determine the flags to use
+ to compile with your Kerberos libraries. If krb5-config isn't found, it
+ will look for the standard Kerberos libraries in locations already
+ searched by your compiler. If the the krb5-config script first in your
+ path is not the one corresponding to the Kerberos libraries you want to
+ use or if your Kerberos libraries and includes aren't in a location
+ searched by default by your compiler, you need to specify a different
+ Kerberos installation root via --with-krb5=PATH. For example:
+
+ ./configure --with-krb5=/usr/pubsw
+
+ You can also individually set the paths to the include directory and the
+ library directory with --with-krb5-include and --with-krb5-lib. You may
+ need to do this if Autoconf can't figure out whether to use lib, lib32,
+ or lib64 on your platform.
+
+ To specify a particular krb5-config script to use, either set the
+ PATH_KRB5_CONFIG environment variable or pass it to configure like:
+
+ ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
+
+ To not use krb5-config and force library probing even if there is a
+ krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
+ path:
+
+ ./configure PATH_KRB5_CONFIG=/nonexistent
+
+ krb5-config is not used and library probing is always done if either
+ --with-krb5-include or --with-krb5-lib are given.
+
+ You can pass the --enable-reduced-depends flag to configure to try to
+ minimize the shared library dependencies encoded in the binaries. This
+ omits from the link line all the libraries included solely because the
+ Kerberos libraries depend on them and instead links the programs only
+ against libraries whose APIs are called directly. This will only work
+ with shared Kerberos libraries and will only work on platforms where
+ shared libraries properly encode their own dependencies (such as Linux).
+ It is intended primarily for building packages for Linux distributions
+ to avoid encoding unnecessary shared library dependencies that make
+ shared library migrations more difficult. If none of the above made any
+ sense to you, don't bother with this flag.
CONFIGURATION
- First, build and install a CrackLib dictionary as described above. This
- dictionary will consist of three files, one each ending in *.hwm, *.pwd,
- and *.pwi. Install those files somewhere on your system.
-
- In the [realms] section of your kdc.conf, under the appropriate realm or
- realms, specify the path to the dictionary:
+ First, build and install either a CrackLib dictionary as described in
+ REQUIREMENTS above, or build a CDB dictionary with cdbmake-wordlist.
+ (Or both.) The CrackLib dictionary will consist of three files, one
+ each ending in *.hwm, *.pwd, and *.pwi. The CDB dictionary will consist
+ of a single file ending in *.cdb. Install those files somewhere on your
+ system. Then, follow the relevant instructions below for either Heimdal
+ or MIT Kerberos.
+
+ See "Other Settings" below for additional krb5.conf setting supported by
+ both Heimdal and MIT Kerberos.
+
+ Heimdal
+
+ There are two options: using an external password check program, or
+ using the plugin. I recommend the external password check program
+ unless you encounter speed problems with that approach that cause
+ kpasswd to time out.
+
+ For either approach, first add a stanza like the following to the
+ [appdefaults] section of your /etc/krb5.conf (or wherever your krb5.conf
+ file is located):
+
+ krb5-strength = {
+ password_dictionary = /path/to/cracklib/dictionary
+ password_dictionary_cdb = /path/to/cdb/dictionary.cdb
+ }
+
+ The first setting configures a CrackLib dictionary and the second a CDB
+ dictionary. The provided path should be the full path to the dictionary
+ files, omitting the trailing *.hwm, *.pwd, and *.pwi extensions for the
+ CrackLib dictionary. You can use either or both settings. If you use
+ both, CrackLib will be checked first, and then CDB. When checking a CDB
+ database, the password, the password with the first character removed,
+ the last character removed, the first and last characters removed, the
+ first two characters removed, and the last two characters removed will
+ all be checked against the dictionary.
+
+ Then, for the external password checking program, add a new section (or
+ modify the existing [password_quality] section) to look like the
+ following:
+
+ [password_quality]
+ policies = external-check
+ external_program = /usr/local/bin/heimdal-strength
+
+ You can, of course, combine this policy with others. Replace the path
+ with the full path to wherever you have installed heimdal-strength. You
+ can put this section in your kdc.conf instead of krb5.conf if you
+ prefer.
+
+ If you want to instead use the module, use the following section
+ instead:
+
+ [password_quality]
+ policies = krb5-strength
+ policy_libraries = /usr/local/lib/krb5/plugins/pwqual/strength.so
+
+ in either krb5.conf or kdc.conf. Note that some older versions of
+ Heimdal have a bug in the support for loading modules when
+ policy_libraries is set. If you get an error like:
+
+ didn't find `kadm5_password_verifier' symbol in `(null)'
+
+ you may have to omit policy_libraries in your configuration and instead
+ pass the --check-library argument to kpasswdd specifying the library to
+ load.
+
+ MIT Kerberos
+
+ To add this module to the list of password quality checks, add a section
+ to krb5.conf (or to a separate kdc.conf if you use that) like:
+
+ [plugins]
+ pwqual = {
+ module = strength:/usr/local/lib/krb5/plugins/pwqual/strength.so
+ }
+
+ to register the plugin.
+
+ There are two ways to tell where the dictionary is. One option is to
+ use krb5.conf (and in this case you must use krb5.conf, even if you use
+ a separate kdc.conf file). For this approach, add the following to the
+ [appdefaults] section:
+
+ krb5-strength = {
+ password_dictionary = /path/to/cracklib/dictionary
+ password_dictionary_cdb = /path/to/cdb/dictionary.cdb
+ }
+
+ The first setting configures a CrackLib dictionary and the second a CDB
+ dictionary. The provided path should be the full path to the dictionary
+ files, omitting the trailing *.hwm, *.pwd, and *.pwi extensions for the
+ CrackLib dictionary. You can use either or both settings. If you use
+ both, CrackLib will be checked first, and then CDB. When checking a CDB
+ database, the password, the password with the first character removed,
+ the last character removed, the first and last characters removed, the
+ first two characters removed, and the last two characters removed will
+ all be checked against the dictionary.
+
+ The second option is to use the normal dict_path setting. In the
+ [realms] section of your krb5.conf kdc.conf, under the appropriate realm
+ or realms, specify the path to the dictionary:
dict_file = /path/to/cracklib/dictionary
- The provided path should be the full path to the dictionary files,
- omitting the trailing *.hwm, *.pwd, or *.pwi extension. Then, specify
- the path to the plugin by adding:
-
- pwcheck_plugin = /usr/local/lib/kadmind/passwd_strength.so
-
- to the same section of the kdc.conf, giving the correct full path to the
- plugin. Restart kadmind and password strength checking should be
- enabled.
-
- Be aware that password strength checking is only applied to principals
- with a policy set. If you want to check all user passwords, assign all
- user principals a password policy. (Similarly, you can avoid checking
- the strength of passwords for particular principals by clearing their
- policy.) Also be aware that enabling this plugin will disable the
- normal kadmind dictionary check. There currently is no way to have them
- both enabled at the same time.
-
- Finally, note that the default rules of this plugin will reject the
- temporary password used by addprinc -randkey or ktadd -randkey when
- initializing a principal. When generating service principals using that
- flag, you will need to pass in the -clearpolicy flag as well to avoid
- rejecting the initial temporary password. You can then add a policy
- later with modprinc if desired.
+ This will be taken as a CrackLib dictionary path, the same as the
+ setting for password_dictionary above. The provided path should be the
+ full path to the dictionary files, omitting the trailing *.hwm, *.pwd,
+ or *.pwi extension. However, be aware that, if you use this approach,
+ you will probably want to disable the built-in standard dict pwqual
+ plugin by adding the line:
+
+ disable = dict
+
+ to the pwqual block of the [plugins] section as shown above. Otherwise,
+ it will also try to load a dictionary at the same path to do simple
+ dictionary matching.
+
+ You can also mix and match these settings, by using dict_path for the
+ CrackLib dictionary path and krb5.conf for the CDB dictionary path. If
+ both settings are used, krb5.conf overrides the dict_path setting (so
+ that dict_path can be used for other password quality modules). There
+ is no way to specify a CDB dictionary via the dict_path setting.
+
+ Other Settings
+
+ The following additional settings are supported in the [appdefaults]
+ section of krb5.conf when running under either Heimdal or MIT Kerberos.
+
+ minimum_length
+
+ If set to a numeric value, passwords with fewer than that number of
+ characters will be rejected, independent of any length restrictions
+ in CrackLib. Note that this setting does not bypass the minimum
+ length requirements in CrackLib itself (which, for the version
+ embedded in this package, is eight characters).
+
+ require_ascii_printable
+
+ If set to a true boolean value, rejects any password that contains
+ non-ASCII characters or ASCII control characters. Spaces are
+ allowed; tabs are not (at least assuming the POSIX C locale). No
+ canonicalization or character set is defined for Kerberos passwords
+ in general, so you may want to reject non-ASCII characters to avoid
+ interoperability problems with computers with different default
+ character sets or Unicode normalization forms.
+
+ require_classes
+
+ This option allows specification of more complex character class
+ requirements. The value of this parameter should be one or more
+ whitespace-separated rule. Each rule has the syntax:
+
+ [<min>-<max>:]<class>[,<class>...]
+
+ where <class> is one of "upper", "lower", "digit", or "symbol"
+ (without the quote marks). The symbol class includes all characters
+ other than alphanumeric characters, including space. The listed
+ classes must appear in the password. Separate multiple required
+ classes with a comma (and no space).
+
+ The character class checks will be done in whatever locale the
+ plugin or password check program is run in, which will normally be
+ the POSIX C locale but may be different depending on local
+ configuration.
+
+ A simple example:
+
+ require_classes = upper,lower,digit
+
+ This requires all passwords contain at least one uppercase letter,
+ at least one lowercase letter, and at least one digit.
+
+ If present, <min> and <max> specify the minimum password length and
+ maximum password length to which this rule applies. This allows one
+ to specify character class requirements that change with password
+ length. So, for example:
+
+ require_classes = 8-19:upper,lower 8-15:digit 8-11:symbol
+
+ requires all passwords from 8 to 11 characters long contain all four
+ character classes, passwords from 12 to 15 characters long contain
+ upper and lower case and a digit, and passwords from 16 to 19
+ characters long contain both upper and lower case. Passowrds longer
+ than 20 characters have no character class restrictions. (This
+ example is probably used in conjunction with minimum_length = 8.)
+
+ require_non_letter
+
+ If set to a true boolean value, the password must contain at least
+ one character that is not a letter (uppercase or lowercase) or a
+ space. This may be helpful in combination with passphrases; users
+ may choose a stock English phrase, and this will force at least some
+ additional complexity.
+
+ You can omit any dictionary setting and only use the above settings, in
+ which case only the above checks and checks for passwords based on the
+ principal will be done, bypassing any dictionary check. (But for that
+ simple style of password strength checking, there are probably better
+ strength checking plugins already available.)
+
+SUPPORT
+
+ The krb5-strength web page at:
+
+ http://www.eyrie.org/~eagle/software/krb5-strength/
+
+ will always have the current version of this package, the current
+ documentation, and pointers to any additional resources.
+
+ I welcome bug reports and patches for this package at eagle@eyrie.org.
+ However, please be aware that I tend to be extremely busy and work
+ projects often take priority. I'll save your mail and get to it as soon
+ as I can, but it may take me a couple of months.
+
+SOURCE REPOSITORY
+
+ krb5-strength is maintained using Git. You can access the current
+ source by cloning the repository at:
+
+ git://git.eyrie.org/kerberos/krb5-strength.git
+
+ or view the repository via the web at:
+
+ http://git.eyrie.org/?p=kerberos/krb5-strength.git
+
+ When contributing modifications, either patches (possibly generated by
+ git format-patch) or Git pull requests are welcome.
+
+LICENSE
+
+ The krb5-strength package as a whole is covered by the following
+ copyright statement and license:
+
+ Copyright 2006, 2007, 2009, 2010, 2012, 2013
+ The Board of Trustees of the Leland Stanford Junior University
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ The embedded version of CrackLib (all files in the cracklib
+ subdirectory) is covered by the Artistic license. See the file
+ cracklib/LICENCE for more information. Combined derivative works that
+ include this code, such as binaries built with the embedded CrackLib,
+ will need to follow the terms of the Artistic license as well as the
+ above license.
+
+ All other individual files without an explicit exception below are
+ released under this license. Some files may have additional copyright
+ holders as noted in those files. There is detailed information about
+ the licensing of each file in the LICENSE file in this distribution.
+
+ Some files in this distribution are individually released under
+ different licenses, all of which are compatible with the above general
+ package license but which may require preservation of additional
+ notices. All required notices are preserved in the LICENSE file.