tools/heimdal-strength.1

   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 "HEIMDAL-STRENGTH 1"
 136 .TH HEIMDAL-STRENGTH 1 "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 heimdal\-strength \- Heimdal password quality check embedding CrackLib
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 \&\fBheimdal-strength\fR [\fIprincipal\fR]
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 \&\fBheimdal-strength\fR is an external password quality check program for
 149 Heimdal that verifies the strength of a password.  Passwords can be tested
 150 with CrackLib, checked against a \s-1CDB\s0 database of known weak passwords,
 151 checked for length, checked for non-printable or non-ASCII characters that
 152 may be difficult to enter reproducibly, required to contain particular
 153 character classes, or any combination of these tests.  It is normally run
 154 via \fBkpasswdd\fR\|(8) using the Heimdal password quality check interface rather
 155 than directly.
 156 .PP
 157 To use this program, it must be configured in \fIkrb5.conf\fR via settings
 158 in \f(CW\*(C`[appdefaults]\*(C'\fR for the application name \f(CW\*(C`krb5\-strength\*(C'\fR.  A typical
 159 setting would be:
 160 .PP
 161 .Vb 3
 162 \&    krb5\-strength = {
 163 \&        password_dictionary = /usr/local/lib/kadmind/dictionary
 164 \&    }
 165 .Ve
 166 .PP
 167 which says to check passwords with CrackLib using the given path as the
 168 base path of the CrackLib dictionary.  See \*(L"\s-1CONFIGURATION\*(R"\s0 below for
 169 details on the supported configuration options.
 170 .PP
 171 \&\fBheimdal-strength\fR then expects the Heimdal password quality check
 172 information on standard input, specifically:
 173 .PP
 174 .Vb 3
 175 \&    principal: <principal>
 176 \&    new\-password: <password>
 177 \&    end
 178 .Ve
 179 .PP
 180 where <principal> is the principal whose password would be changed and
 181 <password> is the new password.  If the password appears to be strong, it
 182 prints \f(CW\*(C`APPROVED\*(C'\fR on standard output and exits with a status of 0.  If
 183 the password is rejected as being too weak, it will print the reason for
 184 rejecting the password on standard error and exit with a status of 0.  If
 185 some fatal error occurs, it will print that error to standard error and
 186 exit with a non-zero status.
 187 .SH "CONFIGURATION"
 188 .IX Header "CONFIGURATION"
 189 The following \fIkrb5.conf\fR configuration options are supported:
 190 .IP "cracklib_maxlen" 4
 191 .IX Item "cracklib_maxlen"
 192 Normally, all passwords are checked with CrackLib if a CrackLib dictionary
 193 is defined.  However, CrackLib's rules were designed for a world in which
 194 most passwords were four to eight characters long, and tends to spuriously
 195 reject a lot of passphrases.  If this option is set to something other
 196 than its default of 0, passwords longer than that length bypass CrackLib
 197 checks.  (Using a SQLite dictionary for longer passwords is strongly
 198 recommended.)
 199 .IP "minimum_different" 4
 200 .IX Item "minimum_different"
 201 If set to a numeric value, passwords with fewer than this number of unique
 202 characters will be rejected.  This can be used to reject, for example,
 203 passwords that are long strings of the same character or repetitions of
 204 small numbers of characters, which may be too easy to guess.
 205 .IP "minimum_length" 4
 206 .IX Item "minimum_length"
 207 If set to a numeric value, passwords with fewer than that number of
 208 characters will be rejected, independent of any length restrictions in
 209 CrackLib.  Note that this setting does not bypass the minimum length
 210 requirements in CrackLib itself.
 211 .IP "password_dictionary" 4
 212 .IX Item "password_dictionary"
 213 Specifies the base path to a CrackLib dictionary and enables password
 214 strength testing using CrackLib.  The provided path should be the full
 215 path to the dictionary files, omitting the trailing \fI*.hwm\fR, \fI*.pwd\fR,
 216 and \fI*.pwi\fR extensions for the CrackLib dictionary.
 217 .IP "password_dictionary_cdb" 4
 218 .IX Item "password_dictionary_cdb"
 219 Specifies the base path to a \s-1CDB\s0 dictionary and enables \s-1CDB\s0 password
 220 dictionary lookups.  The path must point to a CDB-format database whose
 221 keys are the known passwords or dictionary words.  The values are ignored.
 222 You can use the \fBkrb5\-strength\-wordlist\fR utility to generate the \s-1CDB\s0
 223 database from a word list.
 224 .Sp
 225 The \s-1CDB\s0 dictionary lookups do not do the complex password mangling that
 226 CrackLib does.  Instead, the password itself will be checked against the
 227 dictionary, and then variations of the password formed by removing the
 228 first character, the last character, the first and last characters, the
 229 first two characters, and the last two characters.  If any of these
 230 strings are found in the \s-1CDB\s0 database, the password will be rejected;
 231 otherwise, it will be accepted, at least by this check.
 232 .Sp
 233 A CrackLib dictionary, a \s-1CDB\s0 dictionary, and a SQLite dictionary may all
 234 be configured at the same time or in any combination, in which case
 235 CrackLib will be run first, followed by \s-1CDB\s0 and then SQLite as
 236 appropriate.
 237 .IP "password_dictionary_sqlite" 4
 238 .IX Item "password_dictionary_sqlite"
 239 Specifies the base path to a SQLite dictionary and enables SQLite password
 240 dictionary lookups.  The path must point to a SQLite 3 database with a
 241 table named \f(CW\*(C`passwords\*(C'\fR.  This table should have two columns, \f(CW\*(C`password\*(C'\fR
 242 and \f(CW\*(C`drowssap\*(C'\fR, which, for each dictionary word, holds the word and the
 243 reversed form of the word.  You can use the \fBkrb5\-strength\-wordlist\fR
 244 utility to generate the SQLite database from a word list.
 245 .Sp
 246 The SQLite dictionary lookups do not do the complex password mangling that
 247 CrackLib does, but they will detect and reject any password that is within
 248 edit distance one of a word in the dictionary, meaning that the dictionary
 249 word can be formed from the password by adding, deleting, or modifying a
 250 single character.
 251 .Sp
 252 A CrackLib dictionary, a \s-1CDB\s0 dictionary, and a SQLite dictionary may all
 253 be configured at the same time or in any combination, in which case
 254 CrackLib will be run first, followed by \s-1CDB\s0 and then SQLite as
 255 appropriate.
 256 .IP "require_ascii_printable" 4
 257 .IX Item "require_ascii_printable"
 258 If set to a true boolean value, rejects any password that contains
 259 non-ASCII characters or \s-1ASCII\s0 control characters.  Spaces are allowed;
 260 tabs are not (at least assuming the \s-1POSIX C\s0 locale).  No canonicalization
 261 or character set is defined for Kerberos passwords in general, so you may
 262 want to reject non-ASCII characters to avoid interoperability problems
 263 with computers with different default character sets or Unicode
 264 normalization forms.
 265 .IP "require_classes" 4
 266 .IX Item "require_classes"
 267 This option allows specification of more complex character class
 268 requirements.  The value of this parameter should be one or more
 269 whitespace-separated rule.  Each rule has the syntax:
 270 .Sp
 271 .Vb 1
 272 \&    [<min>\-<max>:]<class>[,<class>...]
 273 .Ve
 274 .Sp
 275 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
 276 symbol class includes all characters other than alphanumeric characters,
 277 including space.  The listed classes must appear in the password.
 278 Separate multiple required classes with a comma (and no space).
 279 .Sp
 280 The character class checks will be done in whatever locale the plugin or
 281 password check program is run in, which will normally be the \s-1POSIX C\s0
 282 locale but may be different depending on local configuration.
 283 .Sp
 284 A simple example:
 285 .Sp
 286 .Vb 1
 287 \&    require_classes = upper,lower,digit
 288 .Ve
 289 .Sp
 290 This requires all passwords contain at least one uppercase letter, at
 291 least one lowercase letter, and at least one digit.
 292 .Sp
 293 If present, <min> and <max> specify the minimum password length and
 294 maximum password length to which this rule applies.  This allows one to
 295 specify character class requirements that change with password length.
 296 So, for example:
 297 .Sp
 298 .Vb 1
 299 \&    require_classes = 8\-19:upper,lower 8\-15:digit 8\-11:symbol
 300 .Ve
 301 .Sp
 302 requires all passwords from 8 to 11 characters long contain all four
 303 character classes, passwords from 12 to 15 characters long contain upper
 304 and lower case and a digit, and passwords from 16 to 19 characters long
 305 contain both upper and lower case.  Passwords longer than 20 characters
 306 have no character class restrictions.  (This example is probably used in
 307 conjunction with minimum_length = 8.)
 308 .IP "require_non_letter" 4
 309 .IX Item "require_non_letter"
 310 If set to a true boolean value, the password must contain at least one
 311 character that is not a letter (uppercase or lowercase) or a space.  This
 312 may be helpful in combination with passphrases; users may choose a stock
 313 English phrase, and this will force at least some additional complexity.
 314 .SH "SEE ALSO"
 315 .IX Header "SEE ALSO"
 316 \&\fBkrb5\-strength\-wordlist\fR\|(1), \fBkadm5\-strength\fR\|(3), \fBkpasswdd\fR\|(8), \fBkrb5.conf\fR\|(5)
 317 .PP
 318 The \*(L"Password changing\*(R" section of the Heimdal info documentation
 319 describes the interface that this program implements and how to configure
 320 Heimdal to use it.
 321 .PP
 322 The current version of this program is available from its web page at
 323 <https://www.eyrie.org/~eagle/software/krb5\-strength/> as part of the
 324 krb5\-strength package.
 325 .SH "AUTHOR"
 326 .IX Header "AUTHOR"
 327 Russ Allbery <eagle@eyrie.org>
 328 .SH "COPYRIGHT AND LICENSE"
 329 .IX Header "COPYRIGHT AND LICENSE"
 330 Copyright 2016 Russ Allbery <eagle@eyrie.org>
 331 .PP
 332 Copyright 2010, 2013\-2014 The Board of Trustees of the Leland Stanford
 333 Junior University
 334 .PP
 335 Copying and distribution of this file, with or without modification, are
 336 permitted in any medium without royalty provided the copyright notice and
 337 this notice are preserved.  This file is offered as-is, without any
 338 warranty.
 339 .PP
 340 SPDX-License-Identifier: \s-1FSFAP\s0