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".)

    See "bmkpasswd --help" for usage information.

    Uses Bytes::Random::Secure to generate random salts.

    Uses 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/> 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 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>

