README

   1                             krb5-strength 0.5
   2                (kadmind password strength checking plugin)
   3
   4               Maintained by Russ Allbery <rra@stanford.edu>
   5
   6   Copyright 2006, 2007 Board of Trustees, Leland Stanford Jr. University.
   7   Portions copyright 1993 Alec Muffett.  Developed by Derrick Brashear and
   8   Ken Hornstein of Sine Nomine Associates, on behalf of Stanford
   9   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   This should be considered beta-quality code.  It is not currently
  15   running anywhere in production.  Feedback and improvements will be
  16   gratefully accepted.
  17
  18 BLURB
  19
  20   krb5-strength is a toolkit for checking the strength of passwords
  21   against an external dictionary, applying more transforms and checks than
  22   kadmind supports by default.  It is implemented as a patch to kadmind
  23   and a plugin module that is called on each password change.  It embeds a
  24   slightly modified copy of Alec Muffett's CrackLib to do the password
  25   checking.
  26
  27 DESCRIPTION
  28
  29   The MIT kadmind supports password strength checking against a dictionary
  30   out of the box.  Unfortunately, that support loads the entire dictionary
  31   into memory, requires uncompressed dictionaries, and doesn't apply any
  32   transformations to the password before checking it against the
  33   dictionary.  CrackLib provides more sophisticated strength checking and
  34   an optimized, compressed on-disk database format.  This toolkit provides
  35   a way to check the strength of Kerberos passwords using CrackLib before
  36   allowing them.
  37
  38   This toolkit consists of two pieces:
  39
  40    * A patch to MIT Kerberos to add a plugin system for password strength
  41      checking.  This patch adds initialization and shutdown hooks plus a
  42      hook that's run prior to each password change.  The code in kadmind
  43      is independent of what the plugin might do.
  44
  45    * A kadmind plugin that is a simple wrapper around the CrackLib
  46      password checking call.  Included in this toolkit is a slightly
  47      modified version of CrackLib.
  48
  49   Currently, the embedded CrackLib is built unconditionally.  In a future
  50   release, I hope to add support for building against an already-installed
  51   CrackLib if so desired.
  52
  53   For information about the changes to the CrackLib included in this
  54   toolkit, see cracklib/HISTORY.  They are minor changes to tighten the
  55   rules in some places, be stricter with longer passwords, fix portability
  56   issues, and remove some code that doesn't make sense in the kadmind
  57   context.
  58
  59   Future versions of MIT Kerberos are expected to provide an improved
  60   plugin interface for this sort of check that is not compatible with the
  61   one added by this patch.  As soon as that interface is available, this
  62   package will be updated to work with it.
  63
  64 REQUIREMENTS
  65
  66   To use this plugin, you will need to apply the patch in the patches
  67   directory to MIT Kerberos and rebuild.  Due to how kadmind is
  68   constructed, the changes are actually in the libkadm5srv library, not in
  69   the kadmind binary, so you'll need to install the modified libraries.
  70
  71   For this module to be effective, you will also need to construct a
  72   dictionary.  The mkdict and packer utilities to build a CrackLib
  73   dictionary from a word list are included in this toolkit but not
  74   installed by default.  You can run them out of the cracklib directory
  75   after building.  You can also use the utilities that come with the stock
  76   CrackLib package (often already packaged in a Linux distribution).
  77
  78   For a word list to use as source for the dictionary, you can use
  79   /usr/share/dict/words if it's available on your system, but it would be
  80   better to find a more comprehensive word list (or even better, find
  81   every word list you can locate on the Internet and combine them).  Since
  82   word lists are bulky, often covered by murky copyrights, and easily
  83   locatable on the Internet with a modicum of searching, none are included
  84   in this toolkit.
  85
  86 COMPILING AND INSTALLING
  87
  88   First, patch MIT Kerberos with the patch provided in the patches
  89   directory and install the new libkadm5srv library.  See patches/README
  90   for more information about the patch.  If you're using a different
  91   version of MIT Kerberos, you may need to adjust the patch accordingly.
  92
  93   Then, you can build and install the plugin with the standard commands:
  94
  95       ./configure
  96       make
  97       make install
  98
  99   The last step will probably have to be done as root.  By default, the
 100   plugin is installed as /usr/local/lib/kadmind/passwd_strength.so.  You
 101   can change this path with the --prefix and --libdir options to
 102   configure.
 103
 104 CONFIGURATION
 105
 106   First, build and install a CrackLib dictionary as described above.  This
 107   dictionary will consist of three files, one each ending in *.hwm, *.pwd,
 108   and *.pwi.  Install those files somewhere on your system.
 109
 110   In the [realms] section of your kdc.conf, under the appropriate realm or
 111   realms, specify the path to the dictionary:
 112
 113       dict_file = /path/to/cracklib/dictionary
 114
 115   The provided path should be the full path to the dictionary files,
 116   omitting the trailing *.hwm, *.pwd, or *.pwi extension.  Then, specify
 117   the path to the plugin by adding:
 118
 119       pwcheck_plugin = /usr/local/lib/kadmind/passwd_strength.so
 120
 121   to the same section of the kdc.conf, giving the correct full path to the
 122   plugin.  Restart kadmind and password strength checking should be
 123   enabled.
 124
 125   Be aware that password strength checking is only applied to principals
 126   with a policy set.  If you want to check all user passwords, assign all
 127   user principals a password policy.  (Similarly, you can avoid checking
 128   the strength of passwords for particular principals by clearing their
 129   policy.)  Also be aware that enabling this plugin will disable the
 130   normal kadmind dictionary check.  There currently is no way to have them
 131   both enabled at the same time.
 132
 133   Finally, note that the default rules of this plugin will reject the
 134   temporary password used by addprinc -randkey or ktadd -randkey when
 135   initializing a principal.  When generating service principals using that
 136   flag, you will need to pass in the -clearpolicy flag as well to avoid
 137   rejecting the initial temporary password.  You can then add a policy
 138   later with modprinc if desired.
 139
 140 LICENSE
 141
 142   The packaging, plugin glue, and build system are covered by the
 143   following copyright and license:
 144
 145     Copyright 2006, 2007 Board of Trustees, Leland Stanford Jr.
 146     University.  All rights reserved.
 147
 148     Permission to use, copy, modify, and distribute this software and its
 149     documentation for any purpose and without fee is hereby granted,
 150     provided that the above copyright notice appear in all copies and that
 151     both that copyright notice and this permission notice appear in
 152     supporting documentation, and that the name of Stanford University not
 153     be used in advertising or publicity pertaining to distribution of the
 154     software without specific, written prior permission.  Stanford
 155     University makes no representations about the suitability of this
 156     software for any purpose.  It is provided "as is" without express or
 157     implied warranty.
 158
 159     THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 160     WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 161     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 162
 163   The version of CrackLib included here, and all modifications made to it
 164   as part of this toolkit, is covered by the Artistic License.  For full
 165   license terms, see cracklib/LICENCE.