1Crypt::Eksblowfish::FamUisleyr(3Cpomn)tributed Perl DocuCmreynptta:t:iEoknsblowfish::Family(3pm)
2
3
4

NAME

6       Crypt::Eksblowfish::Family - Eksblowfish cipher family
7

SYNOPSIS

9               use Crypt::Eksblowfish::Family;
10
11               $family = Crypt::Eksblowfish::Family->new_family(8, $salt);
12
13               $cost = $family->cost;
14               $salt = $family->salt;
15               $block_size = $family->blocksize;
16               $key_size = $family->keysize;
17               $cipher = $family->new($key);
18

DESCRIPTION

20       An object of this class represents an Eksblowfish cipher family.  It
21       contains the family parameters (cost and salt), and if combined with a
22       key it yields an encryption function.  See Crypt::Eksblowfish for
23       discussion of the Eksblowfish algorithm.
24
25       It is intended that an object of this class can be used in situations
26       such as the "-cipher" parameter to "Crypt::CBC".  Normally that
27       parameter is the name of a class, such as "Crypt::Rijndael", where the
28       class implements a block cipher algorithm.  The class provides a "new"
29       constructor that accepts a key.  In the case of Eksblowfish, the key
30       alone is not sufficient.  An Eksblowfish family fills the role of block
31       cipher algorithm.  Therefore a family object is used in place of a
32       class name, and it is the family object the provides the "new"
33       constructor.
34
35   Crypt::CBC
36       "Crypt::CBC" itself has a problem, with the result that this class can
37       no longer be used with it in the manner originally intended.
38
39       When this class was originally designed, it worked with "Crypt::CBC" as
40       described above: an object of this class would be accepted by
41       "Crypt::CBC" as a cipher algorithm, and "Crypt::CBC" would happily
42       supply it with a key and encrypt using the resulting cipher object.
43       "Crypt::CBC" didn't realise it was dealing with a family object,
44       however, and there was some risk that a future version might
45       accidentally squash the object into a string, which would be no use.
46       In the course of discussion about regularising the use of cipher family
47       objects, the author of "Crypt::CBC" got hold of the wrong end of the
48       stick, and ended up changing "Crypt::CBC" in a way that totally breaks
49       this usage, rather than putting it on a secure footing.
50
51       The present behaviour of "Crypt::CBC" is that if an object (rather than
52       a class name) is supplied as the "-cipher" parameter then it has a
53       completely different meaning from usual.  In this case, the object
54       supplied is used as the keyed cipher, rather than as a cipher algorithm
55       which must be given a key.  This bypasses all of "Crypt::CBC"'s usual
56       keying logic, which can hash and salt a passphrase to generate the key.
57       It is arguably a useful feature, but it's a gross abuse of the
58       "-cipher" parameter and a severe impediment to the use of family-keyed
59       cipher algorithms.
60
61       This class now provides a workaround.  For the benefit of "Crypt::CBC",
62       and any other crypto plumbing that requires a keyable cipher algorithm
63       to look like a Perl class (rather than an object), a family object of
64       this class can in fact be reified as a class of its own.  See the
65       method "as_class".
66

CONSTRUCTOR

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

METHODS

76       $family->cost
77           Extracts and returns the cost parameter.
78
79       $family->salt
80           Extracts and returns the salt parameter.
81
82       $family->blocksize
83           Returns 8, indicating the Eksblowfish block size of 8 octets.
84
85       $family->keysize
86           Returns 0, indicating that the key size is variable.  This
87           situation is handled specially by "Crypt::CBC".
88
89       $family->new(KEY)
90           Performs key setup on a new instance of the Eksblowfish algorithm,
91           returning the keyed state.  The KEY may be any length from 1 octet
92           to 72 octets inclusive.  The object returned is of class
93           "Crypt::Eksblowfish"; see Crypt::Eksblowfish for the encryption and
94           decryption methods.
95
96           Note that this method is called on a family object, not on the
97           class "Crypt::Eksblowfish::Family".
98
99       $family->encrypt
100           This method nominally exists, to satisfy "Crypt::CBC".  It can't
101           really be used: it doesn't make any sense.
102
103       $family->as_class
104           Generates and returns (the name of) a Perl class that behaves as a
105           keyable cipher algorithm identical to this Eksblowfish cipher
106           family.  The same methods that can be called as instance methods on
107           $family can be called as class methods on the generated class.
108
109           You should prefer to use the family object directly wherever you
110           can.  Aside from being a silly indirection, the classes generated
111           by this method cannot be garbage-collected.  This method exists
112           only to cater to "Crypt::CBC", which requires a keyable cipher
113           algorithm to look like a Perl class, and won't operate correctly on
114           one that looks like an object.
115

SEE ALSO

117       Crypt::CBC, Crypt::Eksblowfish
118

AUTHOR

120       Andrew Main (Zefram) <zefram@fysh.org>
121
123       Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Andrew Main (Zefram)
124       <zefram@fysh.org>
125

LICENSE

127       This module is free software; you can redistribute it and/or modify it
128       under the same terms as Perl itself.
129
130
131
132perl v5.38.0                      2023-07-20   Crypt::Eksblowfish::Family(3pm)
Impressum