Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
App::bmkpasswd
Perl Perl6

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
t
xt
Changes
README.mkdn
dist.ini

README.mkdn

NAME

App::bmkpasswd - bcrypt-capable mkpasswd(1) and exported helpers

SYNOPSIS

## From Perl:

use App::bmkpasswd 'mkpasswd', 'passwdcmp';
my $bcrypted = mkpasswd($passwd);
say 'matched' if passwdcmp($passwd, $bcrypted);

## From a shell:

bmkpasswd --help


# Generate bcrypted passwords
# Defaults to work cost factor '08':
bmkpasswd
bmkpasswd --workcost='06'

# SHA requires Crypt::Passwd::XS or a recent libc:
bmkpasswd --method='sha512'


# Compare a hash:
bmkpasswd --check=HASH

# Check hash generation times:
bmkpasswd --benchmark

DESCRIPTION

App::bmkpasswd is a simple bcrypt-enabled mkpasswd.

Helper functions are also exported for use in other applications; see "EXPORTED". Crypt::Bcrypt::Easy provides an easier bcrypt-specific programmatic interface for Perl programmers.

See bmkpasswd --help for command-line usage information.

Uses Crypt::Eksblowfish::Bcrypt for bcrypted passwords.

Bcrypt comes with a configurable work-cost factor; that allows hash generation to become configurably slower as computers get faster, thereby impeding brute-force hash generation attempts.

See http://codahale.com/how-to-safely-store-a-password/ for more on why you ought to be using bcrypt or similar "adaptive" techniques.

SHA-256 and SHA-512 are supported if available. You'll need either Crypt::Passwd::XS or a system crypt() that can handle SHA (such as glibc-2.7+ or modern FreeBSD builds).

Uses Bytes::Random::Secure to generate random salts. For the paranoid, constant time comparison is used when comparing hashes; strongly-random salts can also be enabled (see "mkpasswd").

EXPORTED

Crypt::Bcrypt::Easy provides an easier programmatic interface, if you're only interested in generating bcrypt passwords. If you'd like to make use of other password types, you can use the exported mkpasswd and passwdcmp functions:

use App::bmkpasswd 'mkpasswd', 'passwdcmp';
# Same as:
use App::bmkpasswd -all;

This module uses Exporter::Tiny to export functions. This provides for flexible import options. See the Exporter::Tiny docs for details.

passwdcmp

Compare a password against a hash.

if ( passwdcmp($plaintext, $crypted) ) {
  ## Successful match
} else {
  ## Failed match
}

passwdcmp will return the hash if it is a match; otherwise, an empty list is returned.

mkpasswd

my $crypted = mkpasswd($passwd);
my $crypted = mkpasswd($passwd, $type);
my $crypted = mkpasswd($passwd, 'bcrypt', $cost);
my $crypted = mkpasswd($passwd, $type, $cost, $strongsalt);

my $crypted = mkpasswd( $passwd => 
  +{
    type    => $type,
    cost    => $cost,
    strong  => $strongsalt,
    saltgen => $saltgenerator,
  }
);

Generate hashed passwords.

By default, generates a bcrypted passwd with work-cost 08:

$bcrypted = mkpasswd($passwd);

A different work-cost can be specified for bcrypt passwds:

$bcrypted = mkpasswd($passwd, 'bcrypt', '10');

SHA is supported, in which case the work-cost value is ignored:

$crypted = mkpasswd($passwd, 'sha256');
$crypted = mkpasswd($passwd, 'sha512');

If a fourth boolean-true argument is specified, a strongly-random salt is generated. This requires spare entropy, and will block if entropy-starved:

$crypted = mkpasswd($passwd, 'bcrypt', '08', 'strong');
$crypted = mkpasswd($passwd, 'sha512', 0, 'strong');

Options can be passed as a HASH, instead. This also lets you pass in a salt generator coderef:

$crypted = mkpasswd( $passwd => +{
    type => 'bcrypt',
    cost => '10',
    strong  => 0,
    saltgen => $saltgenerator,
  }
);

The salt generator is passed the type (one of: bcrypt, sha, md5) and the value of the strong option (default false).

my $saltgenerator = sub {
  my ($type, $strongsalt) = @_;
  if ($type eq 'bcrypt') {
    # ...
  } elsif ($type eq 'sha') {
    # ...
  } else {
    die "Don't know how to create a salt for type '$type'!"
  }
};

(Most people want random salts, in which case the default salt generator should be fine.)

AUTHOR

Jon Portnoy avenj@cobaltirc.org

Something went wrong with that request. Please try again.