NAME

Crypt::Passphrase::Bcrypt - A bcrypt encoder for Crypt::Passphrase

VERSION

version 0.009

SYNOPSIS

my $passphrase = Crypt::Passphrase->new(
  encoder => {
    module => 'Bcrypt',
    cost   => 14,
    hash   => 'sha256',
  },
);

DESCRIPTION

This class implements a bcrypt encoder for Crypt::Passphrase. For high-end parameters Crypt::Passphrase::Argon2 is recommended over this module as an encoder, as that provides memory-hardness and more easily allows for long passwords.

Note that in bcrypt passwords may only contain 72 characters and may not contain any null-byte. To work around this limitation this module supports prehashing the input in a way that prevents password shucking. By default it will reject such passwords when prehashing is not used.

Configuration

It accepts the following arguments:

• cost

  This is the cost factor that is used to hash passwords. It currently defaults to 14, but this may change in the future.

• subtype

  • 2b

    This is the subtype everyone has been using since 2014. The change here is that the hashing algorithm now requires utf-8 encoding, and the null terminator must be included for hashing.

  • 2y

    This type is considered equivalent to 2b. It is common on php but not elsewhere.

  • 2a

    This is an old and subtly buggy version of bcrypt. This is mainly useful for Crypt::Eksblowfish compatibility, along with older OpenBSD (pre 5.5) implementations.

  • 2x

    This is a very broken version that is only useful for compatibility with ancient php versions and their crypt_blowfish library.

  This is 2b by default, and you're unlikely to want to change this. Details about why this came about can be found here http://undeadly.org/cgi?action=article&sid=20140224132743. They are all security equivalent but for forward compatibility you should only ever generate new passwords with 2b.

• hash

  Pre-hash the password using the specified hash. It will support any hash supported by Crypt::Bcrypt, which is currently 'sha256', 'sha384' and 'sha512'. This is mainly useful because plain bcrypt is not null-byte safe and only supports 72 characters of input. This uses a salt-keyed hash to prevent password shucking.

• length_check

  When not pre-hashing bcrypt passwords may only contain 72 characters and may not contain any null-byte. The value of this argument decides what to do if a hash is found to violate that restriction. Allowed values are:

  • 'die' (the default)

    This will die when given an incompliant password.

  • 'warn'

    This will warn about the incompliant password.

  • 'ignore'

    This will silently pass the password.

  Alternatively, you can pass it a subref with your own handler, this will be passed the error message as its argument.

SUPPORTED CRYPT TYPES

It supports the above described subtypes, as well as bcrypt-sha256, bcrypt-sha384 and bcrypt-sha512 for prehashed bcrypt.

AUTHOR

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.