.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Crypt::Eksblowfish::Family 3pm" .TH Crypt::Eksblowfish::Family 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Crypt::Eksblowfish::Family \- Eksblowfish cipher family .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& 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); .Ve .SH DESCRIPTION .IX Header "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. .PP It is intended that an object of this class can be used in situations such as the "\-cipher" parameter to \f(CW\*(C`Crypt::CBC\*(C'\fR. 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 \f(CW\*(C`new\*(C'\fR 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 \f(CW\*(C`new\*(C'\fR constructor. .SS Crypt::CBC .IX Subsection "Crypt::CBC" \&\f(CW\*(C`Crypt::CBC\*(C'\fR itself has a problem, with the result that this class can no longer be used with it in the manner originally intended. .PP When this class was originally designed, it worked with \f(CW\*(C`Crypt::CBC\*(C'\fR as described above: an object of this class would be accepted by \&\f(CW\*(C`Crypt::CBC\*(C'\fR as a cipher algorithm, and \f(CW\*(C`Crypt::CBC\*(C'\fR would happily supply it with a key and encrypt using the resulting cipher object. \&\f(CW\*(C`Crypt::CBC\*(C'\fR 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 \f(CW\*(C`Crypt::CBC\*(C'\fR got hold of the wrong end of the stick, and ended up changing \f(CW\*(C`Crypt::CBC\*(C'\fR in a way that totally breaks this usage, rather than putting it on a secure footing. .PP The present behaviour of \f(CW\*(C`Crypt::CBC\*(C'\fR 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 \f(CW\*(C`Crypt::CBC\*(C'\fR'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. .PP This class now provides a workaround. For the benefit of \f(CW\*(C`Crypt::CBC\*(C'\fR, 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". .SH CONSTRUCTOR .IX Header "CONSTRUCTOR" .IP "Crypt::Eksblowfish::Family\->new_family(COST, SALT)" 4 .IX Item "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. .SH METHODS .IX Header "METHODS" .ie n .IP $family\->cost 4 .el .IP \f(CW$family\fR\->cost 4 .IX Item "$family->cost" Extracts and returns the cost parameter. .ie n .IP $family\->salt 4 .el .IP \f(CW$family\fR\->salt 4 .IX Item "$family->salt" Extracts and returns the salt parameter. .ie n .IP $family\->blocksize 4 .el .IP \f(CW$family\fR\->blocksize 4 .IX Item "$family->blocksize" Returns 8, indicating the Eksblowfish block size of 8 octets. .ie n .IP $family\->keysize 4 .el .IP \f(CW$family\fR\->keysize 4 .IX Item "$family->keysize" Returns 0, indicating that the key size is variable. This situation is handled specially by \f(CW\*(C`Crypt::CBC\*(C'\fR. .ie n .IP $family\->new(KEY) 4 .el .IP \f(CW$family\fR\->new(KEY) 4 .IX Item "$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 \f(CW\*(C`Crypt::Eksblowfish\*(C'\fR; see Crypt::Eksblowfish for the encryption and decryption methods. .Sp Note that this method is called on a family object, not on the class \&\f(CW\*(C`Crypt::Eksblowfish::Family\*(C'\fR. .ie n .IP $family\->encrypt 4 .el .IP \f(CW$family\fR\->encrypt 4 .IX Item "$family->encrypt" This method nominally exists, to satisfy \f(CW\*(C`Crypt::CBC\*(C'\fR. It can't really be used: it doesn't make any sense. .ie n .IP $family\->as_class 4 .el .IP \f(CW$family\fR\->as_class 4 .IX Item "$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 \f(CW$family\fR can be called as class methods on the generated class. .Sp 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 \&\f(CW\*(C`Crypt::CBC\*(C'\fR, which requires a keyable cipher algorithm to look like a Perl class, and won't operate correctly on one that looks like an object. .SH "SEE ALSO" .IX Header "SEE ALSO" Crypt::CBC, Crypt::Eksblowfish .SH AUTHOR .IX Header "AUTHOR" Andrew Main (Zefram) .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Andrew Main (Zefram) .SH LICENSE .IX Header "LICENSE" This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.