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