README

   1                             krb5-strength 1.0
   2                (kadmind password strength checking plugin)
   3
   4               Maintained by Russ Allbery <rra@stanford.edu>
   5
   6   Copyright 2006, 2007, 2009, 2010 Board of Trustees, Leland Stanford
   7   Jr. University.  Portions copyright 1993 Alec Muffett.  Developed by
   8   Derrick Brashear and Ken Hornstein of Sine Nomine Associates, on behalf
   9   of Stanford University.
  10
  11   This software is distributed under a BSD-style license and under the
  12   Artistic License.  Please see the section LICENSE for more information.
  13
  14 BLURB
  15
  16   krb5-strength provides mechanisms for checking the strength of Kerberos
  17   passwords against an external dictionary when a user changes passwords
  18   in a Kerberos KDC.  It is roughly equivalent to checking password
  19   strength via CrackLib, except that it embeds a copy of Alec Muffett's
  20   CrackLib that has been modified to perform slightly more strenuous
  21   tests.  It is usable as-is with Heimdal.  With MIT Kerberos, it requires
  22   an included patch to libkadm5srv to support a dynamically loaded
  23   password check module.
  24
  25 DESCRIPTION
  26
  27   Heimdal includes a capability to plug in external password quality
  28   checks and comes with an example that checks passwords against CrackLib.
  29   However, in testing at Stanford, we found that CrackLib with its default
  30   transform rules does not catch passwords that can be guessed using the
  31   same dictionary with other tools, such as Jack the Ripper.
  32
  33   The MIT Kerberos kadmind supports password strength checking against a
  34   dictionary out of the box.  Unfortunately, that support loads the entire
  35   dictionary into memory, requires uncompressed dictionaries, and doesn't
  36   apply any transformations to the password before checking it against the
  37   dictionary.  CrackLib provides more sophisticated strength checking and
  38   an optimized, compressed on-disk database format.
  39
  40   This toolkit therefore provides the ability to check password quality
  41   against a modified version of CrackLib that only passes passwords that
  42   resist attacks from both Crack and Jack the Ripper using the same rule
  43   sets.  For Heimdal, it includes both a program usable as an external
  44   password quality check and a plugin that implements the dynamic module
  45   API.  For MIT Kerberos, it includes two pieces:
  46
  47    * A patch to MIT Kerberos to add a plugin system for password strength
  48      checking.  This patch adds initialization and shutdown hooks plus a
  49      hook that's run prior to each password change.  The code in kadmind
  50      is independent of what the plugin might do.
  51
  52    * A kadmind plugin that provides a wrapper around the included,
  53      slightly modified version of CrackLib.
  54
  55   Currently, the embedded CrackLib is built unconditionally.  In a future
  56   release, I hope to add support for building against an already-installed
  57   CrackLib if so desired (although built that way this package is only
  58   useful for MIT Kerberos, since Heimdal provides a similar facility as an
  59   example in the distribution).
  60
  61   For information about the changes to the CrackLib included in this
  62   toolkit, see cracklib/HISTORY.  They are minor changes to tighten the
  63   rules in some places, be stricter with longer passwords, fix portability
  64   issues, and remove some code that doesn't make sense in the kadmind
  65   context.
  66
  67   My eventual hope is to submit to CrackLib 2.x modifications that allow
  68   the rule set to be configured at runtime, at which point this package
  69   can likely wither away in favor of much simpler plugins that link to the
  70   standard CrackLib library.
  71
  72 REQUIREMENTS
  73
  74   For Heimdal, this package is usable without any special considerations.
  75   You may use either the external password quality check tool, installed
  76   as heimdal-strength, or the plugin as you choose.  It has been tested
  77   with Heimdal 1.2.1 and later.
  78
  79   To use this plugin with MIT Kerberos, you will need to apply the patch
  80   in the patches directory to MIT Kerberos and rebuild.  Due to how
  81   kadmind is constructed, the changes are actually in the libkadm5srv
  82   library, not in the kadmind binary, so you'll need to install the
  83   modified libraries.
  84
  85   For this module to be effective for either Heimdal or MIT Kerberos, you
  86   will also need to construct a dictionary.  The mkdict and packer
  87   utilities to build a CrackLib dictionary from a word list are included
  88   in this toolkit but not installed by default.  You can run them out of
  89   the cracklib directory after building.  You can also use the utilities
  90   that come with the stock CrackLib package (often already packaged in a
  91   Linux distribution); the database format is compatible.
  92
  93   For a word list to use as source for the dictionary, you can use
  94   /usr/share/dict/words if it's available on your system, but it would be
  95   better to find a more comprehensive word list (or even better, find
  96   every word list you can locate on the Internet and combine them).  Since
  97   word lists are bulky, often covered by murky copyrights, and easily
  98   locatable on the Internet with a modicum of searching, none are included
  99   in this toolkit.
 100
 101   To bootstrap from a Git checkout, or If you change the Automake files
 102   and need to regenerate Makefile.in, you will need Automake 1.11 or
 103   later.  For bootstrap or if you change configure.ac or any of the m4
 104   files it includes and need to regenerate configure or config.h.in, you
 105   will need Autoconf 2.64 or later.
 106
 107 COMPILING AND INSTALLING
 108
 109   You can build and install the plugin with the standard commands:
 110
 111       ./configure
 112       make
 113       make install
 114
 115   The last step will probably have to be done as root.  By default, the
 116   plugin is installed as /usr/local/lib/kadmind/passwd_strength.so and the
 117   Heimdal external password check function is installed as
 118   /usr/local/bin/heimdal-strength.  You can change these paths with the
 119   --prefix, --libdir, and --bindir options to configure.
 120
 121   For MIT Kerberos, you also have to apply the patch provided in the
 122   patches directory and install the new libkadm5srv library.  See
 123   patches/README for more information about the patch.  If you're using a
 124   different version of MIT Kerberos, you may need to adjust the patch
 125   accordingly.
 126
 127 CONFIGURATION
 128
 129   First, build and install a CrackLib dictionary as described above.  This
 130   dictionary will consist of three files, one each ending in *.hwm, *.pwd,
 131   and *.pwi.  Install those files somewhere on your system.  Then, follow
 132   the relevant instructions below for either Heimdal or MIT Kerberos.
 133
 134  Heimdal
 135
 136   There are two options: using an external password check program, or
 137   using the plugin.  I recommend the external password check program
 138   unless you encounter speed problems with that approach that cause
 139   kpasswd to time out.
 140
 141   For either approach, first add a stanza like the following to the
 142   [appdefaults] section of your /etc/krb5.conf (or wherever your krb5.conf
 143   file is located):
 144
 145       krb5-strength = {
 146           password_dictionary = /usr/local/lib/kadmind/dictionary
 147       }
 148
 149   The provided path should be the full path to the dictionary files,
 150   omitting the trailing *.hwm, *.pwd, and *.pwi extensions.
 151
 152   Then, for the external password checking program, add a new section (or
 153   modify the existing [password_quality] section) to look like the
 154   following:
 155
 156       [password_quality]
 157           policies         = external-check
 158           external_program = /usr/local/bin/heimdal-strength
 159
 160   You can, of course, combine this policy with others.  Replace the path
 161   with the full path to wherever you have installed heimdal-strength.  You
 162   can put this section in your kdc.conf instead of krb5.conf if you
 163   prefer.
 164
 165   If you want to instead use the module, use the following section
 166   instead:
 167
 168       [password_quality]
 169           policies         = krb5-strength
 170           policy_libraries = /usr/local/lib/kadmind/passwd_strength.so
 171
 172   in either krb5.conf or kdc.conf.  Note that some versions of Heimdal
 173   have a bug in the support for loading modules when policy_libraries is
 174   set.  If you get an error like:
 175
 176       didn't find `kadm5_password_verifier' symbol in `(null)'
 177
 178   you may have to omit policy_libraries in your configuration and instead
 179   pass the --check-library argument to kpasswdd specifying the library to
 180   load.
 181
 182  MIT Kerberos
 183
 184   In the [realms] section of your kdc.conf, under the appropriate realm or
 185   realms, specify the path to the dictionary:
 186
 187       dict_file = /path/to/cracklib/dictionary
 188
 189   The provided path should be the full path to the dictionary files,
 190   omitting the trailing *.hwm, *.pwd, or *.pwi extension.  Then, specify
 191   the path to the plugin by adding:
 192
 193       pwcheck_plugin = /usr/local/lib/kadmind/passwd_strength.so
 194
 195   to the same section of the kdc.conf, giving the correct full path to the
 196   plugin.  Restart kadmind and password strength checking should be
 197   enabled.
 198
 199   Be aware that, for MIT Kerberos, password strength checking is only
 200   applied to principals with a policy set.  If you want to check all user
 201   passwords, assign all user principals a password policy.  (Similarly,
 202   you can avoid checking the strength of passwords for particular
 203   principals by clearing their policy.)  Also be aware that enabling this
 204   plugin will disable the normal kadmind dictionary check.  There
 205   currently is no way to have them both enabled at the same time.
 206
 207   Finally, note that the default rules of this plugin will reject the
 208   temporary password used by addprinc -randkey or ktadd -randkey when
 209   initializing a principal.  When generating service principals using that
 210   flag, you will need to pass in the -clearpolicy flag as well to avoid
 211   rejecting the initial temporary password.  You can then add a policy
 212   later with modprinc if desired.