crypt::eksblowfish::bcrypt(3pm) [debian man page]

Crypt::Eksblowfish::Bcrypt(3pm) 			User Contributed Perl Documentation			   Crypt::Eksblowfish::Bcrypt(3pm)

NAME

       Crypt::Eksblowfish::Bcrypt - Blowfish-based Unix crypt() password hash

SYNOPSIS

	       use Crypt::Eksblowfish::Bcrypt qw(bcrypt_hash);

	       $hash = bcrypt_hash({
			       key_nul => 1,
			       cost => 8,
			       salt => $salt,
		       }, $password);

	       use Crypt::Eksblowfish::Bcrypt qw(en_base64 de_base64);

	       $text = en_base64($octets);
	       $octets = de_base64($text);

	       use Crypt::Eksblowfish::Bcrypt qw(bcrypt);

	       $hashed_password = bcrypt($password, $settings);

DESCRIPTION

       This module implements the Blowfish-based Unix crypt() password hashing algorithm, known as "bcrypt".  This hash uses a variant of
       Blowfish, known as "Eksblowfish", modified to have particularly expensive key scheduling.  Eksblowfish and bcrypt were devised by Niels
       Provos and David Mazieres for OpenBSD.  The design is described in a paper at <http://www.usenix.org/events/usenix99/provos.html>.

FUNCTIONS

       bcrypt_hash(SETTINGS, PASSWORD)
	   Hashes PASSWORD according to the supplied SETTINGS, and returns the 23-octet hash.  SETTINGS must be a reference to a hash, with these
	   keys:

	   key_nul
	       Truth value: whether to append a NUL to the password 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 NUL is to be preferred; not doing so is supported only for
	       backward compatibility.

	   cost
	       Non-negative integer controlling the cost of the hash function.	The number of operations is proportional to 2^cost.

	   salt
	       Exactly sixteen octets of salt.

       en_base64(BYTES)
	   Encodes the octet string textually using the form of base 64 that is conventionally used with bcrypt.

       de_base64(TEXT)
	   Decodes an octet string that was textually encoded using the form of base 64 that is conventionally used with bcrypt.

       bcrypt(PASSWORD, SETTINGS)
	   This is a version of "crypt" (see "crypt" in perlfunc) that implements the bcrypt algorithm.  It does not implement any other hashing
	   algorithms, so if others are desired then it necessary to examine the algorithm prefix in SETTINGS and dispatch between more than one
	   version of "crypt".

	   SETTINGS must be a string which encodes the algorithm parameters, including salt.  It must begin with "$2", optional "a", "$", two
	   digits, "$", and 22 base 64 digits.	The rest of the string is ignored.  The presence of the optional "a" means that a NUL is to be
	   appended to the password before it is used as a key.  The two digits set the cost parameter.  The 22 base 64 digits encode the salt.
	   The function will "die" if SETTINGS does not have this format.

	   The PASSWORD is hashed according to the SETTINGS.  The value returned is a string which encodes the algorithm parameters and the hash:
	   the parameters are in the same format required in SETTINGS, and the hash is appended in the form of 31 base 64 digits.  This result is
	   suitable to be used as a SETTINGS string for input to this function: the hash part of the string is ignored on input.

SEE ALSO

       Crypt::Eksblowfish, <http://www.usenix.org/events/usenix99/provos.html>

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2006, 2007, 2008, 2009, 2010 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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

perl v5.14.2							    2011-11-15					   Crypt::Eksblowfish::Bcrypt(3pm)

Crypt::Eksblowfish::Family(3pm) 			User Contributed Perl Documentation			   Crypt::Eksblowfish::Family(3pm)

NAME

       Crypt::Eksblowfish::Family - Eksblowfish cipher family

SYNOPSIS

	       use Crypt::Eksblowfish::Family;

	       $family = Crypt::Eksblowfish::Family->new_family(8, $salt);

	       $cost = $family->cost;
	       $salt = $family->salt;
	       $block_size = $family->blocksize;
	       $key_size = $family->keysize;
	       $cipher = $family->new($key);

DESCRIPTION

       An object of this class represents an Eksblowfish cipher family.  It contains the family parameters (cost and salt), and if combined with a
       key it yields an encryption function.  See Crypt::Eksblowfish for discussion of the Eksblowfish algorithm.

       It is intended that an object of this class can be used in situations such as the "-cipher" parameter to "Crypt::CBC".  Normally that
       parameter is the name of a class, such as "Crypt::Rijndael", where the class implements a block cipher algorithm.  The class provides a
       "new" constructor that accepts a key.  In the case of Eksblowfish, the key alone is not sufficient.  An Eksblowfish family fills the role
       of block cipher algorithm.  Therefore a family object is used in place of a class name, and it is the family object the provides the "new"
       constructor.

   Crypt::CBC
       "Crypt::CBC" itself has a problem, with the result that this class can no longer be used with it in the manner originally intended.

       When this class was originally designed, it worked with "Crypt::CBC" as described above: an object of this class would be accepted by
       "Crypt::CBC" as a cipher algorithm, and "Crypt::CBC" would happily supply it with a key and encrypt using the resulting cipher object.
       "Crypt::CBC" didn't realise it was dealing with a family object, however, and there was some risk that a future version might accidentally
       squash the object into a string, which would be no use.	In the course of discussion about regularising the use of cipher family objects,
       the author of "Crypt::CBC" got hold of the wrong end of the stick, and ended up changing "Crypt::CBC" in a way that totally breaks this
       usage, rather than putting it on a secure footing.

       The present behaviour of "Crypt::CBC" is that if an object (rather than a class name) is supplied as the "-cipher" parameter then it has a
       completely different meaning from usual.  In this case, the object supplied is used as the keyed cipher, rather than as a cipher algorithm
       which must be given a key.  This bypasses all of "Crypt::CBC"'s usual keying logic, which can hash and salt a passphrase to generate the
       key.  It is arguably a useful feature, but it's a gross abuse of the "-cipher" parameter and a severe impediment to the use of family-keyed
       cipher algorithms.

       This class now provides a workaround.  For the benefit of "Crypt::CBC", and any other crypto plumbing that requires a keyable cipher
       algorithm to look like a Perl class (rather than an object), a family object of this class can in fact be reified as a class of its own.
       See the method "as_class".

CONSTRUCTOR

       Crypt::Eksblowfish::Family->new_family(COST, SALT)
	   Creates and returns an object representing the Eksblowfish cipher family specified by the parameters.  The SALT is a family key, and
	   must be exactly 16 octets.  COST is an integer parameter controlling the expense of keying: the number of operations in key setup is
	   proportional to 2^COST.

METHODS

       $family->cost
	   Extracts and returns the cost parameter.

       $family->salt
	   Extracts and returns the salt parameter.

       $family->blocksize
	   Returns 8, indicating the Eksblowfish block size of 8 octets.

       $family->keysize
	   Returns 0, indicating that the key size is variable.  This situation is handled specially by "Crypt::CBC".

       $family->new(KEY)
	   Performs key setup on a new instance of the Eksblowfish algorithm, returning the keyed state.  The KEY may be any length from 1 octet
	   to 72 octets inclusive.  The object returned is of class "Crypt::Eksblowfish"; see Crypt::Eksblowfish for the encryption and decryption
	   methods.

	   Note that this method is called on a family object, not on the class "Crypt::Eksblowfish::Family".

       $family->encrypt
	   This method nominally exists, to satisfy "Crypt::CBC".  It can't really be used: it doesn't make any sense.

       $family->as_class
	   Generates and returns (the name of) a Perl class that behaves as a keyable cipher algorithm identical to this Eksblowfish cipher
	   family.  The same methods that can be called as instance methods on $family can be called as class methods on the generated class.

	   You should prefer to use the family object directly wherever you can.  Aside from being a silly indirection, the classes generated by
	   this method cannot be garbage-collected.  This method exists only to cater to "Crypt::CBC", which requires a keyable cipher algorithm
	   to look like a Perl class, and won't operate correctly on one that looks like an object.

SEE ALSO

       Crypt::CBC, Crypt::Eksblowfish

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2006, 2007, 2008, 2009, 2010 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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

perl v5.14.2							    2011-11-15					   Crypt::Eksblowfish::Family(3pm)