X-Git-Url: https://git.eyrie.org/?a=blobdiff_plain;f=README;h=e55709892f2fbd60181dc851398899ce10a7a9b9;hb=a75803f3f923d61218c571df511d7db4ace29891;hp=573a6f8110e705572fa8e69a25feb2dd7e47c532;hpb=685f201f8f9819b777be1e29bde73db4631ecf9d;p=kerberos%2Fkrb5-strength.git diff --git a/README b/README index 573a6f8..e557098 100644 --- a/README +++ b/README @@ -1,165 +1,357 @@ - krb5-strength 0.4 - (kadmind password strength checking plugin) + krb5-strength 3.2 + (Kerberos password strength checking plugin) + Maintained by Russ Allbery - Maintained by Russ Allbery - - 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 2016, 2020 Russ Allbery . Copyright + 2006-2007, 2009-2010, 2012-2014 The Board of Trustees of the Leland + Stanford Junior University. Copyright 1993 Alec Muffett. This software + is distributed under a BSD-style license. Please see the section + LICENSE below 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 Heimdal KDC, an external + password quality program for use with Heimdal, and a per-principal + password history implementation for Heimdal. Passwords can be tested + with CrackLib, checked against a CDB or SQLite database of known weak + passwords with some transformations, 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. 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, or a SQLite database, which can reject all passwords + within edit distance one of a dictionary word. It can also impose other + programmatic checks on passwords such as character class requirements. + + If you're just now starting with password checking, I recommend using + the SQLite database with a large wordlist and minimum password lengths. + We found this produced the best results with the least user frustration. + + For Heimdal, krb5-strength 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, one of the other dictionary + types, or the additional character class and length checks. 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, remove some code that + doesn't make sense in the kadmind context, and close a few security + issues. The standard CrackLib distribution on at least some Linux + distributions now supports an additional interface to configure its + behavior, and krb5-strength should change in the future to use that + interface and drop the embedded copy. + + 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 - 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 7.0. + + 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. They also have known + security vulnerabilities. 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, and the SQLite library (a version new enough to support + the sqlite3_open_v2 API; 3.7 should be more than sufficient), which + provides support for checking whether passwords are within edit distance + one of a dictionary word. + + 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 or SQLite dictionary, use the provided + krb5-strength-wordlist program. For CDB dictionries, the cdb utility + must be on your PATH. For SQLite, the DBI and DBD::SQLite Perl modules + are required. krb5-strength-wordlist requires Perl 5.010 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. + + The password history program, heimdal-history, requires Perl 5.010 or + later plus the following CPAN modules: + + * DB_File::Lock + * Const::Fast + * Crypt::PBKDF2 + * Getopt::Long::Descriptive + * IPC::Run + * JSON::MaybeXS -COMPILING AND INSTALLING + and their dependencies. - 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. + 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 DBI, DBD::SQLite, JSON, Perl6::Slurp, and Readonly modules + (from CPAN) to generate man pages and bootstrap the test suite data from + a Git checkout. - Then, you can build and install the plugin with the standard commands: +BUILDING AND INSTALLATION + + You can build and install krb5-strength with the standard commands: ./configure make make install - 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 + If you are building from a Git clone, first run ./bootstrap in the + source directory to generate the build files. make install will + probably have to be done as root. Building outside of the source + directory is also supported, if you wish, by creating an empty directory + and then running configure with the correct relative path. + + By default, the Heimdal external password check function is installed as + /usr/local/bin/heimdal-strength, and the plugin is installed as + /usr/local/lib/krb5/plugins/pwqual/strength.so. You can change these + paths with the --prefix, --libdir, and --bindir options to configure. + + By default, the embedded version of CrackLib will be used. 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. You can also + build without any CrackLib support by passing --without-cracklib to configure. -CONFIGURATION + 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. + + Similarly, krb5-strength will automatically build with SQLite if it is + found. To specify the installation path of SQLite, use --with-sqlite. + You can also separately set the include and library path with + --with-sqlite-include and --with-sqlite-lib. + + Normally, configure will use krb5-config to determine the flags to use + to compile with your Kerberos libraries. 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 + + If krb5-config isn't found, configure 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 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. + + 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 + compiler warnings (requires either GCC or Clang and may require a + relatively current version of the compiler). + + 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 other + libraries depend on them and instead links the programs only against + libraries whose APIs are called directly. This will only work with + shared libraries and will only work on platforms where shared libraries + properly encode their own dependencies (this includes most modern + platforms such as all 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. + + After installing this software, see the man pages for krb5-strength, + heimdal-strength, and heimdal-history for configuration information. + +TESTING + + krb5-strength comes with a test suite, which you can run after building + with: + + make check + + If a test fails, you can run a single test with verbose output via: + + tests/runtests -o + + Do this instead of running the test program directly since it will + ensure that necessary environment variables are set up. + + 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 also 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. Some tests will be skipped if the modules + are not available. + + To enable tests that don't detect functionality problems but are used to + sanity-check the release, set the environment variable RELEASE_TESTING + to a true value. To enable tests that may be sensitive to the local + environment or that produce a lot of false positives without uncovering + many problems, set the environment variable AUTHOR_TESTING to a true + value. + +SUPPORT + + The krb5-strength web page at: + + https://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. + + For bug tracking, use the issue tracker on GitHub: + + https://github.com/rra/krb5-strength/issues + + However, please be aware that I tend to be extremely busy and work + projects often take priority. I'll save your report and get to it as + soon as I can, but it may take me a couple of months. - 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. +SOURCE REPOSITORY - In the [realms] section of your kdc.conf, under the appropriate realm or - realms, specify the path to the dictionary: + krb5-strength is maintained using Git. You can access the current + source on GitHub at: - dict_file = /path/to/cracklib/dictionary + https://github.com/rra/krb5-strength - 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: + or by cloning the repository at: - pwcheck_plugin = /usr/local/lib/kadmind/passwd_strength.so + https://git.eyrie.org/git/kerberos/krb5-strength.git - 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. + or view the repository via the web at: - 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. + https://git.eyrie.org/?p=kerberos/krb5-strength.git - 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. + The eyrie.org repository is the canonical one, maintained by the author, + but using GitHub is probably more convenient for most purposes. Pull + requests are gratefully reviewed and normally accepted. LICENSE - The packaging, plugin glue, and build system are covered by the - following copyright and license: - - Copyright 2006, 2007 Board of Trustees, Leland Stanford Jr. - University. All rights reserved. - - Permission to use, copy, modify, and distribute this software and its - documentation for any purpose and without fee is hereby granted, - provided that the above copyright notice appear in all copies and that - both that copyright notice and this permission notice appear in - supporting documentation, and that the name of Stanford University not - be used in advertising or publicity pertaining to distribution of the - software without specific, written prior permission. Stanford - University makes no representations about the suitability of this - software for any purpose. It is provided "as is" without express or - implied warranty. - - THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED - WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. - - The version of CrackLib included here, and all modifications made to it - as part of this toolkit, is covered by the Artistic License. For full - license terms, see cracklib/LICENCE. + The krb5-strength package as a whole is covered by the following + copyright statement and license: + + Copyright 2016, 2020 Russ Allbery + Copyright 2006-2007, 2009-2010, 2012-2014 + The Board of Trustees of the Leland Stanford Junior University + Copyright 1993 Alec Muffett + + 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. + + Developed by Daria Phoebe Brashear and Ken Hornstein of Sine Nomine + Associates, on behalf of Stanford University. + + 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. + + 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, and detailed information about the + licensing of each file, are recorded in the LICENSE file. + + Files covered by a license with an assigned SPDX License Identifier + include SPDX-License-Identifier tags to enable automated processing of + license information. See https://spdx.org/licenses/ for more + information. + + For any copyright range specified by files in this package as YYYY-ZZZZ, + the range specifies every single year in that closed interval.