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, 2011 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.