tools/heimdal-strength.pod

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