1Crypt::Eksblowfish::FamUisleyr(3Cpomn)tributed Perl DocuCmreynptta:t:iEoknsblowfish::Family(3pm)
2
6 Crypt::Eksblowfish::Family - Eksblowfish cipher family
7
9 use Crypt::Eksblowfish::Family;
10 $family = Crypt::Eksblowfish::Family->new_family(8, $salt);
12 $cost = $family->cost;
14 $salt = $family->salt;
15 $block_size = $family->blocksize;
16 $key_size = $family->keysize;
17 $cipher = $family->new($key);
18
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 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 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 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 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 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
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
76 $family->cost
77 Extracts and returns the cost parameter.
78 $family->salt
80 Extracts and returns the salt parameter.
81 $family->blocksize
83 Returns 8, indicating the Eksblowfish block size of 8 octets.
84 $family->keysize
86 Returns 0, indicating that the key size is variable. This
87 situation is handled specially by "Crypt::CBC".
88 $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 Note that this method is called on a family object, not on the
97 class "Crypt::Eksblowfish::Family".
98 $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 $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 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
117 Crypt::CBC, Crypt::Eksblowfish
118
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
127 This module is free software; you can redistribute it and/or modify it
128 under the same terms as Perl itself.
129perl v5.38.0 2023-07-20 Crypt::Eksblowfish::Family(3pm)