.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "KRB5-STRENGTH 5" .TH KRB5-STRENGTH 5 "2018-09-01" "3.1" "krb5-strength" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" krb5\-strength \- Kerberos password strength checking plugin .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\s-1MIT\s0 Kerberos: .PP .Vb 4 \& [plugins] \& pwqual = { \& module = strength:/usr/lib/x86_64-linux-gnu/krb5/plugins/pwqual/strength.so \& } .Ve .PP Heimdal: .PP .Vb 3 \& [password_quality] \& policies = krb5\-strength \& policy_libraries = /usr/lib/x86_64-linux-gnu/krb5/plugins/pwqual/strength.so .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIstrength.so\fR is a \s-1KDC\s0 plugin for Kerberos password strength checking for either \s-1MIT\s0 Kerberos or Heimdal provided as part of the krb5\-strength package. For \s-1MIT\s0 Kerberos KDCs (or, more to the point, kadmind servers), this plugin is the recommended way of enabling strength checking. For Heimdal KDCs, you normally should use the \fBheimdal-strength\fR external program instead, but the plugin is a supported option if you want to avoid external programs for some reason. .PP For this module to be effective for either Heimdal or \s-1MIT\s0 Kerberos, you will also need to construct a dictionary. What type of dictionary you create depends on what backends you want to use: CrackLib, \s-1CDB,\s0 or SQLite. .PP For CrackLib, on Debian systems, you can install the cracklib-runtime package and use the \fBcracklib-format\fR and \fBcracklib-packer\fR utilities that come with it. The former takes a set of wordlists and outputs a wordlist in the format required by \fBcracklib-packer\fR, and the latter turns this into a CrackLib dictionary. Alternately, you can use the \&\fBmkdict\fR and \fBpacker\fR utilities, which are included in the krb5\-strength package but not installed by default. You can run them out of the \&\fIcracklib\fR directory of the source tree after building. (\fBmkdict\fR is the equivalent of \fBcracklib-format\fR.) .PP For building a \s-1CDB\s0 or SQLite dictionary, use \fBkrb5\-strength\-wordlist\fR. .SH "CONFIGURATION" .IX Header "CONFIGURATION" First, build and install either a CrackLib dictionary as described above. The CrackLib dictionary will consist of three files, one each ending in \&\f(CW\*(C`*.hwm\*(C'\fR, \f(CW\*(C`*.pwd\*(C'\fR, and \f(CW\*(C`*.pwi\*(C'\fR. The \s-1CDB\s0 and SQLite dictionaries will be single files, conventionally ending in \f(CW\*(C`*.cdb\*(C'\fR and \f(CW\*(C`*.sqlite\*(C'\fR respectively. Install those files somewhere on your system. Then, follow the relevant instructions below for either \*(L"Heimdal\*(R" or \*(L"\s-1MIT\s0 Kerberos\*(R". .PP See \*(L"Other Settings\*(R" below for additional \fIkrb5.conf\fR setting supported by both Heimdal and \s-1MIT\s0 Kerberos. .SS "Heimdal" .IX Subsection "Heimdal" There are two options: using an external password check program, or using the plugin. I recommend the external password check program unless you encounter speed problems with that approach that cause \fBkpasswd\fR to time out. If you choose to use the external program, read the \&\fBheimdal-strength\fR documentation instead of this documentation. .PP If using the module, first add a stanza like the following to the \&\f(CW\*(C`[appdefaults]\*(C'\fR section of your \fI/etc/krb5.conf\fR (or wherever your \&\fIkrb5.conf\fR file is located): .PP .Vb 5 \& krb5\-strength = { \& password_dictionary = /path/to/cracklib/dictionary \& password_dictionary_cdb = /path/to/cdb/dictionary.cdb \& password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite \& } .Ve .PP The first setting configures a CrackLib dictionary, the second a \s-1CDB\s0 dictionary, and the third a SQLite dictionary. The provided path should be the full path to the dictionary files, omitting the trailing \f(CW\*(C`*.hwm\*(C'\fR, \&\f(CW\*(C`*.pwd\*(C'\fR, and \f(CW\*(C`*.pwi\*(C'\fR extensions for the CrackLib dictionary (but including the extensions for the other types). You can use any combination of the three settings. If you use more than one, CrackLib will be checked first, then \s-1CDB,\s0 and then SQLite as appropriate. .PP When checking against a \s-1CDB\s0 database, the password, the password with the first character removed, the last character removed, the first and last characters removed, the first two characters removed, and the last two characters removed will all be checked against the dictionary. .PP When checking a SQLite database, the password will be rejected if it is within edit distance one of any word in the dictionary, meaning that the database word can be formed from the password by deleting, adding, or changing a single character. .PP Then, add a new section (or modify the existing \f(CW\*(C`[password_quality]\*(C'\fR section) like the following: .PP .Vb 3 \& [password_quality] \& policies = krb5\-strength \& policy_libraries = /usr/lib/x86_64-linux-gnu/krb5/plugins/pwqual/strength.so .Ve .PP in either \fIkrb5.conf\fR or \fIkdc.conf\fR. Note that some older versions of Heimdal have a bug in the support for loading modules when \&\f(CW\*(C`policy_libraries\*(C'\fR is set. If you get an error like: .PP .Vb 1 \& didn\*(Aqt find \`kadm5_password_verifier\*(Aq symbol in \`(null)\*(Aq .Ve .PP you may have to omit \f(CW\*(C`policy_libraries\*(C'\fR in your configuration and instead pass the \f(CW\*(C`\-\-check\-library argument\*(C'\fR to \fBkpasswdd\fR specifying the library to load. .PP If you want to also enable history checking, see \fIheimdal\-history\fR\|(1) for further instructions. .SS "\s-1MIT\s0 Kerberos" .IX Subsection "MIT Kerberos" To add this module to the list of password quality checks, add a section to \fIkrb5.conf\fR (or to a separate \fIkdc.conf\fR if you use that) like: .PP .Vb 4 \& [plugins] \& pwqual = { \& module = strength:/usr/lib/x86_64-linux-gnu/krb5/plugins/pwqual/strength.so \& } .Ve .PP to register the plugin. .PP There are two ways to tell where the dictionary is. One option is to use \&\fIkrb5.conf\fR (and in this case you must use \fIkrb5.conf\fR, even if you use a separate \fIkdc.conf\fR file). For this approach, add the following to the \&\f(CW\*(C`[appdefaults]\*(C'\fR section: .PP .Vb 5 \& krb5\-strength = { \& password_dictionary = /path/to/cracklib/dictionary \& password_dictionary_cdb = /path/to/cdb/dictionary.cdb \& password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite \& } .Ve .PP The first setting configures a CrackLib dictionary, the second a \s-1CDB\s0 dictionary, and the third a SQLite dictionary. The provided path should be the full path to the dictionary files, omitting the trailing \f(CW\*(C`*.hwm\*(C'\fR, \&\f(CW\*(C`*.pwd\*(C'\fR, and \f(CW\*(C`*.pwi\*(C'\fR extensions for the CrackLib dictionary (but including the extensions for the other types). You can use any combination of the three settings. If you use more than one, CrackLib will be checked first, then \s-1CDB,\s0 and then SQLite as appropriate. .PP When checking against a \s-1CDB\s0 database, the password, the password with the first character removed, the last character removed, the first and last characters removed, the first two characters removed, and the last two characters removed will all be checked against the dictionary. .PP When checking a SQLite database, the password will be rejected if it is within edit distance one of any word in the dictionary, meaning that the database word can be formed from the password by deleting, adding, or changing a single character. .PP The second option is to use the normal \f(CW\*(C`dict_path\*(C'\fR setting. In the \&\f(CW\*(C`[realms]\*(C'\fR section of your \fIkrb5.conf\fR or \fIkdc.conf\fR, under the appropriate realm or realms, specify the path to the dictionary: .PP .Vb 1 \& dict_file = /path/to/cracklib/dictionary .Ve .PP This will be taken as a CrackLib dictionary path, the same as the setting for password_dictionary above. The provided path should be the full path to the dictionary files, omitting the trailing \f(CW\*(C`*.hwm\*(C'\fR, \f(CW\*(C`*.pwd\*(C'\fR, or \&\f(CW\*(C`*.pwi\*(C'\fR extension. However, be aware that, if you use this approach, you will probably want to disable the built-in standard dict pwqual plugin by adding the line: .PP .Vb 1 \& disable = dict .Ve .PP to the \f(CW\*(C`pwqual\*(C'\fR block of the \f(CW\*(C`[plugins]\*(C'\fR section as shown above. Otherwise, it will also try to load a dictionary at the same path to do simple dictionary matching. .PP You can also mix and match these settings, by using \f(CW\*(C`dict_path\*(C'\fR for the CrackLib dictionary path and \fIkrb5.conf\fR for the \s-1CDB\s0 or SQLite dictionary paths. If both settings are used for the CrackLib path, \fIkrb5.conf\fR overrides the \f(CW\*(C`dict_path\*(C'\fR setting (so that \f(CW\*(C`dict_path\*(C'\fR can be used for other password quality modules). There is no way to specify a \s-1CDB\s0 or SQLite dictionary via the \f(CW\*(C`dict_path\*(C'\fR setting. .SS "Other Settings" .IX Subsection "Other Settings" The following additional settings are supported in the \f(CW\*(C`[appdefaults]\*(C'\fR section of \fIkrb5.conf\fR when running under either Heimdal or \s-1MIT\s0 Kerberos. .IP "cracklib_maxlen" 4 .IX Item "cracklib_maxlen" Normally, all passwords are checked with CrackLib if a CrackLib dictionary is defined. However, CrackLib's rules were designed for a world in which most passwords were four to eight characters long, and tends to spuriously reject a lot of passphrases. If this option is set to something other than its default of 0, passwords longer than that length bypass CrackLib checks. (Using a SQLite dictionary for longer passwords is strongly recommended.) .IP "minimum_different" 4 .IX Item "minimum_different" If set to a numeric value, passwords with fewer than this number of unique characters will be rejected. This can be used to reject, for example, passwords that are long strings of the same character or repetitions of small numbers of characters, which may be too easy to guess. .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 (which, for the version embedded in this package, is eight characters). .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 \& [\-:][,...] .Ve .Sp where 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 (without quote marks), or an integer representing a minimum number of character classes. 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, and 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 \f(CW\*(C`minimum_length = 8\*(C'\fR.) .Sp \&\f(CW\*(C`require_classes\*(C'\fR also supports specifying the minimum number of character classes a password should contain. For example: .Sp .Vb 1 \& require_classes = 3 .Ve .Sp would require all passwords to have a minimum of any three of the character classes. .Sp This can also be used with and ranges, as above. For example: .Sp .Vb 1 \& require_classes = 8\-11:3 12\-19:2 .Ve .Sp requires all passwords from 8 to 11 characters contain at least three different character classes, and passwords from 12 to 19 characters contain at least two different character classes. Ranges can overlap, as in the examples above, but this makes less sense when specifying a minimum number of classes. .Sp Minimum numbers of character classes can be combined with specific character classes. For example: .Sp .Vb 1 \& require_classes = symbol,3 .Ve .Sp requires all passwords contain three distinct character classes and must contain a symbol character. .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. .PP You can omit any dictionary setting and only use the above settings, in which case only the above checks and checks for passwords based on the principal will be done, bypassing any dictionary check. (But for that simple style of password strength checking, there are probably better strength checking plugins already available.) .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2016 Russ Allbery .PP Copyright 2006, 2007, 2009, 2010, 2012, 2013, 2014 The Board of Trustees of the Leland Stanford Junior University .PP Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIcracklib\-format\fR\|(8), \fIcracklib\-packer\fR\|(8), \fIheimdal\-strength\fR\|(1), \&\fIkrb5\-strength\-wordlist\fR\|(1)