tools/heimdal-history.1

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "HEIMDAL-HISTORY 1"
 132 .TH HEIMDAL-HISTORY 1 "2016-12-25" "3.1" "krb5-strength"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 heimdal\-history \- Password history via Heimdal external strength checking
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 \&\fBheimdal-history\fR [\fB\-hmq\fR] [\fB\-b\fR \fItarget-time\fR] [\fB\-d\fR \fIdatabase\fR]
 142     [\fB\-S\fR \fIlength-stats-db\fR] [\fB\-s\fR \fIstrength-program\fR] [\fBprincipal\fR]
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 \&\fBheimdal-history\fR is an implementation of password history via the
 146 Heimdal external password strength checking interface.  It stores separate
 147 history for each principal, hashed using Crypt::PBKDF2 with
 148 randomly-generated salt.  (The randomness is from a weak pseudorandom
 149 number generator, not strongly random.)
 150 .PP
 151 Password history is stored in a BerkeleyDB \s-1DB_HASH\s0 file.  The key is the
 152 principal.  The value is a \s-1JSON\s0 array of objects, each of which has two
 153 keys.  \f(CW\*(C`timestamp\*(C'\fR contains the time when the history entry was added (in
 154 \&\s-1POSIX\s0 seconds since \s-1UNIX\s0 epoch), and \f(CW\*(C`hash\*(C'\fR contains the hash of a
 155 previously-used password in the Crypt::PBKDF2 LDAP-compatible format.
 156 Passwords are hashed using \s-1PBKDF2 \s0(from PKCS#5) with \s-1SHA\-256\s0 as the
 157 underlying hash function using a number of rounds configured in this
 158 script.  See Crypt::PBKDF2 for more information.
 159 .PP
 160 \&\fBheimdal-history\fR also checks password strength before checking history.
 161 It does so by invoking another program that also uses the Heimdal external
 162 password strength checking interface.  By default, it runs
 163 \&\fB/usr/bin/heimdal\-strength\fR.  Only if that program approves the password
 164 does it hash it and check history.
 165 .PP
 166 For more information on how to set up password history, see
 167 \&\*(L"\s-1CONFIGURATION\*(R"\s0 below.
 168 .PP
 169 As with any implementation of the Heimdal external password strength
 170 checking protocol, \fBheimdal-history\fR expects, on standard input:
 171 .PP
 172 .Vb 3
 173 \&    principal: <principal>
 174 \&    new\-password: <password>
 175 \&    end
 176 .Ve
 177 .PP
 178 (with no leading whitespace).  <principal> is the principal changing its
 179 password (passed to the other password strength checking program but
 180 otherwise unused here), and <password> is the new password.  There must
 181 be exactly one space after the colon.  Any subsequent spaces are taken to
 182 be part of the principal or password.
 183 .PP
 184 If invoked as root, \fBheimdal-history\fR will run the external strength
 185 checking program as user \f(CW\*(C`nobody\*(C'\fR and group \f(CW\*(C`nogroup\*(C'\fR, and will check
 186 and write to the history database as user \f(CW\*(C`_history\*(C'\fR and group
 187 \&\f(CW\*(C`_history\*(C'\fR.  These users must exist on the system if it is run as root.
 188 .PP
 189 The result of each password check will be logged to syslog (priority
 190 \&\s-1LOG_INFO,\s0 facility \s-1LOG_AUTH\s0).  Each log line will be a set of key/value
 191 pairs in the format \f(CW\*(C`\f(CIkey\f(CW=\f(CIvalue\f(CW\*(C'\fR.  The keys are:
 192 .IP "action" 4
 193 .IX Item "action"
 194 The action performed (currently always \f(CW\*(C`check\*(C'\fR).
 195 .IP "principal" 4
 196 .IX Item "principal"
 197 The principal for which a password was checked.
 198 .IP "error" 4
 199 .IX Item "error"
 200 An internal error message that did not stop the history check, but which
 201 may indicate that something is wrong with the history database (such as
 202 corrupted entries or invalid hashes).  If this key is present, neither
 203 \&\f(CW\*(C`result\*(C'\fR nor \f(CW\*(C`reason\*(C'\fR will be present.  There will be a subsequent log
 204 message from the same invocation giving the final result of the history
 205 check (assuming \fBheimdal-history\fR doesn't exit with a fatal error).
 206 .IP "result" 4
 207 .IX Item "result"
 208 Either \f(CW\*(C`accepted\*(C'\fR or \f(CW\*(C`rejected\*(C'\fR.
 209 .IP "reason" 4
 210 .IX Item "reason"
 211 If the password was rejected, the reason for the rejection.
 212 .PP
 213 The value will be surrounded with double quotes if it contains a double
 214 quote or space.  Any double quotes in the value will be doubled, so \f(CW\*(C`"\*(C'\fR
 215 becomes \f(CW""\fR.
 216 .SH "OPTIONS"
 217 .IX Header "OPTIONS"
 218 .IP "\fB\-b\fR \fItarget-time\fR, \fB\-\-benchmark\fR=\fItarget-time\fR" 4
 219 .IX Item "-b target-time, --benchmark=target-time"
 220 Do not do a password history check.  Instead, benchmark the hash algorithm
 221 with various possible iteration counts and find an iteration count that
 222 results in \fItarget-time\fR seconds of computation time required to hash a
 223 password (which should be a real number).  A result will be considered
 224 acceptable if it is within 0.005 seconds of the target time.  The results
 225 will be printed to standard output and then \fBheimdal-history\fR will exit
 226 successfully.
 227 .IP "\fB\-d\fR \fIdatabase\fR, \fB\-\-database\fR=\fIdatabase\fR" 4
 228 .IX Item "-d database, --database=database"
 229 Use \fIdatabase\fR as the history database file instead of the default
 230 (\fI/var/lib/heimdal\-history/history.db\fR).  Primarily used for testing,
 231 since Heimdal won't pass this argument.
 232 .IP "\fB\-h\fR, \fB\-\-help\fR" 4
 233 .IX Item "-h, --help"
 234 Print a short usage message and exit.
 235 .IP "\fB\-m\fR, \fB\-\-manual\fR, \fB\-\-man\fR" 4
 236 .IX Item "-m, --manual, --man"
 237 Display this manual and exit.
 238 .IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
 239 .IX Item "-q, --quiet"
 240 Suppress logging to syslog and only return the results on standard output
 241 and standard error.  Primarily used for testing, since Heimdal won't pass
 242 this argument.
 243 .IP "\fB\-S\fR \fIlength-stats-db\fR, \fB\-\-stats\fR=\fIlength-stats-db\fR" 4
 244 .IX Item "-S length-stats-db, --stats=length-stats-db"
 245 Use \fIlength-stats-db\fR as the database file for password length statistics
 246 instead of the default (\fI/var/lib/heimdal\-history/lengths.db\fR).
 247 Primarily used for testing, since Heimdal won't pass this argument.
 248 .IP "\fB\-s\fR \fIstrength-program\fR, \fB\-\-strength\fR=\fIstrength-program\fR" 4
 249 .IX Item "-s strength-program, --strength=strength-program"
 250 Run \fIstrength-program\fR as the external strength-checking program instead
 251 of the default (\fI/usr/bin/heimdal\-strength\fR).  Primarily used for
 252 testing, since Heimdal won't pass this argument.
 253 .SH "CONFIGURATION"
 254 .IX Header "CONFIGURATION"
 255 Additional setup is required to use this history implementation with your
 256 Heimdal \s-1KDC.\s0
 257 .PP
 258 First, ensure that its dependencies are installed, and then examine the
 259 local configuration settings at the top of the \fBheimdal-history\fR program.
 260 By default, it requires a \f(CW\*(C`_history\*(C'\fR user and \f(CW\*(C`_history\*(C'\fR group be
 261 present on the system, and all history information will be read and
 262 written as that user and group.  It also requires a \f(CW\*(C`nobody\*(C'\fR user and
 263 \&\f(CW\*(C`nogroup\*(C'\fR group to be present (this should be the default with most
 264 variants of \s-1UNIX\s0), and all strength checking will be done as that user and
 265 group.  It uses various files in \fI/var/lib/heimdal\-history\fR to store
 266 history and statistical information by default, so if using the defaults,
 267 create that directory and ensure it is writable by the \f(CW\*(C`_history\*(C'\fR user.
 268 .PP
 269 Once that setup is done, change your \f(CW\*(C`[password_quality]\*(C'\fR configuration
 270 in \fIkrb5.conf\fR or \fIkdc.conf\fR to:
 271 .PP
 272 .Vb 3
 273 \&    [password_quality]
 274 \&        policies         = external\-check
 275 \&        external_program = /usr/local/bin/heimdal\-history
 276 .Ve
 277 .PP
 278 The \fBheimdal-history\fR program will automatically also run
 279 \&\fBheimdal-strength\fR as well, looking for it in \fI/usr/bin\fR.  Change the
 280 \&\f(CW$STRENGTH_PROGRAM\fR setting at the top of the script if you have that
 281 program in a different location.  You should continue to configure
 282 \&\fBheimdal-strength\fR as if you were running it directly.
 283 .SH "RETURN STATUS"
 284 .IX Header "RETURN STATUS"
 285 On approval of the password, \fBheimdal-history\fR will print \f(CW\*(C`APPROVED\*(C'\fR and
 286 a newline to standard output and exit with status 0.
 287 .PP
 288 If the password is rejected by the strength checking program or if it (or
 289 a version with a single character removed) matches one of the hashes stored
 290 in the password history, \fBheimdal-history\fR will print the reason for
 291 rejection to standard error and exit with status 0.
 292 .PP
 293 On any internal error, \fBheimdal-history\fR will print the error to standard
 294 error and exit with a non-zero status.
 295 .SH "FILES"
 296 .IX Header "FILES"
 297 .IP "\fI/usr/bin/heimdal\-strength\fR" 4
 298 .IX Item "/usr/bin/heimdal-strength"
 299 The default password strength checking program.  This program must follow
 300 the Heimdal external password strength checking \s-1API.\s0
 301 .IP "\fI/var/lib/heimdal\-history/history.db\fR" 4
 302 .IX Item "/var/lib/heimdal-history/history.db"
 303 The default database path.  If \fBheimdal-strength\fR is run as root, this
 304 file needs to be readable and writable by user \f(CW\*(C`_history\*(C'\fR and group
 305 \&\f(CW\*(C`_history\*(C'\fR.  If it doesn't exist, it will be created with mode 0600.
 306 .IP "\fI/var/lib/heimdal\-history/history.db.lock\fR" 4
 307 .IX Item "/var/lib/heimdal-history/history.db.lock"
 308 The lock file used to synchronize access to the history database.  As with
 309 the history database, if \fBheimdal-strength\fR is run as root, this file
 310 needs to be readable and writable by user \f(CW\*(C`_history\*(C'\fR and group
 311 \&\f(CW\*(C`_history\*(C'\fR.
 312 .IP "\fI/var/lib/heimdal\-history/lengths.db\fR" 4
 313 .IX Item "/var/lib/heimdal-history/lengths.db"
 314 The default length statistics path, which will be a BerkeleyDB \s-1DB_HASH\s0
 315 file of password lengths to counts of passwords with that length.  If
 316 \&\fBheimdal-strength\fR is run as root, this file needs to be readable and
 317 writable by user \f(CW\*(C`_history\*(C'\fR and group \f(CW\*(C`_history\*(C'\fR.  If it doesn't exist,
 318 it will be created with mode 0600.
 319 .IP "\fI/var/lib/heimdal\-history/lengths.db.lock\fR" 4
 320 .IX Item "/var/lib/heimdal-history/lengths.db.lock"
 321 The lock file used to synchronize access to the length statistics
 322 database.  As with the length statistics database, if \fBheimdal-strength\fR
 323 is run as root, this file needs to be readable and writable by user
 324 \&\f(CW\*(C`_history\*(C'\fR and group \f(CW\*(C`_history\*(C'\fR.
 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 2013, 2014 The Board of Trustees of the Leland Stanford Junior
 333 University
 334 .PP
 335 Permission is hereby granted, free of charge, to any person obtaining a
 336 copy of this software and associated documentation files (the \*(L"Software\*(R"),
 337 to deal in the Software without restriction, including without limitation
 338 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 339 and/or sell copies of the Software, and to permit persons to whom the
 340 Software is furnished to do so, subject to the following conditions:
 341 .PP
 342 The above copyright notice and this permission notice shall be included in
 343 all copies or substantial portions of the Software.
 344 .PP
 345 \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 346 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 347 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 348 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 349 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 350 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 351 DEALINGS IN THE SOFTWARE.\s0
 352 .SH "SEE ALSO"
 353 .IX Header "SEE ALSO"
 354 Crypt::PBKDF2, \fIheimdal\-strength\fR\|(1)