# NAME

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

# SYNOPSIS

    ## From Perl:
    use App::bmkpasswd 'mkpasswd';
    my $bcrypted = mkpasswd($passwd);

    ## From a shell:
    bmkpasswd --help
    

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

    ## Use other methods:
    bmkpasswd --method='md5'
    # SHA requires Crypt::Passwd::XS or glibc2.7+
    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"](#EXPORTED).)

See `bmkpasswd --help` for usage information.

Uses [Bytes::Random::Secure](http://search.cpan.org/perldoc?Bytes::Random::Secure) to generate random salts.

Uses [Crypt::Eksblowfish::Bcrypt](http://search.cpan.org/perldoc?Crypt::Eksblowfish::Bcrypt) for bcrypted passwords. Bcrypt hashes 
come 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/](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](http://search.cpan.org/perldoc?Crypt::Passwd::XS) or a system crypt() that can handle SHA, 
such as glibc-2.7+ or newer FreeBSD builds.

__MD5__ support is fairly universal, but it is known insecure and there 
is really no valid excuse to be using it; it is included here for 
compatibility with ancient hashes.

# EXPORTED

You can use the exported __mkpasswd__ and __passwdcmp__ functions in 
other Perl modules/applications:

    use App::bmkpasswd qw/mkpasswd passwdcmp/;

## mkpasswd

    ## Generate a bcrypted passwd with work-cost 08:
    $bcrypted = mkpasswd($passwd);

    ## Generate a bcrypted passwd with other work-cost:
    $bcrypted = mkpasswd($passwd, 'bcrypt', '06');

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

    ## Use a strong random source (requires spare entropy):
    $crypted = mkpasswd($passwd, 'bcrypt', '08', 1);
    $crypted = mkpasswd($passwd, 'sha512', '', 1);

## passwdcmp

    ## Compare a password against a hash
    ## passwdcmp() will return the hash if it is a match
    if ( passwdcmp($passwd, $hash) ) {
      ## Successful match
    } else {
      ## Failed match
    }

# BUGS

There is currently no easy way to pass your own salt; frankly, 
this thing is aimed at some projects of mine where that issue is 
unlikely to come up and randomized is appropriate. If that's a problem, 
patches welcome? ;-)

# AUTHOR

Jon Portnoy <avenj@cobaltirc.org>
