# Password history via Heimdal external strength checking.
#
# This script is meant to be called via the Heimdal external password strength
-# checking interface and maintains per-user password history that also rejects
-# one-character permutations. Password history is stored as Crypt::PBKDF2
-# hashes with random salt for each password.
+# checking interface and maintains per-user password history. Password
+# history is stored as Crypt::PBKDF2 hashes with random salt for each
+# password.
#
# Written by Russ Allbery <eagle@eyrie.org>
# Copyright 2013, 2014
# The number of PBKDF2 iterations to use when hashing passwords. This number
# should be chosen so as to force the hash operation to take approximately 0.1
# seconds on current hardware.
-Readonly my $HASH_ITERATIONS => 65536;
+Readonly my $HASH_ITERATIONS => 14592;
# Path to the history database. Currently, this must be a Berkeley DB file in
# the old DB_HASH format. Keys will be principal names, and values will be a
Readonly my $STRENGTH_USER => 'nobody';
Readonly my $STRENGTH_GROUP => 'nogroup';
+# Global boolean variable saying whether to log with syslog. This is set
+# based on the presence of the -q (--quiet) command-line option.
+my $SYSLOG = 1;
+
##############################################################################
# Utility functions
##############################################################################
# - error: an error message explaining the anomalous situation
#
# Values containing whitespace are quoted with double quotes, with any
-# internal double quotes doubled.
+# internal double quotes doubled. No logging will be done if $SYSLOG is
+# false.
#
# $principal - Principal for which we checked a password
# $error - The error message
# Returns: undef
sub log_error {
my ($principal, $error) = @_;
+ if (!$SYSLOG) {
+ return;
+ }
my $message = encode_log_message(
action => 'check',
principal => $principal,
# - reason: the reason for a rejection
#
# Values containing whitespace are quoted with double quotes, with any
-# internal double quotes doubled.
+# internal double quotes doubled. No logging will be done if $SYSLOG is
+# false.
#
# $principal - Principal for which we checked a password
# $result - "accepted" or "rejected" per above
# Returns: undef
sub log_result {
my ($principal, $result, $reason) = @_;
+ if (!$SYSLOG) {
+ return;
+ }
# Create the message.
my %message = (
# PBKDF2 using SHA-2 as the underlying hash function. As of version 0.133330,
# this uses SHA-256.
#
-# $password - Password to hash
+# $password - Password to hash
+# $iterations - Optional iteration count, defaulting to $HASH_ITERATIONS
#
# Returns: Hash encoded in the LDAP-compatible Crypt::PBKDF2 format
sub password_hash {
- my ($password) = @_;
+ my ($password, $iterations) = @_;
+ $iterations //= $HASH_ITERATIONS;
my $hasher = Crypt::PBKDF2->new(
hash_class => 'HMACSHA2',
- iterations => $HASH_ITERATIONS,
+ iterations => $iterations,
);
return $hasher->generate($password);
}
return;
}
+##############################################################################
+# Benchmarking
+##############################################################################
+
+# Perform a binary search for a number of hash iterations that makes password
+# hashing take the given target time on the current system.
+#
+# Assumptions:
+#
+# * The system load is low enough that this benchmark result is meaningful
+# and not heavily influenced by other programs running on the system. The
+# binary search may be unstable if the system load is too variable.
+#
+# * The static "password" string used for benchmarking will exhibit similar
+# performance to the statistically average password.
+#
+# Information about the iteration search process is printed to standard output
+# while the search runs.
+#
+# $target - The elapsed time, in real seconds, we're aiming for
+# $delta - The permissible delta around the target time
+#
+# Returns: The number of hash iterations with that performance characteristic
+# Throws: Text exception on failure to write to standard output
+sub find_iteration_count {
+ my ($target, $delta) = @_;
+ my $high = 0;
+ my $low = 0;
+
+ # A static password to use for benchmarking.
+ my $password = 'this is a benchmark';
+
+ # Start at the current configured iteration count. If this doesn't take
+ # long enough, it becomes the new low mark and we try double that
+ # iteration count. Otherwise, do binary search.
+ #
+ # We time twenty iterations each time, chosen because it avoids the
+ # warnings from Benchmark about too few iterations for a reliable count.
+ require Benchmark;
+ my $iterations = $HASH_ITERATIONS;
+ while (1) {
+ my $hash = sub { password_hash($password, $iterations) };
+ my $times = Benchmark::timethis(20, $hash, q{}, 'none');
+
+ # Extract the CPU time from the formatted time string. This will be
+ # the total time for all of the iterations, so divide by the iteration
+ # count to recover the time per iteration.
+ my $report = Benchmark::timestr($times);
+ my ($time) = ($report =~ m{ ([\d.]+) [ ] CPU }xms);
+ $time = $time / 20;
+
+ # Tell the user what we discovered.
+ say {*STDOUT} "Performing $iterations iterations takes $time seconds"
+ or die "$0: cannot write to standard output: $!\n";
+
+ # If this is what we're looking for, we're done.
+ if (abs($time - $target) < $delta) {
+ last;
+ }
+
+ # Determine the new iteration target.
+ if ($time > $target) {
+ $high = $iterations;
+ } else {
+ $low = $iterations;
+ }
+ if ($time < $target && $high == 0) {
+ $iterations = $iterations * 2;
+ } else {
+ $iterations = int(($high + $low) / 2);
+ }
+ }
+
+ # Report the result and return it.
+ say {*STDOUT} "Use $iterations iterations"
+ or die "$0: cannot write to standard output: $!\n";
+ return $iterations;
+}
+
##############################################################################
# Database
##############################################################################
}
##############################################################################
-# Heimdal password strength protocol
+# Heimdal password quality protocol
##############################################################################
-# Run another external password strength checker and return the results. This
+# Run another external password quality checker and return the results. This
# allows us to chain to another program that handles the actual strength
# checking prior to handling history.
#
+# $path - Password quality check program to run
# $principal - Principal attempting to change their password
# $password - The new password
#
# Returns: Scalar context: true if the password was accepted, false otherwise
# List context: whether the password is okay, the exit status of the
-# strength checking program, and the error message if the first
+# quality checking program, and the error message if the first
# element is false
# Throws: Text exception on failure to execute the program, or read or write
# from it or to it, or if it fails without an error
sub strength_check {
- my ($principal, $password) = @_;
+ my ($path, $principal, $password) = @_;
- # Run the external strength checking program. If we're root, we'll run it
+ # Run the external quality checking program. If we're root, we'll run it
# as the strength checking user and group.
my $in = "principal: $principal\nnew-password: $password\nend\n";
my $init = sub { drop_privileges($STRENGTH_USER, $STRENGTH_GROUP) };
my ($out, $err);
- run([$STRENGTH_PROGRAM, $principal], \$in, \$out, \$err, init => $init);
+ run([$path, $principal], \$in, \$out, \$err, init => $init);
my $status = ($? >> 8);
# Check the results.
return wantarray ? ($okay, $err, $status) : $okay;
}
-# Read a Heimdal external password strength checking request from the provided
+# Read a Heimdal external password quality checking request from the provided
# file handle and return the principal (ignored for our application) and the
# password.
#
# Parse the argument list.
my ($opt, $usage) = describe_options(
'%c %o',
- ['database|d=s', 'Path to the history database, overriding the default'],
- ['help|h', 'Print usage message and exit'],
- ['manual|man|m', 'Print full manual and exit'],
- ['stats|S=s', 'Path to hash of length statistics'],
- ['strength|s=s', 'Path to strength checking program to run'],
+ ['benchmark|b=f', 'Benchmark hash iterations for this target time'],
+ ['database|d=s', 'Path to the history database, overriding the default'],
+ ['help|h', 'Print usage message and exit'],
+ ['manual|man|m', 'Print full manual and exit'],
+ ['quiet|q', 'Suppress logging to syslog'],
+ ['stats|S=s', 'Path to hash of length statistics'],
+ ['strength|s=s', 'Path to strength checking program to run'],
);
if ($opt->help) {
print {*STDOUT} $usage->text
}
my $database = $opt->database || $HISTORY_PATH;
my $stats_db = $opt->stats || $LENGTH_STATS_PATH;
+my $strength = $opt->strength || $STRENGTH_PROGRAM;
+
+# If asked to do benchmarking, ignore other arguments and just do that.
+# Currently, we hard-code a 0.005-second granularity on our binary search.
+if ($opt->benchmark) {
+ find_iteration_count($opt->benchmark, 0.005);
+ exit(0);
+}
# Open syslog for result reporting.
-openlog($0, 'pid', LOG_AUTH);
+if ($opt->quiet) {
+ $SYSLOG = 0;
+} else {
+ openlog($0, 'pid', LOG_AUTH);
+}
# Read the principal and password that we're supposed to check.
my ($password, $principal) = read_change_data(\*STDIN);
# Delegate to the external strength checking program.
-my ($okay, $error, $status) = strength_check($principal, $password);
+my ($okay, $error, $status) = strength_check($strength, $principal, $password);
if (!$okay) {
log_result($principal, 'rejected', $error);
warn "$error\n";
##############################################################################
=for stopwords
-heimdal-history heimdal-strength Heimdal -hm BerkeleyDB timestamps POSIX
+heimdal-history heimdal-strength Heimdal -hmq BerkeleyDB timestamps POSIX
whitespace API Allbery sublicense MERCHANTABILITY NONINFRINGEMENT syslog
pseudorandom JSON LDAP-compatible PBKDF2 SHA-256
=head1 SYNOPSIS
-B<heimdal-history> [B<-hm>] [B<-d> I<database>] [B<-S> I<length-stats-db>]
- [B<-s> I<strength-program>] [B<principal>]
+B<heimdal-history> [B<-hmq>] [B<-b> I<target-time>] [B<-d> I<database>]
+ [B<-
S> I<length-stats-db>] [B<-s> I<strength-program>] [B<principal>]
=head1 DESCRIPTION
=over 4
+=item B<-b> I<target-time>, B<--benchmark>=I<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 I<target-time> 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 B<heimdal-history> will exit
+successfully.
+
=item B<-d> I<database>, B<--database>=I<database>
Use I<database> as the history database file instead of the default
Display this manual and exit.
+=item B<-q>, B<--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.
+
=item B<-S> I<length-stats-db>, B<--stats>=I<length-stats-db>
Use I<length-stats-db> as the database file for password length statistics
projects / kerberos / krb5-strength.git / blobdiff