[ViewVC] Annotation of: cvs/Crypt-Twofish2/README

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

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);

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

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

    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 "Crypt::CBC".

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

    $cipher = new $key [, $mode]
        Create a new "Crypt::Twofish2" cipher object with the given key
        (which must be 128, 192 or 256 bits long). The additional $mode
        argument is the encryption mode, either "MODE_ECB" (electronic
        cookbook mode, the default), "MODE_CBC" (cipher block chaining, the
        same that "Crypt::CBC" does) or "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 "Crypt::Twofish2" objects with the same key.

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

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

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

    $cipher->decrypt($data)
        The pendant to "encrypt" in that it *de*crypts data again.

SEE ALSO
    Crypt::CBC, Crypt::Twofish.

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.

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.

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