tools/heimdal-strength.pod

   1 =for stopwords
   2 heimdal-strength Heimdal CrackLib krb5-strength Allbery CDB
   3 canonicalization krb5-strength-wordlist reproducibly
   4 SPDX-License-Identifier FSFAP
   5
   6 =head1 NAME
   7
   8 heimdal-strength - Heimdal password quality check embedding CrackLib
   9
  10 =head1 SYNOPSIS
  11
  12 B<heimdal-strength> [I<principal>]
  13
  14 =head1 DESCRIPTION
  15
  16 B<heimdal-strength> is an external password quality check program for
  17 Heimdal that verifies the strength of a password.  Passwords can be tested
  18 with CrackLib, checked against a CDB database of known weak passwords,
  19 checked for length, checked for non-printable or non-ASCII characters that
  20 may be difficult to enter reproducibly, required to contain particular
  21 character classes, or any combination of these tests.  It is normally run
  22 via kpasswdd(8) using the Heimdal password quality check interface rather
  23 than directly.
  24
  25 To use this program, it must be configured in F<krb5.conf> via settings
  26 in C<[appdefaults]> for the application name C<krb5-strength>.  A typical
  27 setting would be:
  28
  29     krb5-strength = {
  30         password_dictionary = /usr/local/lib/kadmind/dictionary
  31     }
  32
  33 which says to check passwords with CrackLib using the given path as the
  34 base path of the CrackLib dictionary.  See L</CONFIGURATION> below for
  35 details on the supported configuration options.
  36
  37 B<heimdal-strength> then expects the Heimdal password quality check
  38 information on standard input, specifically:
  39
  40     principal: <principal>
  41     new-password: <password>
  42     end
  43
  44 where <principal> is the principal whose password would be changed and
  45 <password> is the new password.  If the password appears to be strong, it
  46 prints C<APPROVED> on standard output and exits with a status of 0.  If
  47 the password is rejected as being too weak, it will print the reason for
  48 rejecting the password on standard error and exit with a status of 0.  If
  49 some fatal error occurs, it will print that error to standard error and
  50 exit with a non-zero status.
  51
  52 =head1 CONFIGURATION
  53
  54 The following F<krb5.conf> configuration options are supported:
  55
  56 =over 4
  57
  58 =item cracklib_maxlen
  59
  60 Normally, all passwords are checked with CrackLib if a CrackLib dictionary
  61 is defined.  However, CrackLib's rules were designed for a world in which
  62 most passwords were four to eight characters long, and tends to spuriously
  63 reject a lot of passphrases.  If this option is set to something other
  64 than its default of 0, passwords longer than that length bypass CrackLib
  65 checks.  (Using a SQLite dictionary for longer passwords is strongly
  66 recommended.)
  67
  68 =item minimum_different
  69
  70 If set to a numeric value, passwords with fewer than this number of unique
  71 characters will be rejected.  This can be used to reject, for example,
  72 passwords that are long strings of the same character or repetitions of
  73 small numbers of characters, which may be too easy to guess.
  74
  75 =item minimum_length
  76
  77 If set to a numeric value, passwords with fewer than that number of
  78 characters will be rejected, independent of any length restrictions in
  79 CrackLib.  Note that this setting does not bypass the minimum length
  80 requirements in CrackLib itself.
  81
  82 =item password_dictionary
  83
  84 Specifies the base path to a CrackLib dictionary and enables password
  85 strength testing using CrackLib.  The provided path should be the full
  86 path to the dictionary files, omitting the trailing F<*.hwm>, F<*.pwd>,
  87 and F<*.pwi> extensions for the CrackLib dictionary.
  88
  89 =item password_dictionary_cdb
  90
  91 Specifies the base path to a CDB dictionary and enables CDB password
  92 dictionary lookups.  The path must point to a CDB-format database whose
  93 keys are the known passwords or dictionary words.  The values are ignored.
  94 You can use the B<krb5-strength-wordlist> utility to generate the CDB
  95 database from a word list.
  96
  97 The CDB dictionary lookups do not do the complex password mangling that
  98 CrackLib does.  Instead, the password itself will be checked against the
  99 dictionary, and then variations of the password formed by removing the
 100 first character, the last character, the first and last characters, the
 101 first two characters, and the last two characters.  If any of these
 102 strings are found in the CDB database, the password will be rejected;
 103 otherwise, it will be accepted, at least by this check.
 104
 105 A CrackLib dictionary, a CDB dictionary, and a SQLite dictionary may all
 106 be configured at the same time or in any combination, in which case
 107 CrackLib will be run first, followed by CDB and then SQLite as
 108 appropriate.
 109
 110 =item password_dictionary_sqlite
 111
 112 Specifies the base path to a SQLite dictionary and enables SQLite password
 113 dictionary lookups.  The path must point to a SQLite 3 database with a
 114 table named C<passwords>.  This table should have two columns, C<password>
 115 and C<drowssap>, which, for each dictionary word, holds the word and the
 116 reversed form of the word.  You can use the B<krb5-strength-wordlist>
 117 utility to generate the SQLite database from a word list.
 118
 119 The SQLite dictionary lookups do not do the complex password mangling that
 120 CrackLib does, but they will detect and reject any password that is within
 121 edit distance one of a word in the dictionary, meaning that the dictionary
 122 word can be formed from the password by adding, deleting, or modifying a
 123 single character.
 124
 125 A CrackLib dictionary, a CDB dictionary, and a SQLite dictionary may all
 126 be configured at the same time or in any combination, in which case
 127 CrackLib will be run first, followed by CDB and then SQLite as
 128 appropriate.
 129
 130 =item require_ascii_printable
 131
 132 If set to a true boolean value, rejects any password that contains
 133 non-ASCII characters or ASCII control characters.  Spaces are allowed;
 134 tabs are not (at least assuming the POSIX C locale).  No canonicalization
 135 or character set is defined for Kerberos passwords in general, so you may
 136 want to reject non-ASCII characters to avoid interoperability problems
 137 with computers with different default character sets or Unicode
 138 normalization forms.
 139
 140 =item require_classes
 141
 142 This option allows specification of more complex character class
 143 requirements.  The value of this parameter should be one or more
 144 whitespace-separated rule.  Each rule has the syntax:
 145
 146     [<min>-<max>:]<class>[,<class>...]
 147
 148 where <class> is one of C<upper>, C<lower>, C<digit>, or C<symbol>.  The
 149 symbol class includes all characters other than alphanumeric characters,
 150 including space.  The listed classes must appear in the password.
 151 Separate multiple required classes with a comma (and no space).
 152
 153 The character class checks will be done in whatever locale the plugin or
 154 password check program is run in, which will normally be the POSIX C
 155 locale but may be different depending on local configuration.
 156
 157 A simple example:
 158
 159     require_classes = upper,lower,digit
 160
 161 This requires all passwords contain at least one uppercase letter, at
 162 least one lowercase letter, and at least one digit.
 163
 164 If present, <min> and <max> specify the minimum password length and
 165 maximum password length to which this rule applies.  This allows one to
 166 specify character class requirements that change with password length.
 167 So, for example:
 168
 169     require_classes = 8-19:upper,lower 8-15:digit 8-11:symbol
 170
 171 requires all passwords from 8 to 11 characters long contain all four
 172 character classes, passwords from 12 to 15 characters long contain upper
 173 and lower case and a digit, and passwords from 16 to 19 characters long
 174 contain both upper and lower case.  Passwords longer than 20 characters
 175 have no character class restrictions.  (This example is probably used in
 176 conjunction with minimum_length = 8.)
 177
 178 =item require_non_letter
 179
 180 If set to a true boolean value, the password must contain at least one
 181 character that is not a letter (uppercase or lowercase) or a space.  This
 182 may be helpful in combination with passphrases; users may choose a stock
 183 English phrase, and this will force at least some additional complexity.
 184
 185 =back
 186
 187 =head1 SEE ALSO
 188
 189 krb5-strength-wordlist(1), kadm5-strength(3), kpasswdd(8), krb5.conf(5)
 190
 191 The "Password changing" section of the Heimdal info documentation
 192 describes the interface that this program implements and how to configure
 193 Heimdal to use it.
 194
 195 The current version of this program is available from its web page at
 196 L<https://www.eyrie.org/~eagle/software/krb5-strength/> as part of the
 197 krb5-strength package.
 198
 199 =head1 AUTHOR
 200
 201 Russ Allbery <eagle@eyrie.org>
 202
 203 =head1 COPYRIGHT AND LICENSE
 204
 205 Copyright 2016 Russ Allbery <eagle@eyrie.org>
 206
 207 Copyright 2010, 2013-2014 The Board of Trustees of the Leland Stanford
 208 Junior University
 209
 210 Copying and distribution of this file, with or without modification, are
 211 permitted in any medium without royalty provided the copyright notice and
 212 this notice are preserved.  This file is offered as-is, without any
 213 warranty.
 214
 215 SPDX-License-Identifier: FSFAP
 216
 217 =cut