-.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
+.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.\" 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"
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
..
-. if !\nF==2 \{\
-. nr % 0
-. nr F 2
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
. \}
.\}
+.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "HEIMDAL-HISTORY 1"
-.TH HEIMDAL-HISTORY 1 "2016-12-25" "3.1" "krb5-strength"
+.TH HEIMDAL-HISTORY 1 "2020-05-17" "3.2" "krb5-strength"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
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]
+\&\fBheimdal-history\fR [\fB\-chmq\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.)
+\&\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.)
+Password history is stored indefinitely (implementing infinite history); older
+password hashes are never removed by this program.
.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.
+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
+\&\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.
+\&\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.
+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:
+As with any implementation of the Heimdal external password strength checking
+protocol, \fBheimdal-history\fR expects, on standard input:
.PP
.Vb 3
\& principal: <principal>
.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.
+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.
+If the password is accepted, \fBheimdal-history\fR will assume that it will be
+used and will update the history database to record the new password. It will
+also update the password length statistics database to account for the new
+password.
.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:
+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).
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).
+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.
.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.
+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
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
+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\-c\fR, \fB\-\-check\-only\fR" 4
+.IX Item "-c, --check-only"
+Check password history and password strength and print the results as normal,
+but do not update the history or length statistics databases. This is a
+read-only mode of operation that will not make any changes to the underlying
+database, only report if a password would currently be accepted.
.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.
+(\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.
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.
+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.
+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.
+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.
+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:
+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]
\& 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.
+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.
+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.
+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.
.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
+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.
+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.
+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
+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.
+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.
+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>
+Copyright 2016\-2017, 2020 Russ Allbery <eagle@eyrie.org>
.PP
-Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
+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:
+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.
+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. IN 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
+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
+.PP
+SPDX-License-Identifier: \s-1MIT\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
-Crypt::PBKDF2, \fIheimdal\-strength\fR\|(1)
+Crypt::PBKDF2, \fBheimdal\-strength\fR\|(1)
projects / kerberos / krb5-strength.git / blobdiff