+ krb5-strength 2.2
+ (Kerberos password strength checking plugin)
+
+ Maintained by Russ Allbery <eagle@eyrie.org>
+
+ 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 provides a password quality plugin for the MIT Kerberos
+ KDC (specifically the kadmind server), an external password quality
+ program for use with Heimdal, and a password history implementation for
+ use with Heimdal. 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
+
+ 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. 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.
+
+ krb5-strength also includes a password history implementation for
+ Heimdal. This is separate from the password strength implementation but
+ can be stacked with it so that both strength and history checks are
+ performed. This history implementation is available only via the
+ Heimdal external password quality interface. MIT Kerberos includes its
+ own password history implementation.
+
+REQUIREMENTS
+
+ 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. 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.
+
+ The password history program, heimdal-history, requires Perl 5.010 or
+ later plus the following CPAN modules:
+
+ DB_File::Lock
+ Crypt::PBKDF2
+ Getopt::Long::Descriptive
+ IPC::Run
+ JSON
+ Readonly
+
+ and their dependencies.
+
+ To run the test suite, you will need Perl 5.010 or later and the
+ dependencies of the heimdal-history program. The following additional
+ Perl modules will be used by the test suite if present:
+
+ 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
+
+ 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/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 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
+ password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite
+ }
+
+ The first setting configures a CrackLib dictionary, the second a CDB
+ dictionary, and the third a SQLite 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
+ any combination of the three settings. If you use more than one,
+ CrackLib will be checked first, then CDB, and then SQLite as
+ appropriate.
+
+ When checking against 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.
+
+ When checking a SQLite database, the password will be rejected if it is
+ within edit distance one of any word in the dictionary, meaning that the
+ database word can be formed from the password by deleting, adding, or
+ changing a single character.
+
+ 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.
+
+ Additional configuration is required to use the history implementation.
+ Ensure that its dependencies are installed, and then examine the local
+ configuration settings at the top of the heimdal-history program. By
+ default, it requires a _history user and _history group be present on
+ the system, and all history information will be read and written as that
+ user and group. It also requires a nobody user and nogroup group to be
+ present, and all strength checking will be done as that user and group.
+ It uses various files in /var/lib/heimdal-history to store history and
+ statistical information by default, so if using the defaults, create
+ that directory and ensure it is writable by the _history user.
+
+ Once that setup is done, change your [password_quality] configuration
+ to:
+
+ [password_quality]
+ policies = external-check
+ external_program = /usr/local/bin/heimdal-history
+
+ The heimdal-history program will automatically also run heimdal-strength
+ as well, looking for it in /usr/local/bin, /usr/bin, and /bin. Change
+ the PATH setting at the top of the script if you have different
+ requirements. You should continue to configure heimdal-strength as if
+ you were running it directly.
+
+ 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
+ password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite
+ }
+
+ The first setting configures a CrackLib dictionary, the second a CDB
+ dictionary, and the third a SQLite 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
+ any combination of the three settings. If you use more than one,
+ CrackLib will be checked first, then CDB, and then SQLite as
+ appropriate.
+
+ When checking against 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.
+
+ When checking a SQLite database, the password will be rejected if it is
+ within edit distance one of any word in the dictionary, meaning that the
+ database word can be formed from the password by deleting, adding, or
+ changing a single character.
+
+ 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
+
+ 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 or SQLite dictionary
+ paths. If both settings are used for the CrackLib path, 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 or SQLite
+ 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_different
+
+ If set to a numeric value, passwords with fewer than this number of
+ unique characters will be rejected. This can be used to reject, for
+ example, passwords that are long strings of the same character or
+ repetitions of small numbers of characters, which may be too easy to
+ guess.
+
+ 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.