]> eyrie.org Git - kerberos/krb5-strength.git/blob - docs/krb5-strength.5.in
New upstream version 3.2
[kerberos/krb5-strength.git] / docs / krb5-strength.5.in
1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 .    ds C`
42 .    ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el       .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
60 .    if \nF \{\
61 .        de IX
62 .        tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 .        if !\nF==2 \{\
65 .            nr % 0
66 .            nr F 2
67 .        \}
68 .    \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
74 .    \" fudge factors for nroff and troff
75 .if n \{\
76 .    ds #H 0
77 .    ds #V .8m
78 .    ds #F .3m
79 .    ds #[ \f1
80 .    ds #] \fP
81 .\}
82 .if t \{\
83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 .    ds #V .6m
85 .    ds #F 0
86 .    ds #[ \&
87 .    ds #] \&
88 .\}
89 .    \" simple accents for nroff and troff
90 .if n \{\
91 .    ds ' \&
92 .    ds ` \&
93 .    ds ^ \&
94 .    ds , \&
95 .    ds ~ ~
96 .    ds /
97 .\}
98 .if t \{\
99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 .    \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 .    \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 .    \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 .    ds : e
123 .    ds 8 ss
124 .    ds o a
125 .    ds d- d\h'-1'\(ga
126 .    ds D- D\h'-1'\(hy
127 .    ds th \o'bp'
128 .    ds Th \o'LP'
129 .    ds ae ae
130 .    ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "KRB5-STRENGTH 5"
136 .TH KRB5-STRENGTH 5 "2020-05-17" "3.2" "krb5-strength"
137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 krb5\-strength \- Kerberos password strength checking plugin
143 .SH "SYNOPSIS"
144 .IX Header "SYNOPSIS"
145 \&\s-1MIT\s0 Kerberos:
146 .PP
147 .Vb 4
148 \&    [plugins]
149 \&      pwqual = {
150 \&        module = strength:@moduledir@/strength.so
151 \&      }
152 .Ve
153 .PP
154 Heimdal:
155 .PP
156 .Vb 3
157 \&    [password_quality]
158 \&        policies         = krb5\-strength
159 \&        policy_libraries = @moduledir@/strength.so
160 .Ve
161 .SH "DESCRIPTION"
162 .IX Header "DESCRIPTION"
163 \&\fIstrength.so\fR is a \s-1KDC\s0 plugin for Kerberos password strength checking for
164 either \s-1MIT\s0 Kerberos or Heimdal provided as part of the krb5\-strength
165 package.  For \s-1MIT\s0 Kerberos KDCs (or, more to the point, kadmind servers),
166 this plugin is the recommended way of enabling strength checking.  For
167 Heimdal KDCs, you normally should use the \fBheimdal-strength\fR external
168 program instead, but the plugin is a supported option if you want to avoid
169 external programs for some reason.
170 .PP
171 For this module to be effective for either Heimdal or \s-1MIT\s0 Kerberos, you
172 will also need to construct a dictionary.  What type of dictionary you
173 create depends on what backends you want to use: CrackLib, \s-1CDB,\s0 or SQLite.
174 .PP
175 For CrackLib, on Debian systems, you can install the cracklib-runtime
176 package and use the \fBcracklib-format\fR and \fBcracklib-packer\fR utilities
177 that come with it.  The former takes a set of wordlists and outputs a
178 wordlist in the format required by \fBcracklib-packer\fR, and the latter
179 turns this into a CrackLib dictionary.  Alternately, you can use the
180 \&\fBmkdict\fR and \fBpacker\fR utilities, which are included in the krb5\-strength
181 package but not installed by default.  You can run them out of the
182 \&\fIcracklib\fR directory of the source tree after building.  (\fBmkdict\fR is
183 the equivalent of \fBcracklib-format\fR.)
184 .PP
185 For building a \s-1CDB\s0 or SQLite dictionary, use \fBkrb5\-strength\-wordlist\fR.
186 .SH "CONFIGURATION"
187 .IX Header "CONFIGURATION"
188 First, build and install either a CrackLib dictionary as described above.
189 The CrackLib dictionary will consist of three files, one each ending in
190 \&\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
191 single files, conventionally ending in \f(CW\*(C`*.cdb\*(C'\fR and \f(CW\*(C`*.sqlite\*(C'\fR
192 respectively.  Install those files somewhere on your system.  Then, follow
193 the relevant instructions below for either \*(L"Heimdal\*(R" or \*(L"\s-1MIT\s0
194 Kerberos\*(R".
195 .PP
196 See \*(L"Other Settings\*(R" below for additional \fIkrb5.conf\fR setting supported
197 by both Heimdal and \s-1MIT\s0 Kerberos.
198 .SS "Heimdal"
199 .IX Subsection "Heimdal"
200 There are two options: using an external password check program, or using
201 the plugin.  I recommend the external password check program unless you
202 encounter speed problems with that approach that cause \fBkpasswd\fR to time
203 out.  If you choose to use the external program, read the
204 \&\fBheimdal-strength\fR documentation instead of this documentation.
205 .PP
206 If using the module, first add a stanza like the following to the
207 \&\f(CW\*(C`[appdefaults]\*(C'\fR section of your \fI/etc/krb5.conf\fR (or wherever your
208 \&\fIkrb5.conf\fR file is located):
209 .PP
210 .Vb 5
211 \&    krb5\-strength = {
212 \&        password_dictionary        = /path/to/cracklib/dictionary
213 \&        password_dictionary_cdb    = /path/to/cdb/dictionary.cdb
214 \&        password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite
215 \&    }
216 .Ve
217 .PP
218 The first setting configures a CrackLib dictionary, the second a \s-1CDB\s0
219 dictionary, and the third a SQLite dictionary.  The provided path should
220 be the full path to the dictionary files, omitting the trailing \f(CW\*(C`*.hwm\*(C'\fR,
221 \&\f(CW\*(C`*.pwd\*(C'\fR, and \f(CW\*(C`*.pwi\*(C'\fR extensions for the CrackLib dictionary (but
222 including the extensions for the other types).  You can use any
223 combination of the three settings.  If you use more than one, CrackLib
224 will be checked first, then \s-1CDB,\s0 and then SQLite as appropriate.
225 .PP
226 When checking against a \s-1CDB\s0 database, the password, the password with the
227 first character removed, the last character removed, the first and last
228 characters removed, the first two characters removed, and the last two
229 characters removed will all be checked against the dictionary.
230 .PP
231 When checking a SQLite database, the password will be rejected if it is
232 within edit distance one of any word in the dictionary, meaning that the
233 database word can be formed from the password by deleting, adding, or
234 changing a single character.
235 .PP
236 Then, add a new section (or modify the existing \f(CW\*(C`[password_quality]\*(C'\fR
237 section) like the following:
238 .PP
239 .Vb 3
240 \&    [password_quality]
241 \&        policies         = krb5\-strength
242 \&        policy_libraries = @moduledir@/strength.so
243 .Ve
244 .PP
245 in either \fIkrb5.conf\fR or \fIkdc.conf\fR.  Note that some older versions of
246 Heimdal have a bug in the support for loading modules when
247 \&\f(CW\*(C`policy_libraries\*(C'\fR is set.  If you get an error like:
248 .PP
249 .Vb 1
250 \&    didn\*(Aqt find \`kadm5_password_verifier\*(Aq symbol in \`(null)\*(Aq
251 .Ve
252 .PP
253 you may have to omit \f(CW\*(C`policy_libraries\*(C'\fR in your configuration and instead
254 pass the \f(CW\*(C`\-\-check\-library argument\*(C'\fR to \fBkpasswdd\fR specifying the library
255 to load.
256 .PP
257 If you want to also enable history checking, see \fBheimdal\-history\fR\|(1) for
258 further instructions.
259 .SS "\s-1MIT\s0 Kerberos"
260 .IX Subsection "MIT Kerberos"
261 To add this module to the list of password quality checks, add a section
262 to \fIkrb5.conf\fR (or to a separate \fIkdc.conf\fR if you use that) like:
263 .PP
264 .Vb 4
265 \&    [plugins]
266 \&      pwqual = {
267 \&        module = strength:@moduledir@/strength.so
268 \&      }
269 .Ve
270 .PP
271 to register the plugin.
272 .PP
273 There are two ways to tell where the dictionary is.  One option is to use
274 \&\fIkrb5.conf\fR (and in this case you must use \fIkrb5.conf\fR, even if you use
275 a separate \fIkdc.conf\fR file).  For this approach, add the following to the
276 \&\f(CW\*(C`[appdefaults]\*(C'\fR section:
277 .PP
278 .Vb 5
279 \&    krb5\-strength = {
280 \&        password_dictionary        = /path/to/cracklib/dictionary
281 \&        password_dictionary_cdb    = /path/to/cdb/dictionary.cdb
282 \&        password_dictionary_sqlite = /path/to/sqlite/dictionary.sqlite
283 \&    }
284 .Ve
285 .PP
286 The first setting configures a CrackLib dictionary, the second a \s-1CDB\s0
287 dictionary, and the third a SQLite dictionary.  The provided path should
288 be the full path to the dictionary files, omitting the trailing \f(CW\*(C`*.hwm\*(C'\fR,
289 \&\f(CW\*(C`*.pwd\*(C'\fR, and \f(CW\*(C`*.pwi\*(C'\fR extensions for the CrackLib dictionary (but
290 including the extensions for the other types).  You can use any
291 combination of the three settings.  If you use more than one, CrackLib
292 will be checked first, then \s-1CDB,\s0 and then SQLite as appropriate.
293 .PP
294 When checking against a \s-1CDB\s0 database, the password, the password with the
295 first character removed, the last character removed, the first and last
296 characters removed, the first two characters removed, and the last two
297 characters removed will all be checked against the dictionary.
298 .PP
299 When checking a SQLite database, the password will be rejected if it is
300 within edit distance one of any word in the dictionary, meaning that the
301 database word can be formed from the password by deleting, adding, or
302 changing a single character.
303 .PP
304 The second option is to use the normal \f(CW\*(C`dict_path\*(C'\fR setting.  In the
305 \&\f(CW\*(C`[realms]\*(C'\fR section of your \fIkrb5.conf\fR or \fIkdc.conf\fR, under the
306 appropriate realm or realms, specify the path to the dictionary:
307 .PP
308 .Vb 1
309 \&    dict_file = /path/to/cracklib/dictionary
310 .Ve
311 .PP
312 This will be taken as a CrackLib dictionary path, the same as the setting
313 for password_dictionary above.  The provided path should be the full path
314 to the dictionary files, omitting the trailing \f(CW\*(C`*.hwm\*(C'\fR, \f(CW\*(C`*.pwd\*(C'\fR, or
315 \&\f(CW\*(C`*.pwi\*(C'\fR extension.  However, be aware that, if you use this approach, you
316 will probably want to disable the built-in standard dict pwqual plugin by
317 adding the line:
318 .PP
319 .Vb 1
320 \&    disable = dict
321 .Ve
322 .PP
323 to the \f(CW\*(C`pwqual\*(C'\fR block of the \f(CW\*(C`[plugins]\*(C'\fR section as shown above.
324 Otherwise, it will also try to load a dictionary at the same path to do
325 simple dictionary matching.
326 .PP
327 You can also mix and match these settings, by using \f(CW\*(C`dict_path\*(C'\fR for the
328 CrackLib dictionary path and \fIkrb5.conf\fR for the \s-1CDB\s0 or SQLite dictionary
329 paths.  If both settings are used for the CrackLib path, \fIkrb5.conf\fR
330 overrides the \f(CW\*(C`dict_path\*(C'\fR setting (so that \f(CW\*(C`dict_path\*(C'\fR can be used for
331 other password quality modules).  There is no way to specify a \s-1CDB\s0 or
332 SQLite dictionary via the \f(CW\*(C`dict_path\*(C'\fR setting.
333 .SS "Other Settings"
334 .IX Subsection "Other Settings"
335 The following additional settings are supported in the \f(CW\*(C`[appdefaults]\*(C'\fR
336 section of \fIkrb5.conf\fR when running under either Heimdal or \s-1MIT\s0 Kerberos.
337 .IP "cracklib_maxlen" 4
338 .IX Item "cracklib_maxlen"
339 Normally, all passwords are checked with CrackLib if a CrackLib dictionary
340 is defined.  However, CrackLib's rules were designed for a world in which
341 most passwords were four to eight characters long, and tends to spuriously
342 reject a lot of passphrases.  If this option is set to something other
343 than its default of 0, passwords longer than that length bypass CrackLib
344 checks.  (Using a SQLite dictionary for longer passwords is strongly
345 recommended.)
346 .IP "minimum_different" 4
347 .IX Item "minimum_different"
348 If set to a numeric value, passwords with fewer than this number of unique
349 characters will be rejected.  This can be used to reject, for example,
350 passwords that are long strings of the same character or repetitions of
351 small numbers of characters, which may be too easy to guess.
352 .IP "minimum_length" 4
353 .IX Item "minimum_length"
354 If set to a numeric value, passwords with fewer than that number of
355 characters will be rejected, independent of any length restrictions in
356 CrackLib.  Note that this setting does not bypass the minimum length
357 requirements in CrackLib itself (which, for the version embedded in this
358 package, is eight characters).
359 .IP "require_ascii_printable" 4
360 .IX Item "require_ascii_printable"
361 If set to a true boolean value, rejects any password that contains
362 non-ASCII characters or \s-1ASCII\s0 control characters.  Spaces are allowed;
363 tabs are not (at least assuming the \s-1POSIX C\s0 locale).  No canonicalization
364 or character set is defined for Kerberos passwords in general, so you may
365 want to reject non-ASCII characters to avoid interoperability problems
366 with computers with different default character sets or Unicode
367 normalization forms.
368 .IP "require_classes" 4
369 .IX Item "require_classes"
370 This option allows specification of more complex character class
371 requirements.  The value of this parameter should be one or more
372 whitespace-separated rule.  Each rule has the syntax:
373 .Sp
374 .Vb 1
375 \&    [<min>\-<max>:]<class>[,<class>...]
376 .Ve
377 .Sp
378 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
379 (without quote marks), or an integer representing a minimum number of
380 character classes.  The symbol class includes all characters other than
381 alphanumeric characters, including space.  The listed classes must appear
382 in the password.  Separate multiple required classes with a comma (and no
383 space).
384 .Sp
385 The character class checks will be done in whatever locale the plugin or
386 password check program is run in, which will normally be the \s-1POSIX C\s0
387 locale but may be different depending on local configuration.
388 .Sp
389 A simple example:
390 .Sp
391 .Vb 1
392 \&    require_classes = upper,lower,digit
393 .Ve
394 .Sp
395 This requires all passwords contain at least one uppercase letter, at
396 least one lowercase letter, and at least one digit.
397 .Sp
398 If present, <min> and <max> specify the minimum password length and
399 maximum password length to which this rule applies.  This allows one to
400 specify character class requirements that change with password length.
401 So, for example:
402 .Sp
403 .Vb 1
404 \&    require_classes = 8\-19:upper,lower 8\-15:digit 8\-11:symbol
405 .Ve
406 .Sp
407 requires all passwords from 8 to 11 characters long contain all four
408 character classes, passwords from 12 to 15 characters long contain upper
409 and lower case and a digit, and passwords from 16 to 19 characters long
410 contain both upper and lower case.  Passwords longer than 20 characters
411 have no character class restrictions.  (This example is probably used in
412 conjunction with \f(CW\*(C`minimum_length = 8\*(C'\fR.)
413 .Sp
414 \&\f(CW\*(C`require_classes\*(C'\fR also supports specifying the minimum number of
415 character classes a password should contain.  For example:
416 .Sp
417 .Vb 1
418 \&    require_classes = 3
419 .Ve
420 .Sp
421 would require all passwords to have a minimum of any three of the
422 character classes.
423 .Sp
424 This can also be used with <min> and <max> ranges, as above.  For example:
425 .Sp
426 .Vb 1
427 \&    require_classes = 8\-11:3 12\-19:2
428 .Ve
429 .Sp
430 requires all passwords from 8 to 11 characters contain at least three
431 different character classes, and passwords from 12 to 19 characters
432 contain at least two different character classes.  Ranges can overlap, as
433 in the examples above, but this makes less sense when specifying a minimum
434 number of classes.
435 .Sp
436 Minimum numbers of character classes can be combined with specific
437 character classes.  For example:
438 .Sp
439 .Vb 1
440 \&    require_classes = symbol,3
441 .Ve
442 .Sp
443 requires all passwords contain three distinct character classes and must
444 contain a symbol character.
445 .IP "require_non_letter" 4
446 .IX Item "require_non_letter"
447 If set to a true boolean value, the password must contain at least one
448 character that is not a letter (uppercase or lowercase) or a space.  This
449 may be helpful in combination with passphrases; users may choose a stock
450 English phrase, and this will force at least some additional complexity.
451 .PP
452 You can omit any dictionary setting and only use the above settings, in
453 which case only the above checks and checks for passwords based on the
454 principal will be done, bypassing any dictionary check.  (But for that
455 simple style of password strength checking, there are probably better
456 strength checking plugins already available.)
457 .SH "AUTHOR"
458 .IX Header "AUTHOR"
459 Russ Allbery <eagle@eyrie.org>
460 .SH "COPYRIGHT AND LICENSE"
461 .IX Header "COPYRIGHT AND LICENSE"
462 Copyright 2016 Russ Allbery <eagle@eyrie.org>
463 .PP
464 Copyright 2006\-2007, 2009\-2010, 2012\-2014 The Board of Trustees of the
465 Leland Stanford Junior University
466 .PP
467 Copying and distribution of this file, with or without modification, are
468 permitted in any medium without royalty provided the copyright notice and
469 this notice are preserved.  This file is offered as-is, without any
470 warranty.
471 .PP
472 SPDX-License-Identifier: \s-1FSFAP\s0
473 .SH "SEE ALSO"
474 .IX Header "SEE ALSO"
475 \&\fBcracklib\-format\fR\|(8), \fBcracklib\-packer\fR\|(8), \fBheimdal\-strength\fR\|(1),
476 \&\fBkrb5\-strength\-wordlist\fR\|(1)