.\" ========================================================================
.\"
.IX Title "HEIMDAL-STRENGTH 1"
-.TH HEIMDAL-STRENGTH 1 "2013-10-10" "2.1" "krb5-strength"
+.TH HEIMDAL-STRENGTH 1 "2013-12-16" "2.2" "krb5-strength"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBheimdal-strength\fR is an external password quality check program for
-Heimdal that verifies the strength of a password using an embedded copy of
-CrackLib, with some modifications to increase the aggressiveness of its
-rules. It is normally run via \fIkpasswdd\fR\|(8) using the Heimdal password
-quality check interface rather than directly.
+Heimdal that verifies the strength of a password. Passwords can be tested
+with CrackLib, checked against a \s-1CDB\s0 database of known weak passwords,
+checked for length, checked for non-printable or non-ASCII characters that
+may be difficult to enter reproducibly, required to contain particular
+character classes, or any combination of these tests. It is normally run
+via \fIkpasswdd\fR\|(8) using the Heimdal password quality check interface rather
+than directly.
.PP
-To use this program, the path to a CrackLib database must be configured in
-krb5.conf via the \f(CW\*(C`password_dictionary\*(C'\fR setting in \f(CW\*(C`[appdefaults]\*(C'\fR. It
-uses the application name \f(CW\*(C`krb5\-strength\*(C'\fR when trying to find this
-setting. A typical setting would be:
+To use this program, it must be configured in \fIkrb5.conf\fR via settings
+in \f(CW\*(C`[appdefaults]\*(C'\fR for the application name \f(CW\*(C`krb5\-strength\*(C'\fR. A typical
+setting would be:
.PP
.Vb 3
\& krb5\-strength = {
\& }
.Ve
.PP
+which says to check passwords with CrackLib using the given path as the
+base path of the CrackLib dictionary. See \*(L"\s-1CONFIGURATION\*(R"\s0 below for
+details on the supported configuration options.
+.PP
\&\fBheimdal-strength\fR then expects the Heimdal password quality check
information on standard input, specifically:
.PP
rejecting the password on standard error and exit with a status of 0. If
some fatal error occurs, it will print that error to standard error and
exit with a non-zero status.
+.SH "CONFIGURATION"
+.IX Header "CONFIGURATION"
+The following \fIkrb5.conf\fR configuration options are supported:
+.IP "minimum_length" 4
+.IX Item "minimum_length"
+If set to a numeric value, passwords with fewer than that number of
+characters will be rejected, independent of any length restrictions in
+CrackLib. Note that this setting does not bypass the minimum length
+requirements in CrackLib itself.
+.IP "password_dictionary" 4
+.IX Item "password_dictionary"
+Specifies the base path to a CrackLib dictionary and enables password
+strength testing using CrackLib. The provided path should be the full
+path to the dictionary files, omitting the trailing \fI*.hwm\fR, \fI*.pwd\fR,
+and \fI*.pwi\fR extensions for the CrackLib dictionary.
+.IP "password_dictionary_cdb" 4
+.IX Item "password_dictionary_cdb"
+Specifies the base path to a \s-1CDB\s0 dictionary and enables \s-1CDB\s0 password
+dictionary lookups. The path must point to a CDB-format database whose
+keys are the known passwords or dictionary words. The values are ignored.
+You can use the \fBcdbmake-wordlist\fR utility to generate the \s-1CDB\s0 database
+from a word list.
+.Sp
+The \s-1CDB\s0 dictionary lookups do not do the complex password mangling that
+CrackLib does. Instead, the password itself will be checked against the
+dictionary, and then variations of the password formed by removing the
+first character, the last character, the first and last characters, the
+first two characters, and the last two characters. If any of these
+strings are found in the \s-1CDB\s0 database, the password will be rejected;
+otherwise, it will be accepted, at least by this check.
+.Sp
+Both a CrackLib dictionary and a \s-1CDB\s0 dictionary may be configured at the
+same time, in which case CrackLib will be run first, followed by the \s-1CDB\s0
+checks.
+.IP "require_ascii_printable" 4
+.IX Item "require_ascii_printable"
+If set to a true boolean value, rejects any password that contains
+non-ASCII characters or \s-1ASCII\s0 control characters. Spaces are allowed;
+tabs are not (at least assuming the \s-1POSIX C\s0 locale). No canonicalization
+or character set is defined for Kerberos passwords in general, so you may
+want to reject non-ASCII characters to avoid interoperability problems
+with computers with different default character sets or Unicode
+normalization forms.
+.IP "require_classes" 4
+.IX Item "require_classes"
+This option allows specification of more complex character class
+requirements. The value of this parameter should be one or more
+whitespace-separated rule. Each rule has the syntax:
+.Sp
+.Vb 1
+\& [<min>\-<max>:]<class>[,<class>...]
+.Ve
+.Sp
+where <class> is one of \f(CW\*(C`upper\*(C'\fR, \f(CW\*(C`lower\*(C'\fR, \f(CW\*(C`digit\*(C'\fR, or \f(CW\*(C`symbol\*(C'\fR. The
+symbol class includes all characters other than alphanumeric characters,
+including space. The listed classes must appear in the password.
+Separate multiple required classes with a comma (and no space).
+.Sp
+The character class checks will be done in whatever locale the plugin or
+password check program is run in, which will normally be the \s-1POSIX C\s0
+locale but may be different depending on local configuration.
+.Sp
+A simple example:
+.Sp
+.Vb 1
+\& require_classes = upper,lower,digit
+.Ve
+.Sp
+This requires all passwords contain at least one uppercase letter, at
+least one lowercase letter, and at least one digit.
+.Sp
+If present, <min> and <max> specify the minimum password length and
+maximum password length to which this rule applies. This allows one to
+specify character class requirements that change with password length.
+So, for example:
+.Sp
+.Vb 1
+\& require_classes = 8\-19:upper,lower 8\-15:digit 8\-11:symbol
+.Ve
+.Sp
+requires all passwords from 8 to 11 characters long contain all four
+character classes, passwords from 12 to 15 characters long contain upper
+and lower case and a digit, and passwords from 16 to 19 characters long
+contain both upper and lower case. Passwords longer than 20 characters
+have no character class restrictions. (This example is probably used in
+conjunction with minimum_length = 8.)
+.IP "require_non_letter" 4
+.IX Item "require_non_letter"
+If set to a true boolean value, the password must contain at least one
+character that is not a letter (uppercase or lowercase) or a space. This
+may be helpful in combination with passphrases; users may choose a stock
+English phrase, and this will force at least some additional complexity.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
-\&\fIkadm5\-strength\fR\|(3), \fIkpasswdd\fR\|(8), \fIkrb5.conf\fR\|(5)
+\&\fIcdbmake\-wordlist\fR\|(1), \fIkadm5\-strength\fR\|(3), \fIkpasswdd\fR\|(8), \fIkrb5.conf\fR\|(5)
.PP
The \*(L"Password changing\*(R" section of the Heimdal info documentation
describes the interface that this program implements and how to configure
krb5\-strength package.
.SH "AUTHOR"
.IX Header "AUTHOR"
-Russ Allbery <rra@stanford.edu>
+Russ Allbery <eagle@eyrie.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2010, 2013 The Board of Trustees of the Leland Stanford Junior
projects / kerberos / krb5-strength.git / blobdiff