SYNOPSIS

        use Authen::Passphrase::BlowfishCrypt;

        $ppr = Authen::Passphrase::BlowfishCrypt->new(
                cost => 8,
                salt => "sodium_\|_chloride",
                hash_base64 => "BPZijhMHLvPeNMHd6XwZyNamOXVBTPi");

        $ppr = Authen::Passphrase::BlowfishCrypt->new(
                cost => 8, salt_random => 1,
                passphrase => "passphrase");

        $ppr = Authen::Passphrase::BlowfishCrypt->from_crypt(
                '$2a$08$a07iYVTrVz7hYEvtakjiXOB'.
                'PZijhMHLvPeNMHd6XwZyNamOXVBTPi');

        $ppr = Authen::Passphrase::BlowfishCrypt->from_rfc2307(
                '{CRYPT}$2a$08$a07iYVTrVz7hYEvtakjiXOB'.
                'PZijhMHLvPeNMHd6XwZyNamOXVBTPi');

        $key_nul = $ppr->key_nul;
        $cost = $ppr->cost;
        $cost = $ppr->keying_nrounds_log2;
        $salt = $ppr->salt;
        $salt_base64 = $ppr->salt_base64;
        $hash = $ppr->hash;
        $hash_base64 = $ppr->hash_base64;

        if($ppr->match($passphrase)) { ...

        $passwd = $ppr->as_crypt;
        $userPassword = $ppr->as_rfc2307;

DESCRIPTION

An object of this class encapsulates a passphrase hashed using the Blowfish-based Unix crypt() hash function, known as \*(L"bcrypt\*(R". This is a subclass of Authen::Passphrase, and this document assumes that the reader is familiar with the documentation for that class.

The crypt() function in a modern Unix actually supports several different passphrase schemes. This class is concerned only with one particular scheme, a Blowfish-based algorithm designed by Niels Provos and David Mazieres for OpenBSD. To handle the whole range of passphrase schemes supported by the modern crypt(), see the from_crypt constructor and the as_crypt method in Authen::Passphrase.

The Blowfish-based crypt() scheme uses a variant of Blowfish called \*(L"Eksblowfish\*(R", for \*(L"expensive key schedule Blowfish\*(R". It has the cryptographic strength of Blowfish, and a very slow key setup phase to resist brute-force attacks. There is a \*(L"cost\*(R" parameter to the scheme: the length of key setup is proportional to 2^cost. There is a 128-bit salt. Up to 72 characters of the passphrase will be used; any more will be ignored.

The cost, salt, and passphrase are all used to (very slowly) key Eksblowfish. Once key setup is done, the string \*(L"OrpheanBeholderScryDoubt\*(R" (three Blowfish blocks long) is encrypted 64 times in \s-1ECB\s0 mode. The final byte of the ciphertext is then dropped, yielding a 23-byte hash.

In the crypt() function the salt and hash are represented in \s-1ASCII\s0 using a base 64 encoding. The base 64 digits are ".\*(L", \*(R"/\*(L", \*(R"A\*(L" to \*(R"Z\*(L", \*(R"a\*(L" to \*(R"z\*(L", \*(R"0\*(L" to \*(R"9" (in that order). The 16-byte salt is represented as 22 base 64 digits, and the 23-byte hash as 31 base 64 digits.

This algorithm is intended for situations where the efficiency of a brute force attack is a concern. It is suitable for use in new applications where this requirement exists. If that is not a concern, and it suffices to merely make brute force the most efficient attack, see Authen::Passphrase::SaltedDigest for more efficient hash algorithms.

Choice of the cost parameter is critical, due to the need to trade off expense of brute-force attack against speed of legitimate passphrase verification. A traditional target is that verification should take about one second on widely-available hardware. (Algorithms that are concerned about brute force speed but lack a cost parameter have often aimed for this, with respect to hardware available at the time of the algorithm's introduction.) As of 2011, this is achieved with a cost parameter around 14.

CONSTRUCTORS

Authen::Passphrase::BlowfishCrypt->new(\s-1ATTR\s0 => \s-1VALUE\s0, ...)

Generates a new passphrase recogniser object using the Blowfish-based crypt() algorithm. The following attributes may be given:

key_nul

Truth value indicating whether to append a \s-1NUL\s0 to the passphrase before using it as a key. The algorithm as originally devised does not do this, but it was later modified to do it. The version that does append \s-1NUL\s0 is to be preferred. Default true.

cost

Base-two logarithm of the number of keying rounds to perform.

keying_nrounds_log2

Synonym for cost.

salt

The salt, as a 16-byte string.

salt_base64

The salt, as a string of 22 base 64 digits.

salt_random

Causes salt to be generated randomly. The value given for this attribute is ignored. The source of randomness may be controlled by the facility described in Data::Entropy.

hash

The hash, as a 23-byte string.

hash_base64

The hash, as a string of 31 base 64 digits.

passphrase

A passphrase that will be accepted.

The cost and salt must be given, and either the hash or the passphrase.

Authen::Passphrase::BlowfishCrypt->from_crypt(\s-1PASSWD\s0)

Generates a new passphrase recogniser object using the Blowfish-based crypt() algorithm, from a crypt string. The crypt string must start with "$2$\*(L" for the version that does not append \s-1NUL\s0 to the key, or \*(R"$2a$\*(L" for the version that does. The next two characters must be decimal digits giving the cost parameter. This must be followed by \*(R"$", 22 base 64 digits giving the salt, and finally 31 base 64 digits giving the hash.

Authen::Passphrase::BlowfishCrypt->from_rfc2307(\s-1USERPASSWORD\s0)

Generates a new passphrase recogniser object using the Blowfish-based crypt() algorithm, from an \s-1RFC\s0 2307 string. The string must consist of "{\s-1CRYPT\s0}" (case insensitive) followed by an acceptable crypt string.

METHODS

Returns a truth value indicating whether a \s-1NUL\s0 will be appended to the passphrase before using it as a key. Returns the base-two logarithm of the number of keying rounds that will be performed. Synonym for \*(L"cost\*(R". Returns the salt, as a string of sixteen bytes. Returns the salt, as a string of 22 base 64 digits. Returns the hash value, as a string of 23 bytes. Returns the hash value, as a string of 31 base 64 digits. These methods are part of the standard Authen::Passphrase interface.

RELATED TO Authen::Passphrase::BlowfishCrypt…

Authen::Passphrase, Crypt::Eksblowfish::Bcrypt

AUTHOR

Andrew Main (Zefram) <[email protected]>

COPYRIGHT

Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram) <[email protected]>

LICENSE

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