Crypt-Twofish2/Twofish2.pm

=head1 NAME

Crypt::Twofish2 - Crypt::CBC compliant Twofish encryption module

=head1 SYNOPSIS

 use Crypt::Twofish2;

 # keysize() is 32, but 24 and 16 are also possible
 # blocksize() is 16

 $cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC;

 $crypted = $cipher->encrypt($plaintext);
 # - OR -
 $plaintext = $cipher->decrypt($crypted);

=head1 DESCRIPTION

This module implements the twofish cipher in a less braindamaged (read:
slow and ugly) way than the existing C<Crypt::Twofish> module.

Although it is C<Crypt::CBC> compliant you usually gain nothing by using
that module (except generality, which is often a good thing), since
C<Crypt::Twofish2> can work in either ECB or CBC mode itself.

=over 4

=cut

package Crypt::Twofish2;

require DynaLoader;

$VERSION = '1.01';
@ISA = qw/DynaLoader/;

bootstrap Crypt::Twofish2 $VERSION;

=item keysize

Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually
supports keylengths of 16, 24 or 32 bytes, but there is no way to
communicate this to C<Crypt::CBC>.

=item blocksize

The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat
unique. It is also the reason I need this module myself ;)

=item $cipher = new $key [, $mode]

Create a new C<Crypt::Twofish2> cipher object with the given key (which
must be 128, 192 or 256 bits long). The additional C<$mode> argument is
the encryption mode, either C<MODE_ECB> (electronic cookbook mode, the
default), C<MODE_CBC> (cipher block chaining, the same that C<Crypt::CBC>
does) or C<MODE_CFB1> (1-bit cipher feedback mode).

ECB mode is very insecure (read a book on cryptography if you don't know
why!), so you should probably use CBC mode. CFB1 mode is not tested and is
most probably broken, so do not try to use it.

In ECB mode you can use the same cipher object to encrypt and decrypt
data. However, every change of "direction" causes an internal reordering
of key data, which is quite slow, so if you want ECB mode and
encryption/decryption at the same time you should create two seperate
C<Crypt::Twofish2> objects with the same key.

In CBC mode you have to use seperate objects for encryption/decryption in
any case.

The C<MODE_*>-constants are not exported by this module, so you must
specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).

=item $cipher->encrypt($data)

Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16
bytes), otherwise this function will croak. Apart from that, it can be of
(almost) any length.

=item $cipher->decrypt($data)

The pendant to C<encrypt> in that it I<de>crypts data again.

=back

=head1 SEE ALSO

L<Crypt::CBC>, L<Crypt::Twofish>.

=head1 BUGS

Should EXPORT or EXPORT_OK the MODE constants.

There should be a way to access initial IV contents :(

Although I tried to make the original twofish code portable, I can't say
how much I did succeed. The code tries to be portable itself, and I hope
I got the endianness issues right. The code is also copyright Counterpane
Systems, no license accompanied it, so using it might actually be illegal
;)

I also cannot guarantee for security, but the module is used quite a bit,
so there are no obvious bugs left.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

 The actual twofish encryption is written in horribly microsoft'ish looking
 almost ansi-c by Doug Whiting.

=cut

1;

Revision:	1.4
Committed:	Thu Mar 3 17:22:20 2005 UTC (19 years, 2 months ago) by root
Branch:	MAIN
Changes since 1.3:	+2 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Crypt::Twofish2 - Crypt::CBC compliant Twofish encryption module
4
5			=head1 SYNOPSIS
6
7			use Crypt::Twofish2;
8
9			# keysize() is 32, but 24 and 16 are also possible
10			# blocksize() is 16
11
12			$cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC;
13
14			$crypted = $cipher->encrypt($plaintext);
15			# - OR -
16			$plaintext = $cipher->decrypt($crypted);
17
18			=head1 DESCRIPTION
19
20			This module implements the twofish cipher in a less braindamaged (read:
21			slow and ugly) way than the existing C<Crypt::Twofish> module.
22
23			Although it is C<Crypt::CBC> compliant you usually gain nothing by using
24			that module (except generality, which is often a good thing), since
25			C<Crypt::Twofish2> can work in either ECB or CBC mode itself.
26
27			=over 4
28
29			=cut
30
31			package Crypt::Twofish2;
32
33			require DynaLoader;
34
35	root	1.4	$VERSION = '1.01';
36	root	1.1	@ISA = qw/DynaLoader/;
37
38			bootstrap Crypt::Twofish2 $VERSION;
39
40			=item keysize
41
42			Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually
43			supports keylengths of 16, 24 or 32 bytes, but there is no way to
44			communicate this to C<Crypt::CBC>.
45
46			=item blocksize
47
48			The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat
49			unique. It is also the reason I need this module myself ;)
50
51			=item $cipher = new $key [, $mode]
52
53			Create a new C<Crypt::Twofish2> cipher object with the given key (which
54			must be 128, 192 or 256 bits long). The additional C<$mode> argument is
55			the encryption mode, either C<MODE_ECB> (electronic cookbook mode, the
56			default), C<MODE_CBC> (cipher block chaining, the same that C<Crypt::CBC>
57			does) or C<MODE_CFB1> (1-bit cipher feedback mode).
58
59			ECB mode is very insecure (read a book on cryptography if you don't know
60			why!), so you should probably use CBC mode. CFB1 mode is not tested and is
61			most probably broken, so do not try to use it.
62
63			In ECB mode you can use the same cipher object to encrypt and decrypt
64			data. However, every change of "direction" causes an internal reordering
65			of key data, which is quite slow, so if you want ECB mode and
66			encryption/decryption at the same time you should create two seperate
67			C<Crypt::Twofish2> objects with the same key.
68
69			In CBC mode you have to use seperate objects for encryption/decryption in
70			any case.
71
72			The C<MODE_*>-constants are not exported by this module, so you must
73			specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).
74
75			=item $cipher->encrypt($data)
76
77			Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16
78			bytes), otherwise this function will croak. Apart from that, it can be of
79			(almost) any length.
80
81			=item $cipher->decrypt($data)
82
83			The pendant to C<encrypt> in that it I<de>crypts data again.
84
85			=back
86
87			=head1 SEE ALSO
88
89			L<Crypt::CBC>, L<Crypt::Twofish>.
90
91			=head1 BUGS
92
93			Should EXPORT or EXPORT_OK the MODE constants.
94
95			There should be a way to access initial IV contents :(
96
97			Although I tried to make the original twofish code portable, I can't say
98			how much I did succeed. The code tries to be portable itself, and I hope
99			I got the endianness issues right. The code is also copyright Counterpane
100			Systems, no license accompanied it, so using it might actually be illegal
101			;)
102
103			I also cannot guarantee for security, but the module is used quite a bit,
104			so there are no obvious bugs left.
105
106			=head1 AUTHOR
107
108	root	1.4	Marc Lehmann <schmorp@schmorp.de>
109	root	1.3	http://home.schmorp.de/
110	root	1.1
111			The actual twofish encryption is written in horribly microsoft'ish looking
112			almost ansi-c by Doug Whiting.
113
114			=cut
115
116			1;
117