<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">=head1 NAME

Crypt::Eksblowfish::Family - Eksblowfish cipher family

=head1 SYNOPSIS

	use Crypt::Eksblowfish::Family;

	$family = Crypt::Eksblowfish::Family-&gt;new_family(8, $salt);

	$cost = $family-&gt;cost;
	$salt = $family-&gt;salt;
	$block_size = $family-&gt;blocksize;
	$key_size = $family-&gt;keysize;
	$cipher = $family-&gt;new($key);

=head1 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 L&lt;Crypt::Eksblowfish&gt;
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 C&lt;Crypt::CBC&gt;.  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 C&lt;new&gt;
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 C&lt;new&gt; constructor.

=head2 Crypt::CBC

C&lt;Crypt::CBC&gt; 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 C&lt;Crypt::CBC&gt;
as described above: an object of this class would be accepted by
C&lt;Crypt::CBC&gt; as a cipher algorithm, and C&lt;Crypt::CBC&gt; would happily
supply it with a key and encrypt using the resulting cipher object.
C&lt;Crypt::CBC&gt; 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 C&lt;Crypt::CBC&gt; got hold of the wrong end of the stick, and
ended up changing C&lt;Crypt::CBC&gt; in a way that totally breaks this usage,
rather than putting it on a secure footing.

The present behaviour of C&lt;Crypt::CBC&gt; 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 C&lt;Crypt::CBC&gt;'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 C&lt;Crypt::CBC&gt;,
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 L&lt;/as_class&gt;.

=cut

package Crypt::Eksblowfish::Family;

{ use 5.006; }
use warnings;
use strict;

use Carp qw(croak);
use Crypt::Eksblowfish 0.005;
use Class::Mix 0.001 qw(genpkg);

our $VERSION = "0.009";

=head1 CONSTRUCTOR

=over

=item Crypt::Eksblowfish::Family-&gt;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.

=cut

sub new_family {
	my($class, $cost, $salt) = @_;
	return bless({ cost =&gt; $cost, salt =&gt; $salt }, $class);
}

=back

=head1 METHODS

=over

=item $family-&gt;cost

Extracts and returns the cost parameter.

=cut

sub cost { $_[0]-&gt;{cost} }

=item $family-&gt;salt

Extracts and returns the salt parameter.

=cut

sub salt { $_[0]-&gt;{salt} }

=item $family-&gt;blocksize

Returns 8, indicating the Eksblowfish block size of 8 octets.

=cut

sub blocksize { 8 }

=item $family-&gt;keysize

Returns 0, indicating that the key size is variable.  This situation is
handled specially by C&lt;Crypt::CBC&gt;.

=cut

sub keysize { 0 }

=item $family-&gt;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 C&lt;Crypt::Eksblowfish&gt;;
see L&lt;Crypt::Eksblowfish&gt; for the encryption and decryption methods.

Note that this method is called on a family object, not on the class
C&lt;Crypt::Eksblowfish::Family&gt;.

=cut

sub new {
	my($self, $key) = @_;
	croak "Crypt::Eksblowfish::Family::new is not a class method ".
			"(perhaps you want new_family instead)"
		if ref($self) eq "";
	return Crypt::Eksblowfish-&gt;new($self-&gt;{cost}, $self-&gt;{salt}, $key);
}

=item $family-&gt;encrypt

This method nominally exists, to satisfy C&lt;Crypt::CBC&gt;.  It can't really
be used: it doesn't make any sense.

=cut

sub encrypt { croak "Crypt::Eksblowfish::Family::encrypt called" }

=item $family-&gt;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
C&lt;Crypt::CBC&gt;, which requires a keyable cipher algorithm to look like a
Perl class, and won't operate correctly on one that looks like an object.

=cut

sub as_class {
	my($self) = @_;
	return $self-&gt;{as_class} ||= do {
		my $pkg = genpkg(__PACKAGE__."::");
		no strict "refs";
		@{"${pkg}::ISA"} = (ref($self));
		*{"${pkg}::new_family"} =
			sub { croak $_[0]."-&gt;new_family called" };
		*{"${pkg}::cost"} = sub { $self-&gt;cost };
		*{"${pkg}::salt"} = sub { $self-&gt;salt };
		*{"${pkg}::new"} = sub { shift; $self-&gt;new(@_) };
		*{"${pkg}::as_class"} = sub { $pkg };
		$pkg;
	};
}

=back

=head1 SEE ALSO

L&lt;Crypt::CBC&gt;,
L&lt;Crypt::Eksblowfish&gt;

=head1 AUTHOR

Andrew Main (Zefram) &lt;zefram@fysh.org&gt;

=head1 COPYRIGHT

Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011
Andrew Main (Zefram) &lt;zefram@fysh.org&gt;

=head1 LICENSE

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

1;
</pre></body></html>