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 minimum_different
  58
  59 If set to a numeric value, passwords with fewer than this number of unique
  60 characters will be rejected.  This can be used to reject, for example,
  61 passwords that are long strings of the same character or repetitions of
  62 small numbers of characters, which may be too easy to guess.
  63
  64 =item minimum_length
  65
  66 If set to a numeric value, passwords with fewer than that number of
  67 characters will be rejected, independent of any length restrictions in
  68 CrackLib.  Note that this setting does not bypass the minimum length
  69 requirements in CrackLib itself.
  70
  71 =item password_dictionary
  72
  73 Specifies the base path to a CrackLib dictionary and enables password
  74 strength testing using CrackLib.  The provided path should be the full
  75 path to the dictionary files, omitting the trailing F<*.hwm>, F<*.pwd>,
  76 and F<*.pwi> extensions for the CrackLib dictionary.
  77
  78 =item password_dictionary_cdb
  79
  80 Specifies the base path to a CDB dictionary and enables CDB password
  81 dictionary lookups.  The path must point to a CDB-format database whose
  82 keys are the known passwords or dictionary words.  The values are ignored.
  83 You can use the B<krb5-strength-wordlist> utility to generate the CDB
  84 database from a word list.
  85
  86 The CDB dictionary lookups do not do the complex password mangling that
  87 CrackLib does.  Instead, the password itself will be checked against the
  88 dictionary, and then variations of the password formed by removing the
  89 first character, the last character, the first and last characters, the
  90 first two characters, and the last two characters.  If any of these
  91 strings are found in the CDB database, the password will be rejected;
  92 otherwise, it will be accepted, at least by this check.
  93
  94 A CrackLib dictionary, a CDB dictionary, and a SQLite dictionary may all
  95 be configured at the same time or in any combination, in which case
  96 CrackLib will be run first, followed by CDB and then SQLite as
  97 appropriate.
  98
  99 =item password_dictionary_sqlite
 100
 101 Specifies the base path to a SQLite dictionary and enables SQLite password
 102 dictionary lookups.  The path must point to a SQLite 3 database with a
 103 table named C<passwords>.  This table should have two columns, C<password>
 104 and C<drowssap>, which, for each dictionary word, holds the word and the
 105 reversed form of the word.  You can use the B<krb5-strength-wordlist>
 106 utility to generate the SQLite database from a word list.
 107
 108 The SQLite dictionary lookups do not do the complex password mangling that
 109 CrackLib does, but they will detect and reject any password that is within
 110 edit distance one of a word in the dictionary, meaning that the dictionary
 111 word can be formed from the password by adding, deleting, or modifying a
 112 single character.
 113
 114 A CrackLib dictionary, a CDB dictionary, and a SQLite dictionary may all
 115 be configured at the same time or in any combination, in which case
 116 CrackLib will be run first, followed by CDB and then SQLite as
 117 appropriate.
 118
 119 =item require_ascii_printable
 120
 121 If set to a true boolean value, rejects any password that contains
 122 non-ASCII characters or ASCII control characters.  Spaces are allowed;
 123 tabs are not (at least assuming the POSIX C locale).  No canonicalization
 124 or character set is defined for Kerberos passwords in general, so you may
 125 want to reject non-ASCII characters to avoid interoperability problems
 126 with computers with different default character sets or Unicode
 127 normalization forms.
 128
 129 =item require_classes
 130
 131 This option allows specification of more complex character class
 132 requirements.  The value of this parameter should be one or more
 133 whitespace-separated rule.  Each rule has the syntax:
 134
 135     [<min>-<max>:]<class>[,<class>...]
 136
 137 where <class> is one of C<upper>, C<lower>, C<digit>, or C<symbol>.  The
 138 symbol class includes all characters other than alphanumeric characters,
 139 including space.  The listed classes must appear in the password.
 140 Separate multiple required classes with a comma (and no space).
 141
 142 The character class checks will be done in whatever locale the plugin or
 143 password check program is run in, which will normally be the POSIX C
 144 locale but may be different depending on local configuration.
 145
 146 A simple example:
 147
 148     require_classes = upper,lower,digit
 149
 150 This requires all passwords contain at least one uppercase letter, at
 151 least one lowercase letter, and at least one digit.
 152
 153 If present, <min> and <max> specify the minimum password length and
 154 maximum password length to which this rule applies.  This allows one to
 155 specify character class requirements that change with password length.
 156 So, for example:
 157
 158     require_classes = 8-19:upper,lower 8-15:digit 8-11:symbol
 159
 160 requires all passwords from 8 to 11 characters long contain all four
 161 character classes, passwords from 12 to 15 characters long contain upper
 162 and lower case and a digit, and passwords from 16 to 19 characters long
 163 contain both upper and lower case.  Passwords longer than 20 characters
 164 have no character class restrictions.  (This example is probably used in
 165 conjunction with minimum_length = 8.)
 166
 167 =item require_non_letter
 168
 169 If set to a true boolean value, the password must contain at least one
 170 character that is not a letter (uppercase or lowercase) or a space.  This
 171 may be helpful in combination with passphrases; users may choose a stock
 172 English phrase, and this will force at least some additional complexity.
 173
 174 =back
 175
 176 =head1 SEE ALSO
 177
 178 krb5-strength-wordlist(1), kadm5-strength(3), kpasswdd(8), krb5.conf(5)
 179
 180 The "Password changing" section of the Heimdal info documentation
 181 describes the interface that this program implements and how to configure
 182 Heimdal to use it.
 183
 184 The current version of this program is available from its web page at
 185 L<http://www.eyrie.org/~eagle/software/krb5-strength/> as part of the
 186 krb5-strength package.
 187
 188 =head1 AUTHOR
 189
 190 Russ Allbery <eagle@eyrie.org>
 191
 192 =head1 COPYRIGHT AND LICENSE
 193
 194 Copyright 2010, 2013, 2014 The Board of Trustees of the Leland Stanford
 195 Junior University
 196
 197 Copying and distribution of this file, with or without modification, are
 198 permitted in any medium without royalty provided the copyright notice and
 199 this notice are preserved.  This file is offered as-is, without any
 200 warranty.
 201
 202 =cut