.\" 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 "HEIMDAL-HISTORY 1"
.TH HEIMDAL-HISTORY 1 "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"
heimdal\-history \- Password history via Heimdal external strength checking
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBheimdal-history\fR [\fB\-hmq\fR] [\fB\-b\fR \fItarget-time\fR] [\fB\-d\fR \fIdatabase\fR]
    [\fB\-S\fR \fIlength-stats-db\fR] [\fB\-s\fR \fIstrength-program\fR] [\fBprincipal\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBheimdal-history\fR is an implementation of password history via the
Heimdal external password strength checking interface.  It stores separate
history for each principal, hashed using Crypt::PBKDF2 with
randomly-generated salt.  (The randomness is from a weak pseudorandom
number generator, not strongly random.)
.PP
Password history is stored in a BerkeleyDB \s-1DB_HASH\s0 file.  The key is the
principal.  The value is a \s-1JSON\s0 array of objects, each of which has two
keys.  \f(CW\*(C`timestamp\*(C'\fR contains the time when the history entry was added (in
\&\s-1POSIX\s0 seconds since \s-1UNIX\s0 epoch), and \f(CW\*(C`hash\*(C'\fR contains the hash of a
previously-used password in the Crypt::PBKDF2 LDAP-compatible format.
Passwords are hashed using \s-1PBKDF2\s0 (from PKCS#5) with \s-1SHA\-256\s0 as the
underlying hash function using a number of rounds configured in this
script.  See Crypt::PBKDF2 for more information.
.PP
\&\fBheimdal-history\fR also checks password strength before checking history.
It does so by invoking another program that also uses the Heimdal external
password strength checking interface.  By default, it runs
\&\fB/usr/bin/heimdal\-strength\fR.  Only if that program approves the password
does it hash it and check history.
.PP
For more information on how to set up password history, see
\&\*(L"\s-1CONFIGURATION\*(R"\s0 below.
.PP
As with any implementation of the Heimdal external password strength
checking protocol, \fBheimdal-history\fR expects, on standard input:
.PP
.Vb 3
\&    principal: <principal>
\&    new\-password: <password>
\&    end
.Ve
.PP
(with no leading whitespace).  <principal> is the principal changing its
password (passed to the other password strength checking program but
otherwise unused here), and <password> is the new password.  There must
be exactly one space after the colon.  Any subsequent spaces are taken to
be part of the principal or password.
.PP
If invoked as root, \fBheimdal-history\fR will run the external strength
checking program as user \f(CW\*(C`nobody\*(C'\fR and group \f(CW\*(C`nogroup\*(C'\fR, and will check
and write to the history database as user \f(CW\*(C`_history\*(C'\fR and group
\&\f(CW\*(C`_history\*(C'\fR.  These users must exist on the system if it is run as root.
.PP
The result of each password check will be logged to syslog (priority
\&\s-1LOG_INFO,\s0 facility \s-1LOG_AUTH\s0).  Each log line will be a set of key/value
pairs in the format \f(CW\*(C`\f(CIkey\f(CW=\f(CIvalue\f(CW\*(C'\fR.  The keys are:
.IP "action" 4
.IX Item "action"
The action performed (currently always \f(CW\*(C`check\*(C'\fR).
.IP "principal" 4
.IX Item "principal"
The principal for which a password was checked.
.IP "error" 4
.IX Item "error"
An internal error message that did not stop the history check, but which
may indicate that something is wrong with the history database (such as
corrupted entries or invalid hashes).  If this key is present, neither
\&\f(CW\*(C`result\*(C'\fR nor \f(CW\*(C`reason\*(C'\fR will be present.  There will be a subsequent log
message from the same invocation giving the final result of the history
check (assuming \fBheimdal-history\fR doesn't exit with a fatal error).
.IP "result" 4
.IX Item "result"
Either \f(CW\*(C`accepted\*(C'\fR or \f(CW\*(C`rejected\*(C'\fR.
.IP "reason" 4
.IX Item "reason"
If the password was rejected, the reason for the rejection.
.PP
The value will be surrounded with double quotes if it contains a double
quote or space.  Any double quotes in the value will be doubled, so \f(CW\*(C`"\*(C'\fR
becomes \f(CW""\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-b\fR \fItarget-time\fR, \fB\-\-benchmark\fR=\fItarget-time\fR" 4
.IX Item "-b target-time, --benchmark=target-time"
Do not do a password history check.  Instead, benchmark the hash algorithm
with various possible iteration counts and find an iteration count that
results in \fItarget-time\fR seconds of computation time required to hash a
password (which should be a real number).  A result will be considered
acceptable if it is within 0.005 seconds of the target time.  The results
will be printed to standard output and then \fBheimdal-history\fR will exit
successfully.
.IP "\fB\-d\fR \fIdatabase\fR, \fB\-\-database\fR=\fIdatabase\fR" 4
.IX Item "-d database, --database=database"
Use \fIdatabase\fR as the history database file instead of the default
(\fI/var/lib/heimdal\-history/history.db\fR).  Primarily used for testing,
since Heimdal won't pass this argument.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Print a short usage message and exit.
.IP "\fB\-m\fR, \fB\-\-manual\fR, \fB\-\-man\fR" 4
.IX Item "-m, --manual, --man"
Display this manual and exit.
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
.IX Item "-q, --quiet"
Suppress logging to syslog and only return the results on standard output
and standard error.  Primarily used for testing, since Heimdal won't pass
this argument.
.IP "\fB\-S\fR \fIlength-stats-db\fR, \fB\-\-stats\fR=\fIlength-stats-db\fR" 4
.IX Item "-S length-stats-db, --stats=length-stats-db"
Use \fIlength-stats-db\fR as the database file for password length statistics
instead of the default (\fI/var/lib/heimdal\-history/lengths.db\fR).
Primarily used for testing, since Heimdal won't pass this argument.
.IP "\fB\-s\fR \fIstrength-program\fR, \fB\-\-strength\fR=\fIstrength-program\fR" 4
.IX Item "-s strength-program, --strength=strength-program"
Run \fIstrength-program\fR as the external strength-checking program instead
of the default (\fI/usr/bin/heimdal\-strength\fR).  Primarily used for
testing, since Heimdal won't pass this argument.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
Additional setup is required to use this history implementation with your
Heimdal \s-1KDC.\s0
.PP
First, ensure that its dependencies are installed, and then examine the
local configuration settings at the top of the \fBheimdal-history\fR program.
By default, it requires a \f(CW\*(C`_history\*(C'\fR user and \f(CW\*(C`_history\*(C'\fR group be
present on the system, and all history information will be read and
written as that user and group.  It also requires a \f(CW\*(C`nobody\*(C'\fR user and
\&\f(CW\*(C`nogroup\*(C'\fR group to be present (this should be the default with most
variants of \s-1UNIX\s0), and all strength checking will be done as that user and
group.  It uses various files in \fI/var/lib/heimdal\-history\fR to store
history and statistical information by default, so if using the defaults,
create that directory and ensure it is writable by the \f(CW\*(C`_history\*(C'\fR user.
.PP
Once that setup is done, change your \f(CW\*(C`[password_quality]\*(C'\fR configuration
in \fIkrb5.conf\fR or \fIkdc.conf\fR to:
.PP
.Vb 3
\&    [password_quality]
\&        policies         = external\-check
\&        external_program = /usr/local/bin/heimdal\-history
.Ve
.PP
The \fBheimdal-history\fR program will automatically also run
\&\fBheimdal-strength\fR as well, looking for it in \fI/usr/bin\fR.  Change the
\&\f(CW$STRENGTH_PROGRAM\fR setting at the top of the script if you have that
program in a different location.  You should continue to configure
\&\fBheimdal-strength\fR as if you were running it directly.
.SH "RETURN STATUS"
.IX Header "RETURN STATUS"
On approval of the password, \fBheimdal-history\fR will print \f(CW\*(C`APPROVED\*(C'\fR and
a newline to standard output and exit with status 0.
.PP
If the password is rejected by the strength checking program or if it (or
a version with a single character removed) matches one of the hashes stored
in the password history, \fBheimdal-history\fR will print the reason for
rejection to standard error and exit with status 0.
.PP
On any internal error, \fBheimdal-history\fR will print the error to standard
error and exit with a non-zero status.
.SH "FILES"
.IX Header "FILES"
.IP "\fI/usr/bin/heimdal\-strength\fR" 4
.IX Item "/usr/bin/heimdal-strength"
The default password strength checking program.  This program must follow
the Heimdal external password strength checking \s-1API.\s0
.IP "\fI/var/lib/heimdal\-history/history.db\fR" 4
.IX Item "/var/lib/heimdal-history/history.db"
The default database path.  If \fBheimdal-strength\fR is run as root, this
file needs to be readable and writable by user \f(CW\*(C`_history\*(C'\fR and group
\&\f(CW\*(C`_history\*(C'\fR.  If it doesn't exist, it will be created with mode 0600.
.IP "\fI/var/lib/heimdal\-history/history.db.lock\fR" 4
.IX Item "/var/lib/heimdal-history/history.db.lock"
The lock file used to synchronize access to the history database.  As with
the history database, if \fBheimdal-strength\fR is run as root, this file
needs to be readable and writable by user \f(CW\*(C`_history\*(C'\fR and group
\&\f(CW\*(C`_history\*(C'\fR.
.IP "\fI/var/lib/heimdal\-history/lengths.db\fR" 4
.IX Item "/var/lib/heimdal-history/lengths.db"
The default length statistics path, which will be a BerkeleyDB \s-1DB_HASH\s0
file of password lengths to counts of passwords with that length.  If
\&\fBheimdal-strength\fR is run as root, this file needs to be readable and
writable by user \f(CW\*(C`_history\*(C'\fR and group \f(CW\*(C`_history\*(C'\fR.  If it doesn't exist,
it will be created with mode 0600.
.IP "\fI/var/lib/heimdal\-history/lengths.db.lock\fR" 4
.IX Item "/var/lib/heimdal-history/lengths.db.lock"
The lock file used to synchronize access to the length statistics
database.  As with the length statistics database, if \fBheimdal-strength\fR
is run as root, this file needs to be readable and writable by user
\&\f(CW\*(C`_history\*(C'\fR and group \f(CW\*(C`_history\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Allbery <eagle@eyrie.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2016 Russ Allbery <eagle@eyrie.org>
.PP
Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
University
.PP
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the \*(L"Software\*(R"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
.PP
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
.PP
\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\s0  \s-1IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Crypt::PBKDF2, \fIheimdal\-strength\fR\|(1)