/config.status
/configure
/cracklib/packer
+/docs/krb5-strength.5.in
/libtool
/m4/libtool.m4
/m4/ltoptions.m4
.dirstamp
.libs/
*.1
+*.5
*.a
*.lo
*.la
ACLOCAL_AMFLAGS = -I m4
EXTRA_DIST = .gitignore .travis.yml LICENSE bootstrap cracklib/HISTORY \
cracklib/LICENCE cracklib/README cracklib/genrules.pl \
- cracklib/mkdict tests/HOWTO tests/TESTS tests/data/krb5.conf \
- tests/data/make-krb5-conf tests/data/passwords tests/data/perl.conf \
- tests/data/perlcriticrc tests/data/perltidyrc \
+ cracklib/mkdict docs/krb5-strength.5.in tests/HOWTO tests/TESTS \
+ tests/data/krb5.conf tests/data/make-krb5-conf tests/data/passwords \
+ tests/data/perl.conf tests/data/perlcriticrc tests/data/perltidyrc \
tests/data/valgrind.supp tests/data/wordlist \
tests/data/wordlist.cdb tests/data/wordlist.sqlite \
tests/docs/pod-spelling-t tests/docs/pod-t tests/perl/critic-t \
# Man pages for all tools.
dist_man_MANS = tools/heimdal-history.1 tools/heimdal-strength.1 \
tools/krb5-strength-wordlist.1
+man_MANS = docs/krb5-strength.5
+
+# Substitute the installation paths into the manual page.
+docs/krb5-strength.5: $(srcdir)/docs/krb5-strength.5.in
+ [ -d docs ] || mkdir docs
+ sed -e 's%\(\\f(CI\)*\@moduledir\(\\fI\)*\@%$(moduledir)%' \
+ < $(srcdir)/docs/krb5-strength.5.in > $@
# Handle the standard stuff that make maintainer-clean should probably remove
# but doesn't. This breaks the GNU coding standard, but in this area the GNU
# coding standard is dumb.
-CLEANFILES = tests/data/dictionary.hwm tests/data/dictionary.pwd \
- tests/data/dictionary.pwi
+CLEANFILES = docs/krb5-strength.5 tests/data/dictionary.hwm \
+ tests/data/dictionary.pwd tests/data/dictionary.pwi
DISTCLEANFILES = tests/data/.placeholder
-MAINTAINERCLEANFILES = Makefile.in aclocal.m4 build-aux/compile \
- build-aux/config.guess build-aux/config.sub build-aux/depcomp \
- build-aux/install-sh build-aux/ltmain.sh build-aux/missing \
- config.h.in config.h.in~ configure m4/libtool.m4 m4/ltoptions.m4 \
- m4/ltsugar.m4 m4/ltversion.m4 m4/lt~obsolete.m4 \
- tests/data/wordlist.cdb tests/data/wordlist.sqlite \
- tools/heimdal-history.1 tools/heimdal-strength.1 \
- tools/krb5-strength-wordlist.1
+MAINTAINERCLEANFILES = Makefile.in aclocal.m4 build-aux/compile \
+ build-aux/config.guess build-aux/config.sub build-aux/depcomp \
+ build-aux/install-sh build-aux/ltmain.sh build-aux/missing \
+ config.h.in config.h.in~ configure docs/krb5-strength.5.in \
+ m4/libtool.m4 m4/ltoptions.m4 m4/ltsugar.m4 m4/ltversion.m4 \
+ m4/lt~obsolete.m4 tests/data/wordlist.cdb \
+ tests/data/wordlist.sqlite tools/heimdal-history.1 \
+ tools/heimdal-strength.1 tools/krb5-strength-wordlist.1
# Also remove the generated *.c files from our JSON test data on
# maintainer-clean.
skip out-of-order words rather than creating a corrupted dictionary.
Patch from Mark Sirota.
+ Configuration instrutions are now in the heimdal-history and
+ heimdal-strength man pages and a new krb5-strength man page (which
+ documents configuration of the KDC plugin) instead of the README file
+ to make it more accessible after the software has been installed.
+
Update to rra-c-util 6.2:
* Use calloc in preference to malloc wherever appropriate.
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 or SQLite dictionary with
- krb5-strength-wordlist. (Or any combination thereof.) The CrackLib
- dictionary will consist of three files, one each ending in *.hwm, *.pwd,
- and *.pwi. The CDB and SQLite dictionaries will be single files,
- conventionally ending in *.cdb and *.sqlite respectively. 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.
-
- cracklib_maxlen
-
- Normally, all passwords are checked with CrackLib if a CrackLib
- dictionary is defined. However, CrackLib's rules were designed for
- a world in which most passwords were four to eight characters long,
- and tends to spuriously reject a lot of passphrases. If this option
- is set to something other than its default of 0, passwords longer
- than that length bypass CrackLib checks. (Using a SQLite dictionary
- for longer passwords is strongly recommended.)
-
- 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.)
+ After installing this software, see the man pages for krb5-strength,
+ heimdal-strength, and heimdal-history for configuration information.
SUPPORT
# Run this shell script to bootstrap as necessary after a fresh checkout.
#
# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2016 Russ Allbery <eagle@eyrie.org>
# Copyright 2007, 2010, 2013, 2014
# The Board of Trustees of the Leland Stanford Junior University
#
# Generate manual pages.
version=`grep '^krb5-strength' NEWS | head -1 | cut -d' ' -f2`
+pod2man --release="$version" --center='krb5-strength' --section=5 \
+ docs/krb5-strength.pod > docs/krb5-strength.5.in
pod2man --release="$version" --center='krb5-strength' \
tools/heimdal-history > tools/heimdal-history.1
pod2man --release="$version" --center='krb5-strength' \
--- /dev/null
+=for stopwords
+Allbery CDB CrackLib Heimdal KDC KDCs canonicalization cracklib-format
+cracklib-packer heimdal-strength heimdal-history kadmind kpasswd kpasswdd
+krb5-strength mkdict pwqual cracklib-runtime krb5-strength-wordlist
+
+=head1 NAME
+
+krb5-strength - Kerberos password strength checking plugin
+
+=head1 SYNOPSIS
+
+MIT Kerberos:
+
+ [plugins]
+ pwqual = {
+ module = strength:@moduledir@/strength.so
+ }
+
+Heimdal:
+
+ [password_quality]
+ policies = krb5-strength
+ policy_libraries = @moduledir@/strength.so
+
+=head1 DESCRIPTION
+
+F<strength.so> is a KDC plugin for Kerberos password strength checking for
+either MIT Kerberos or Heimdal provided as part of the krb5-strength
+package. For MIT Kerberos KDCs (or, more to the point, kadmind servers),
+this plugin is the recommended way of enabling strength checking. For
+Heimdal KDCs, you normally should use the B<heimdal-strength> external
+program instead, but the plugin is a supported option if you want to avoid
+external programs for some reason.
+
+For this module to be effective for either Heimdal or MIT Kerberos, you
+will also need to construct a dictionary. What type of dictionary you
+create depends on what backends you want to use: CrackLib, CDB, or SQLite.
+
+For CrackLib, on Debian systems, you can install the cracklib-runtime
+package and use the B<cracklib-format> and B<cracklib-packer> utilities
+that come with it. The former takes a set of wordlists and outputs a
+wordlist in the format required by B<cracklib-packer>, and the latter
+turns this into a CrackLib dictionary. Alternately, you can use the
+B<mkdict> and B<packer> utilities, which are included in the krb5-strength
+package but not installed by default. You can run them out of the
+F<cracklib> directory of the source tree after building. (B<mkdict> is
+the equivalent of B<cracklib-format>.)
+
+For building a CDB or SQLite dictionary, use B<krb5-strength-wordlist>.
+
+=head1 CONFIGURATION
+
+First, build and install either a CrackLib dictionary as described above.
+The CrackLib dictionary will consist of three files, one each ending in
+C<*.hwm>, C<*.pwd>, and C<*.pwi>. The CDB and SQLite dictionaries will be
+single files, conventionally ending in C<*.cdb> and C<*.sqlite>
+respectively. Install those files somewhere on your system. Then, follow
+the relevant instructions below for either L</Heimdal> or L</MIT
+Kerberos>.
+
+See L</Other Settings> below for additional F<krb5.conf> setting supported
+by both Heimdal and MIT Kerberos.
+
+=head2 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 B<kpasswd> to time
+out. If you choose to use the external program, read the
+B<heimdal-strength> documentation instead of this documentation.
+
+If using the module, first add a stanza like the following to the
+C<[appdefaults]> section of your F</etc/krb5.conf> (or wherever your
+F<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 C<*.hwm>,
+C<*.pwd>, and C<*.pwi> extensions for the CrackLib dictionary (but
+including the extensions for the other types). 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, add a new section (or modify the existing C<[password_quality]>
+section) like the following:
+
+ [password_quality]
+ policies = krb5-strength
+ policy_libraries = @moduledir@/strength.so
+
+in either F<krb5.conf> or F<kdc.conf>. Note that some older versions of
+Heimdal have a bug in the support for loading modules when
+C<policy_libraries> is set. If you get an error like:
+
+ didn't find `kadm5_password_verifier' symbol in `(null)'
+
+you may have to omit C<policy_libraries> in your configuration and instead
+pass the C<--check-library argument> to B<kpasswdd> specifying the library
+to load.
+
+If you want to also enable history checking, see L<heimdal-history(1)> for
+further instructions.
+
+=head2 MIT Kerberos
+
+To add this module to the list of password quality checks, add a section
+to F<krb5.conf> (or to a separate F<kdc.conf> if you use that) like:
+
+ [plugins]
+ pwqual = {
+ module = strength:@moduledir@/strength.so
+ }
+
+to register the plugin.
+
+There are two ways to tell where the dictionary is. One option is to use
+F<krb5.conf> (and in this case you must use F<krb5.conf>, even if you use
+a separate F<kdc.conf> file). For this approach, add the following to the
+C<[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 C<*.hwm>,
+C<*.pwd>, and C<*.pwi> extensions for the CrackLib dictionary (but
+including the extensions for the other types). 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 C<dict_path> setting. In the
+C<[realms]> section of your F<krb5.conf> or F<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 C<*.hwm>, C<*.pwd>, or
+C<*.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 C<pwqual> block of the C<[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 C<dict_path> for the
+CrackLib dictionary path and F<krb5.conf> for the CDB or SQLite dictionary
+paths. If both settings are used for the CrackLib path, F<krb5.conf>
+overrides the C<dict_path> setting (so that C<dict_path> can be used for
+other password quality modules). There is no way to specify a CDB or
+SQLite dictionary via the C<dict_path> setting.
+
+=head2 Other Settings
+
+The following additional settings are supported in the C<[appdefaults]>
+section of F<krb5.conf> when running under either Heimdal or MIT Kerberos.
+
+=over 4
+
+=item cracklib_maxlen
+
+Normally, all passwords are checked with CrackLib if a CrackLib dictionary
+is defined. However, CrackLib's rules were designed for a world in which
+most passwords were four to eight characters long, and tends to spuriously
+reject a lot of passphrases. If this option is set to something other
+than its default of 0, passwords longer than that length bypass CrackLib
+checks. (Using a SQLite dictionary for longer passwords is strongly
+recommended.)
+
+=item 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.
+
+=item 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).
+
+=item 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.
+
+=item 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 C<upper>, C<lower>, C<digit>, or C<symbol>
+(without 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. Passwords longer than 20 characters
+have no character class restrictions. (This example is probably used in
+conjunction with C<minimum_length = 8>.)
+
+=item 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.
+
+=back
+
+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.)
+
+=head1 AUTHOR
+
+Russ Allbery <eagle@eyrie.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2016 Russ Allbery <eagle@eyrie.org>
+
+Copyright 2006, 2007, 2009, 2010, 2012, 2013, 2014 The Board of Trustees
+of the Leland Stanford Junior University
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved. This file is offered as-is, without any
+warranty.
+
+=head1 SEE ALSO
+
+L<cracklib-format(8)>, L<cracklib-packer(8)>, L<heimdal-strength(1)>,
+L<krb5-strength-wordlist(1)>
+
+=cut
=for stopwords
heimdal-history heimdal-strength Heimdal -hmq BerkeleyDB timestamps POSIX
whitespace API Allbery sublicense MERCHANTABILITY NONINFRINGEMENT syslog
-pseudorandom JSON LDAP-compatible PBKDF2 SHA-256
+pseudorandom JSON LDAP-compatible PBKDF2 SHA-256 KDC
=head1 NAME
B</usr/bin/heimdal-strength>. Only if that program approves the password
does it hash it and check history.
+For more information on how to set up password history, see
+L</CONFIGURATION> below.
+
As with any implementation of the Heimdal external password strength
checking protocol, B<heimdal-history> expects, on standard input:
=back
+=head1 CONFIGURATION
+
+Additional setup is required to use this history implementation with your
+Heimdal KDC.
+
+First, ensure that its dependencies are installed, and then examine the
+local configuration settings at the top of the B<heimdal-history> program.
+By default, it requires a C<_history> user and C<_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 C<nobody> user and
+C<nogroup> group to be present (this should be the default with most
+variants of UNIX), and all strength checking will be done as that user and
+group. It uses various files in F</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 C<_history> user.
+
+Once that setup is done, change your C<[password_quality]> configuration
+in F<krb5.conf> or F<kdc.conf> to:
+
+ [password_quality]
+ policies = external-check
+ external_program = /usr/local/bin/heimdal-history
+
+The B<heimdal-history> program will automatically also run
+B<heimdal-strength> as well, looking for it in F</usr/bin>. Change the
+C<$STRENGTH_PROGRAM> setting at the top of the script if you have that
+program in a different location. You should continue to configure
+B<heimdal-strength> as if you were running it directly.
+
=head1 RETURN STATUS
On approval of the password, B<heimdal-history> will print C<APPROVED> and
=head1 COPYRIGHT AND LICENSE
+Copyright 2016 Russ Allbery <eagle@eyrie.org>
+
Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
University
=over 4
+=item cracklib_maxlen
+
+Normally, all passwords are checked with CrackLib if a CrackLib dictionary
+is defined. However, CrackLib's rules were designed for a world in which
+most passwords were four to eight characters long, and tends to spuriously
+reject a lot of passphrases. If this option is set to something other
+than its default of 0, passwords longer than that length bypass CrackLib
+checks. (Using a SQLite dictionary for longer passwords is strongly
+recommended.)
+
=item minimum_different
If set to a numeric value, passwords with fewer than this number of unique