From cc99ca18b80b268db61376557b9781d74091136d Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Fri, 25 Nov 2016 23:02:05 -0800 Subject: [PATCH] Move configuration instructions to man pages Create a new krb5-strength man page that gets the configuration instructions for the plugins (with the proper path substituted in by the Makefile) and move other configuration details to the heimdal-strength and heimdal-history man pages. Duplicate the documentation for cracklib_maxlen in the heimdal-strength man page. This will make it easier to automate generation of the README file, since it will now require less complex formatting. --- .gitignore | 2 + Makefile.am | 33 ++-- NEWS | 5 + README | 266 +------------------------------- bootstrap | 3 + docs/krb5-strength.pod | 304 +++++++++++++++++++++++++++++++++++++ tools/heimdal-history | 36 ++++- tools/heimdal-strength.pod | 10 ++ 8 files changed, 381 insertions(+), 278 deletions(-) create mode 100644 docs/krb5-strength.pod diff --git a/.gitignore b/.gitignore index cfbaa38..dd75eb3 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ /config.status /configure /cracklib/packer +/docs/krb5-strength.5.in /libtool /m4/libtool.m4 /m4/ltoptions.m4 @@ -39,6 +40,7 @@ .dirstamp .libs/ *.1 +*.5 *.a *.lo *.la diff --git a/Makefile.am b/Makefile.am index 80fa8e7..a0502a5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -10,9 +10,9 @@ 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 \ @@ -95,21 +95,28 @@ dist_bin_SCRIPTS = tools/heimdal-history tools/krb5-strength-wordlist # 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. diff --git a/NEWS b/NEWS index 73cb893..4e9f93e 100644 --- a/NEWS +++ b/NEWS @@ -31,6 +31,11 @@ krb5-strength 3.1 (unreleased) 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. diff --git a/README b/README index 756ffcc..7371673 100644 --- a/README +++ b/README @@ -236,270 +236,8 @@ COMPILING AND INSTALLING 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: - - [-:][,...] - - where 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, and 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 diff --git a/bootstrap b/bootstrap index bf1216e..46c154c 100755 --- a/bootstrap +++ b/bootstrap @@ -3,6 +3,7 @@ # Run this shell script to bootstrap as necessary after a fresh checkout. # # Written by Russ Allbery +# Copyright 2016 Russ Allbery # Copyright 2007, 2010, 2013, 2014 # The Board of Trustees of the Leland Stanford Junior University # @@ -15,6 +16,8 @@ autoreconf -i --force # 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' \ diff --git a/docs/krb5-strength.pod b/docs/krb5-strength.pod new file mode 100644 index 0000000..96e5cac --- /dev/null +++ b/docs/krb5-strength.pod @@ -0,0 +1,304 @@ +=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 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 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 and B utilities +that come with it. The former takes a set of wordlists and outputs a +wordlist in the format required by B, and the latter +turns this into a CrackLib dictionary. Alternately, you can use the +B and B utilities, which are included in the krb5-strength +package but not installed by default. You can run them out of the +F directory of the source tree after building. (B is +the equivalent of B.) + +For building a CDB or SQLite dictionary, use B. + +=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 or L. + +See L below for additional F 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 to time +out. If you choose to use the external program, read the +B documentation instead of this documentation. + +If using the module, first add a stanza like the following to the +C<[appdefaults]> section of your F (or wherever your +F 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 or F. Note that some older versions of +Heimdal have a bug in the support for loading modules when +C is set. If you get an error like: + + didn't find `kadm5_password_verifier' symbol in `(null)' + +you may have to omit C in your configuration and instead +pass the C<--check-library argument> to B specifying the library +to load. + +If you want to also enable history checking, see L for +further instructions. + +=head2 MIT Kerberos + +To add this module to the list of password quality checks, add a section +to F (or to a separate F 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 (and in this case you must use F, even if you use +a separate F 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 setting. In the +C<[realms]> section of your F or F, 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 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 for the +CrackLib dictionary path and F for the CDB or SQLite dictionary +paths. If both settings are used for the CrackLib path, F +overrides the C setting (so that C can be used for +other password quality modules). There is no way to specify a CDB or +SQLite dictionary via the C setting. + +=head2 Other Settings + +The following additional settings are supported in the C<[appdefaults]> +section of F 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: + + [-:][,...] + +where is one of C, C, C, or C +(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, and 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.) + +=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 + +=head1 COPYRIGHT AND LICENSE + +Copyright 2016 Russ Allbery + +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, L, L, +L + +=cut diff --git a/tools/heimdal-history b/tools/heimdal-history index 840f999..08c2f01 100755 --- a/tools/heimdal-history +++ b/tools/heimdal-history @@ -662,7 +662,7 @@ __END__ =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 @@ -696,6 +696,9 @@ password strength checking interface. By default, it runs B. 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 below. + As with any implementation of the Heimdal external password strength checking protocol, B expects, on standard input: @@ -799,6 +802,35 @@ testing, since Heimdal won't pass this argument. =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 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 user and +C 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 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 or F to: + + [password_quality] + policies = external-check + external_program = /usr/local/bin/heimdal-history + +The B program will automatically also run +B as well, looking for it in F. 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 as if you were running it directly. + =head1 RETURN STATUS On approval of the password, B will print C and @@ -857,6 +889,8 @@ Russ Allbery =head1 COPYRIGHT AND LICENSE +Copyright 2016 Russ Allbery + Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior University diff --git a/tools/heimdal-strength.pod b/tools/heimdal-strength.pod index 93ae31c..802da32 100644 --- a/tools/heimdal-strength.pod +++ b/tools/heimdal-strength.pod @@ -54,6 +54,16 @@ The following F configuration options are supported: =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 -- 2.39.2