tools/heimdal-strength.pod

   1 =for stopwords
   2 heimdal-strength Heimdal CrackLib krb5-strength Allbery CDB
   3 canonicalization cdbmake-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<cdbmake-wordlist> utility to generate the CDB database
  77 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 Both a CrackLib dictionary and a CDB dictionary may be configured at the
  88 same time, in which case CrackLib will be run first, followed by the CDB
  89 checks.
  90
  91 =item require_ascii_printable
  92
  93 If set to a true boolean value, rejects any password that contains
  94 non-ASCII characters or ASCII control characters.  Spaces are allowed;
  95 tabs are not (at least assuming the POSIX C locale).  No canonicalization
  96 or character set is defined for Kerberos passwords in general, so you may
  97 want to reject non-ASCII characters to avoid interoperability problems
  98 with computers with different default character sets or Unicode
  99 normalization forms.
 100
 101 =item require_classes
 102
 103 This option allows specification of more complex character class
 104 requirements.  The value of this parameter should be one or more
 105 whitespace-separated rule.  Each rule has the syntax:
 106
 107     [<min>-<max>:]<class>[,<class>...]
 108
 109 where <class> is one of C<upper>, C<lower>, C<digit>, or C<symbol>.  The
 110 symbol class includes all characters other than alphanumeric characters,
 111 including space.  The listed classes must appear in the password.
 112 Separate multiple required classes with a comma (and no space).
 113
 114 The character class checks will be done in whatever locale the plugin or
 115 password check program is run in, which will normally be the POSIX C
 116 locale but may be different depending on local configuration.
 117
 118 A simple example:
 119
 120     require_classes = upper,lower,digit
 121
 122 This requires all passwords contain at least one uppercase letter, at
 123 least one lowercase letter, and at least one digit.
 124
 125 If present, <min> and <max> specify the minimum password length and
 126 maximum password length to which this rule applies.  This allows one to
 127 specify character class requirements that change with password length.
 128 So, for example:
 129
 130     require_classes = 8-19:upper,lower 8-15:digit 8-11:symbol
 131
 132 requires all passwords from 8 to 11 characters long contain all four
 133 character classes, passwords from 12 to 15 characters long contain upper
 134 and lower case and a digit, and passwords from 16 to 19 characters long
 135 contain both upper and lower case.  Passwords longer than 20 characters
 136 have no character class restrictions.  (This example is probably used in
 137 conjunction with minimum_length = 8.)
 138
 139 =item require_non_letter
 140
 141 If set to a true boolean value, the password must contain at least one
 142 character that is not a letter (uppercase or lowercase) or a space.  This
 143 may be helpful in combination with passphrases; users may choose a stock
 144 English phrase, and this will force at least some additional complexity.
 145
 146 =back
 147
 148 =head1 SEE ALSO
 149
 150 cdbmake-wordlist(1), kadm5-strength(3), kpasswdd(8), krb5.conf(5)
 151
 152 The "Password changing" section of the Heimdal info documentation
 153 describes the interface that this program implements and how to configure
 154 Heimdal to use it.
 155
 156 The current version of this program is available from its web page at
 157 L<http://www.eyrie.org/~eagle/software/krb5-strength/> as part of the
 158 krb5-strength package.
 159
 160 =head1 AUTHOR
 161
 162 Russ Allbery <eagle@eyrie.org>
 163
 164 =head1 COPYRIGHT AND LICENSE
 165
 166 Copyright 2010, 2013 The Board of Trustees of the Leland Stanford Junior
 167 University
 168
 169 Copying and distribution of this file, with or without modification, are
 170 permitted in any medium without royalty provided the copyright notice and
 171 this notice are preserved.  This file is offered as-is, without any
 172 warranty.
 173
 174 =cut