--- name: "Crypt::Eksblowfish::Family" section: "3pm" platform: "linux" package: "libcrypt-eksblowfish-perl" version: "0.009-3+b4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Crypt::Eksblowfish::Family" --- # Crypt::Eksblowfish::Family(3pm) Eksblowfish cipher family ## 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) \ ## COPYRIGHT Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Andrew Main (Zefram) \ ## LICENSE This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.