tools/heimdal-history.1

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   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 turned on, 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-HISTORY 1"
 136 .TH HEIMDAL-HISTORY 1 "2014-03-25" "3.0" "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\-history \- Password history via Heimdal external strength checking
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 \&\fBheimdal-history\fR [\fB\-hmq\fR] [\fB\-b\fR \fItarget-time\fR] [\fB\-d\fR \fIdatabase\fR]
 146     [\fB\-S\fR \fIlength-stats-db\fR] [\fB\-s\fR \fIstrength-program\fR] [\fBprincipal\fR]
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 \&\fBheimdal-history\fR is an implementation of password history via the
 150 Heimdal external password strength checking interface.  It stores separate
 151 history for each principal, hashed using Crypt::PBKDF2 with
 152 randomly-generated salt.  (The randomness is from a weak pseudorandom
 153 number generator, not strongly random.)
 154 .PP
 155 Password history is stored in a BerkeleyDB \s-1DB_HASH\s0 file.  The key is the
 156 principal.  The value is a \s-1JSON\s0 array of objects, each of which has two
 157 keys.  \f(CW\*(C`timestamp\*(C'\fR contains the time when the history entry was added (in
 158 \&\s-1POSIX\s0 seconds since \s-1UNIX\s0 epoch), and \f(CW\*(C`hash\*(C'\fR contains the hash of a
 159 previously-used password in the Crypt::PBKDF2 LDAP-compatible format.
 160 Passwords are hashed using \s-1PBKDF2 \s0(from PKCS#5) with \s-1SHA\-256\s0 as the
 161 underlying hash function using a number of rounds configured in this
 162 script.  See Crypt::PBKDF2 for more information.
 163 .PP
 164 \&\fBheimdal-history\fR also checks password strength before checking history.
 165 It does so by invoking another program that also uses the Heimdal external
 166 password strength checking interface.  By default, it runs
 167 \&\fB/usr/bin/heimdal\-strength\fR.  Only if that program approves the password
 168 does it hash it and check history.
 169 .PP
 170 As with any implementation of the Heimdal external password strength
 171 checking protocol, \fBheimdal-history\fR expects, on standard input:
 172 .PP
 173 .Vb 3
 174 \&    principal: <principal>
 175 \&    new\-password: <password>
 176 \&    end
 177 .Ve
 178 .PP
 179 (with no leading whitespace).  <principal> is the principal changing its
 180 password (passed to the other password strength checking program but
 181 otherwise unused here), and <password> is the new password.  There must
 182 be exactly one space after the colon.  Any subsequent spaces are taken to
 183 be part of the principal or password.
 184 .PP
 185 If invoked as root, \fBheimdal-history\fR will run the external strength
 186 checking program as user \f(CW\*(C`nobody\*(C'\fR and group \f(CW\*(C`nogroup\*(C'\fR, and will check
 187 and write to the history database as user \f(CW\*(C`_history\*(C'\fR and group
 188 \&\f(CW\*(C`_history\*(C'\fR.  These users must exist on the system if it is run as root.
 189 .PP
 190 The result of each password check will be logged to syslog (priority
 191 \&\s-1LOG_INFO,\s0 facility \s-1LOG_AUTH\s0).  Each log line will be a set of key/value
 192 pairs in the format \f(CW\*(C`\f(CIkey\f(CW=\f(CIvalue\f(CW\*(C'\fR.  The keys are:
 193 .IP "action" 4
 194 .IX Item "action"
 195 The action performed (currently always \f(CW\*(C`check\*(C'\fR).
 196 .IP "principal" 4
 197 .IX Item "principal"
 198 The principal for which a password was checked.
 199 .IP "error" 4
 200 .IX Item "error"
 201 An internal error message that did not stop the history check, but which
 202 may indicate that something is wrong with the history database (such as
 203 corrupted entries or invalid hashes).  If this key is present, neither
 204 \&\f(CW\*(C`result\*(C'\fR nor \f(CW\*(C`reason\*(C'\fR will be present.  There will be a subsequent log
 205 message from the same invocation giving the final result of the history
 206 check (assuming \fBheimdal-history\fR doesn't exit with a fatal error).
 207 .IP "result" 4
 208 .IX Item "result"
 209 Either \f(CW\*(C`accepted\*(C'\fR or \f(CW\*(C`rejected\*(C'\fR.
 210 .IP "reason" 4
 211 .IX Item "reason"
 212 If the password was rejected, the reason for the rejection.
 213 .PP
 214 The value will be surrounded with double quotes if it contains a double
 215 quote or space.  Any double quotes in the value will be doubled, so \f(CW\*(C`"\*(C'\fR
 216 becomes \f(CW""\fR.
 217 .SH "OPTIONS"
 218 .IX Header "OPTIONS"
 219 .IP "\fB\-b\fR \fItarget-time\fR, \fB\-\-benchmark\fR=\fItarget-time\fR" 4
 220 .IX Item "-b target-time, --benchmark=target-time"
 221 Do not do a password history check.  Instead, benchmark the hash algorithm
 222 with various possible iteration counts and find an iteration count that
 223 results in \fItarget-time\fR seconds of computation time required to hash a
 224 password (which should be a real number).  A result will be considered
 225 acceptable if it is within 0.005 seconds of the target time.  The results
 226 will be printed to standard output and then \fBheimdal-history\fR will exit
 227 successfully.
 228 .IP "\fB\-d\fR \fIdatabase\fR, \fB\-\-database\fR=\fIdatabase\fR" 4
 229 .IX Item "-d database, --database=database"
 230 Use \fIdatabase\fR as the history database file instead of the default
 231 (\fI/var/lib/heimdal\-history/history.db\fR).  Primarily used for testing,
 232 since Heimdal won't pass this argument.
 233 .IP "\fB\-h\fR, \fB\-\-help\fR" 4
 234 .IX Item "-h, --help"
 235 Print a short usage message and exit.
 236 .IP "\fB\-m\fR, \fB\-\-manual\fR, \fB\-\-man\fR" 4
 237 .IX Item "-m, --manual, --man"
 238 Display this manual and exit.
 239 .IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
 240 .IX Item "-q, --quiet"
 241 Suppress logging to syslog and only return the results on standard output
 242 and standard error.  Primarily used for testing, since Heimdal won't pass
 243 this argument.
 244 .IP "\fB\-S\fR \fIlength-stats-db\fR, \fB\-\-stats\fR=\fIlength-stats-db\fR" 4
 245 .IX Item "-S length-stats-db, --stats=length-stats-db"
 246 Use \fIlength-stats-db\fR as the database file for password length statistics
 247 instead of the default (\fI/var/lib/heimdal\-history/lengths.db\fR).
 248 Primarily used for testing, since Heimdal won't pass this argument.
 249 .IP "\fB\-s\fR \fIstrength-program\fR, \fB\-\-strength\fR=\fIstrength-program\fR" 4
 250 .IX Item "-s strength-program, --strength=strength-program"
 251 Run \fIstrength-program\fR as the external strength-checking program instead
 252 of the default (\fI/usr/bin/heimdal\-strength\fR).  Primarily used for
 253 testing, since Heimdal won't pass this argument.
 254 .SH "RETURN STATUS"
 255 .IX Header "RETURN STATUS"
 256 On approval of the password, \fBheimdal-history\fR will print \f(CW\*(C`APPROVED\*(C'\fR and
 257 a newline to standard output and exit with status 0.
 258 .PP
 259 If the password is rejected by the strength checking program or if it (or
 260 a version with a single character removed) matches one of the hashes stored
 261 in the password history, \fBheimdal-history\fR will print the reason for
 262 rejection to standard error and exit with status 0.
 263 .PP
 264 On any internal error, \fBheimdal-history\fR will print the error to standard
 265 error and exit with a non-zero status.
 266 .SH "FILES"
 267 .IX Header "FILES"
 268 .IP "\fI/usr/bin/heimdal\-strength\fR" 4
 269 .IX Item "/usr/bin/heimdal-strength"
 270 The default password strength checking program.  This program must follow
 271 the Heimdal external password strength checking \s-1API.\s0
 272 .IP "\fI/var/lib/heimdal\-history/history.db\fR" 4
 273 .IX Item "/var/lib/heimdal-history/history.db"
 274 The default database path.  If \fBheimdal-strength\fR is run as root, this
 275 file needs to be readable and writable by user \f(CW\*(C`_history\*(C'\fR and group
 276 \&\f(CW\*(C`_history\*(C'\fR.  If it doesn't exist, it will be created with mode 0600.
 277 .IP "\fI/var/lib/heimdal\-history/history.db.lock\fR" 4
 278 .IX Item "/var/lib/heimdal-history/history.db.lock"
 279 The lock file used to synchronize access to the history database.  As with
 280 the history database, if \fBheimdal-strength\fR is run as root, this file
 281 needs to be readable and writable by user \f(CW\*(C`_history\*(C'\fR and group
 282 \&\f(CW\*(C`_history\*(C'\fR.
 283 .IP "\fI/var/lib/heimdal\-history/lengths.db\fR" 4
 284 .IX Item "/var/lib/heimdal-history/lengths.db"
 285 The default length statistics path, which will be a BerkeleyDB \s-1DB_HASH\s0
 286 file of password lengths to counts of passwords with that length.  If
 287 \&\fBheimdal-strength\fR is run as root, this file needs to be readable and
 288 writable by user \f(CW\*(C`_history\*(C'\fR and group \f(CW\*(C`_history\*(C'\fR.  If it doesn't exist,
 289 it will be created with mode 0600.
 290 .IP "\fI/var/lib/heimdal\-history/lengths.db.lock\fR" 4
 291 .IX Item "/var/lib/heimdal-history/lengths.db.lock"
 292 The lock file used to synchronize access to the length statistics
 293 database.  As with the length statistics database, if \fBheimdal-strength\fR
 294 is run as root, this file needs to be readable and writable by user
 295 \&\f(CW\*(C`_history\*(C'\fR and group \f(CW\*(C`_history\*(C'\fR.
 296 .SH "AUTHOR"
 297 .IX Header "AUTHOR"
 298 Russ Allbery <eagle@eyrie.org>
 299 .SH "COPYRIGHT AND LICENSE"
 300 .IX Header "COPYRIGHT AND LICENSE"
 301 Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
 302 University
 303 .PP
 304 Permission is hereby granted, free of charge, to any person obtaining a
 305 copy of this software and associated documentation files (the \*(L"Software\*(R"),
 306 to deal in the Software without restriction, including without limitation
 307 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 308 and/or sell copies of the Software, and to permit persons to whom the
 309 Software is furnished to do so, subject to the following conditions:
 310 .PP
 311 The above copyright notice and this permission notice shall be included in
 312 all copies or substantial portions of the Software.
 313 .PP
 314 \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 315 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 316 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 317 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 318 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 319 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 320 DEALINGS IN THE SOFTWARE.\s0
 321 .SH "SEE ALSO"
 322 .IX Header "SEE ALSO"
 323 Crypt::PBKDF2, \fIheimdal\-strength\fR\|(1)