NAME
    Crypt::Twofish_PP - The Twofish Algorithm in Pure Perl

SYNOPSIS
      use Crypt::Twofish_PP;

      $cipher = Crypt::Twofish_PP->new ($key);
      $ciphertext = $cipher->encrypt ($key);
      $plaintext = $cipher->decrypt ($ciphertext);

      $keysize = $cipher->keysize;
      $blocksize = $cipher->blocksize;

      $keysize = Crypt::Twofish_PP->keysize;
      $blocksize = Crypt::Twofish_PP->blocksize;

      use Crypt::CBC;
      $cipher = Crypt::CBC->new (key    => 'my secret key',
                                 cipher => 'Twofish_PP');
      $cipher = Crypt::CBC->new (key    => 'my secret key',
                                 cipher => 'Twofish_PP::Key24');
      $cipher = Crypt::CBC->new (key    => 'my secret key',
                                 cipher => 'Twofish_PP::Key16');

      use Crypt::CBC;
      use Crypt::Twofish_PP;
      $Crypt::Twofish_PP::KEYSIZE = 24;
      $cipher = Crypt::CBC->new (key   => 'my secret key',
                                 cipher => 'Twofish_PP');
      $Crypt::Twofish_PP::KEYSIZE = 32;
      $cipher = Crypt::CBC->new (key   => 'my secret key',
                                 cipher => 'Twofish_PP');

DESCRIPTION
    Twofish is a 128-bit symmetric block cipher with a variable key length
    (128, 192, or 256 bits) key, developed by Counterpane Labs. It is
    unpatented and free for all uses, as described at
    <http://www.counterpane.com/twofish.html>. It has been one of the five
    finalists for AES.

    This module is written in pure Perl, it should run everywhere where Perl
    runs.

METHODS
    The following methods are part of the Crypt::Twofish_PP API:

    new KEY
        The constructor takes as its single argument a key of 16, 24 or 32
        bytes length. Calling it with other key lenghts, will cause the
        module to throw an exception.

    encrypt BLOCK
        Returns the encrypted block. The length of the block must be exactly
        16 bytes, otherwise the behaviour will be undefined. You can safely
        right-pad shorter blocks with null bytes.

    decrypt BLOCK
        Returns the encrypted block. The length of the block must be exactly
        16 bytes, otherwise the behaviour will be undefined. You can safely
        right-pad shorter blocks with null bytes.

    blocksize
        Returns the constant value 16.

    keysize
        Returns the length of the key in bytes. When called as a class
        method, it returns the value $Crypt::Twofish_PP::KEYSIZE which is
        initialized to 32.

CIPHER BLOCK CHAINING (CBC) MODE
    When encrypting streams of data you will need an additional block
    chaining mechanism like CBC as provided by Crypt::CBC(3). When used with
    Crypt::CBC(3), Crypt::Twofish_PP(3) will usually work with a fixed key
    length of 32 bytes, since Crypt::CBC(3) is not capable of handling
    variable length keys.

    If you need to use shorter keys with Crypt::CBC(3), you have two
    choices: You can either overwrite the variable $Crypt::CBC::KEYSIZE with
    the desired length (16 or 24) in bytes, or you can specify
    'Twofish_PP::Key16' resp. 'Twofish_PP::Key24' as the cipher algorithm to
    Crypt::CBC(3). The modules Crypt::Twofish_PP::Key32(3),
    Crypt::Twofish_PP::Key24(3), and Crypt::Twofish_PP::Key16(3), inherit
    all functionality from Crypt::Twofish_PP but overwrite the "keysize()"
    method, such that another default key length is reported back to
    Crypt::CBC(3).

UTF-8 NUISANCES
    Beginning with Perl 5.6, Perl scalars might be internally flagged as
    being UTF-8 strings, and are treated as character-oriented data, not as
    byte-oriented data (one character may require one to six bytes for its
    internal representation). In most cases you will gain nothing from the
    introduction of that flag, and rather find yourself trying to get rid of
    it. Crypt::Twofish_PP uses byte-oriented keys, and encrypts/decrypts
    blocks of 16 bytes, and it is the callers responsability to clean input
    data from that flag.

PERFORMANCE ISSUES
    The most expansive method by far is the constructor. The constructor
    will set up the key scheduling which is a time-consuming process that
    has to be repeated for every new key. Processing one 16 byte key
    currently (on my machine) takes about 15 times longer than encrypting
    one 16 byte data block with that key. If you plan to use the same key
    several times in your application, you will probably want to keep the
    encryption/decryption module around for later perusal. By the way, this
    behavior of Crypt::Twofish_PP is a typical characteristic of most modern
    encryption algorithms. Although the details may differ a lot between
    algorithms, setting up the decoder/encoder with a key usually takes a
    lot more time than performing the encryption/decryption.

    The length of your key is also important. The longer it is, the more
    time is consumed to set up the key scheduling. Once you have the module
    ready to encrypt/decrypt, the key length has no impact on performance.
    This is a general property of the Twofish algorithm, other algorithms
    show a different behavior, and may vary in speed depending on the
    particular key length (Rijndael now AES is an example for this).

    The subdirectory benchmark of the source distribution contains a script
    benchmark.pl that you can use to test the performance of a variety of
    cryptographic modules installed on your system.

    There are two other modules available on CPAN that also implement the
    Twofish algorith, but in C, not in Perl as Crypt::Twofish_PP does. Of
    course the C implementations are a lot faster than the pure Perl
    implementation, and you should rather use one of them whenever possible.
    However, at the time of this writing (November 2003), Crypt::Twofish_PP
    offers by far the fastest pure Perl 256 bit encryption available on
    CPAN. For shorter key lengths Crypt::CAST5_PP(3) is faster only when
    encrypting/decrypting large chunks of data.

ENVIRONMENT
    The environement variables LANG, LANGUAGE, LC_MESSAGES, resp. LC_ALL
    control the language for messages produced by the module. The environemt
    variable OUTPUT_CHARSET may be used to control the output character set.
    See the file README-NLS in the source distribution for details.

BUGS
    The module has been tested on big- and little-endian machines with
    integer sizes of 32 and 64 bits, and no bugs showed up. It should
    therefore be considered safe to use it everywhere.

AUTHOR
    Copyright (C) 2003, Guido Flohr <guido@imperia.net>, all rights
    reserved. See the source code for details.

    This software is contributed to the Perl community by Imperia
    (<http://www.imperia.net/>).

SEE ALSO
    Crypt::Twofish_PP::Key32(3), Crypt::Twofish_PP::Key24(3),
    Crypt::Twofish_PP::Key16(3), Crypt::CBC(3), Crypt::Twofish2(3),
    Crypt::Twofish(3), perl(1)