• Home
  • History
  • Annotate
  • current directory
Name Date Size #Lines LOC

..16-Aug-2019-

benchmark/H16-Aug-2019-

lib/H27-Nov-2003-

po/H27-Nov-2003-

t/H27-Nov-2003-

ArtisticH A D21-Nov-20036 KiB13299

MANIFESTH A D26-Nov-2003712 3231

Makefile.PLH A D27-Nov-20031.1 KiB5132

READMEH A D27-Nov-20036.8 KiB153125

README-NLSH A D24-Nov-20039.5 KiB201157

TRANSLATIONSH A D24-Nov-20031.4 KiB3224

README

1NAME
2    Crypt::Twofish_PP - The Twofish Algorithm in Pure Perl
3
4SYNOPSIS
5      use Crypt::Twofish_PP;
6
7      $cipher = Crypt::Twofish_PP->new ($key);
8      $ciphertext = $cipher->encrypt ($key);
9      $plaintext = $cipher->decrypt ($ciphertext);
10
11      $keysize = $cipher->keysize;
12      $blocksize = $cipher->blocksize;
13
14      $keysize = Crypt::Twofish_PP->keysize;
15      $blocksize = Crypt::Twofish_PP->blocksize;
16
17      use Crypt::CBC;
18      $cipher = Crypt::CBC->new (key    => 'my secret key',
19                                 cipher => 'Twofish_PP');
20      $cipher = Crypt::CBC->new (key    => 'my secret key',
21                                 cipher => 'Twofish_PP::Key24');
22      $cipher = Crypt::CBC->new (key    => 'my secret key',
23                                 cipher => 'Twofish_PP::Key16');
24
25      use Crypt::CBC;
26      use Crypt::Twofish_PP;
27      $Crypt::Twofish_PP::KEYSIZE = 24;
28      $cipher = Crypt::CBC->new (key   => 'my secret key',
29                                 cipher => 'Twofish_PP');
30      $Crypt::Twofish_PP::KEYSIZE = 32;
31      $cipher = Crypt::CBC->new (key   => 'my secret key',
32                                 cipher => 'Twofish_PP');
33
34DESCRIPTION
35    Twofish is a 128-bit symmetric block cipher with a variable key length
36    (128, 192, or 256 bits) key, developed by Counterpane Labs. It is
37    unpatented and free for all uses, as described at
38    <http://www.counterpane.com/twofish.html>. It has been one of the five
39    finalists for AES.
40
41    This module is written in pure Perl, it should run everywhere where Perl
42    runs.
43
44METHODS
45    The following methods are part of the Crypt::Twofish_PP API:
46
47    new KEY
48        The constructor takes as its single argument a key of 16, 24 or 32
49        bytes length. Calling it with other key lenghts, will cause the
50        module to throw an exception.
51
52    encrypt BLOCK
53        Returns the encrypted block. The length of the block must be exactly
54        16 bytes, otherwise the behaviour will be undefined. You can safely
55        right-pad shorter blocks with null bytes.
56
57    decrypt BLOCK
58        Returns the encrypted block. The length of the block must be exactly
59        16 bytes, otherwise the behaviour will be undefined. You can safely
60        right-pad shorter blocks with null bytes.
61
62    blocksize
63        Returns the constant value 16.
64
65    keysize
66        Returns the length of the key in bytes. When called as a class
67        method, it returns the value $Crypt::Twofish_PP::KEYSIZE which is
68        initialized to 32.
69
70CIPHER BLOCK CHAINING (CBC) MODE
71    When encrypting streams of data you will need an additional block
72    chaining mechanism like CBC as provided by Crypt::CBC(3). When used with
73    Crypt::CBC(3), Crypt::Twofish_PP(3) will usually work with a fixed key
74    length of 32 bytes, since Crypt::CBC(3) is not capable of handling
75    variable length keys.
76
77    If you need to use shorter keys with Crypt::CBC(3), you have two
78    choices: You can either overwrite the variable $Crypt::CBC::KEYSIZE with
79    the desired length (16 or 24) in bytes, or you can specify
80    'Twofish_PP::Key16' resp. 'Twofish_PP::Key24' as the cipher algorithm to
81    Crypt::CBC(3). The modules Crypt::Twofish_PP::Key32(3),
82    Crypt::Twofish_PP::Key24(3), and Crypt::Twofish_PP::Key16(3), inherit
83    all functionality from Crypt::Twofish_PP but overwrite the "keysize()"
84    method, such that another default key length is reported back to
85    Crypt::CBC(3).
86
87UTF-8 NUISANCES
88    Beginning with Perl 5.6, Perl scalars might be internally flagged as
89    being UTF-8 strings, and are treated as character-oriented data, not as
90    byte-oriented data (one character may require one to six bytes for its
91    internal representation). In most cases you will gain nothing from the
92    introduction of that flag, and rather find yourself trying to get rid of
93    it. Crypt::Twofish_PP uses byte-oriented keys, and encrypts/decrypts
94    blocks of 16 bytes, and it is the callers responsability to clean input
95    data from that flag.
96
97PERFORMANCE ISSUES
98    The most expansive method by far is the constructor. The constructor
99    will set up the key scheduling which is a time-consuming process that
100    has to be repeated for every new key. Processing one 16 byte key
101    currently (on my machine) takes about 15 times longer than encrypting
102    one 16 byte data block with that key. If you plan to use the same key
103    several times in your application, you will probably want to keep the
104    encryption/decryption module around for later perusal. By the way, this
105    behavior of Crypt::Twofish_PP is a typical characteristic of most modern
106    encryption algorithms. Although the details may differ a lot between
107    algorithms, setting up the decoder/encoder with a key usually takes a
108    lot more time than performing the encryption/decryption.
109
110    The length of your key is also important. The longer it is, the more
111    time is consumed to set up the key scheduling. Once you have the module
112    ready to encrypt/decrypt, the key length has no impact on performance.
113    This is a general property of the Twofish algorithm, other algorithms
114    show a different behavior, and may vary in speed depending on the
115    particular key length (Rijndael now AES is an example for this).
116
117    The subdirectory benchmark of the source distribution contains a script
118    benchmark.pl that you can use to test the performance of a variety of
119    cryptographic modules installed on your system.
120
121    There are two other modules available on CPAN that also implement the
122    Twofish algorith, but in C, not in Perl as Crypt::Twofish_PP does. Of
123    course the C implementations are a lot faster than the pure Perl
124    implementation, and you should rather use one of them whenever possible.
125    However, at the time of this writing (November 2003), Crypt::Twofish_PP
126    offers by far the fastest pure Perl 256 bit encryption available on
127    CPAN. For shorter key lengths Crypt::CAST5_PP(3) is faster only when
128    encrypting/decrypting large chunks of data.
129
130ENVIRONMENT
131    The environement variables LANG, LANGUAGE, LC_MESSAGES, resp. LC_ALL
132    control the language for messages produced by the module. The environemt
133    variable OUTPUT_CHARSET may be used to control the output character set.
134    See the file README-NLS in the source distribution for details.
135
136BUGS
137    The module has been tested on big- and little-endian machines with
138    integer sizes of 32 and 64 bits, and no bugs showed up. It should
139    therefore be considered safe to use it everywhere.
140
141AUTHOR
142    Copyright (C) 2003, Guido Flohr <guido@imperia.net>, all rights
143    reserved. See the source code for details.
144
145    This software is contributed to the Perl community by Imperia
146    (<http://www.imperia.net/>).
147
148SEE ALSO
149    Crypt::Twofish_PP::Key32(3), Crypt::Twofish_PP::Key24(3),
150    Crypt::Twofish_PP::Key16(3), Crypt::CBC(3), Crypt::Twofish2(3),
151    Crypt::Twofish(3), perl(1)
152
153

README-NLS

1Notes on National Language Support (NLS)
2****************************************
3
4This package is internationalized with libintl-perl, a free
5internationalization library for Perl, you will need to install a copy of
6libintl-perl in order to use the package.  You can get libintl-perl from the
7Comprehensive Perl Archive Network CPAN at http://www.cpan.org/.
8
9The following notes are meant to be a quick start guide for somewhat
10experienced users and system administrators and many important details had to
11be omitted for brevity.  If you have any difficulties with the
12internationalization features of this package, no matter if you are a
13programmer, a translator, or an end user, feel free to ask at the mailing list
14for libintl-perl.  To do so, send an e-mail to the address
15<libintl-perl AT imperia DOT net> (please replace "AT" with a "@", and "DOT"
16with a dot ".").
17
18You can subscribe to this list at
19
20     http://ml.imperia.org/mailman/listinfo/libintl-perl
21
22A searchable archive of earlier postings is located at
23
24     http://ml.imperia.org/libintl-perl/
25
26You may already find an answer to your question there.
27
28Feel free to include this document in your own Perl packages internationalized
29with libintl-perl, no severe copyright restrictions apply.  You should send
30corrections or improvements to the author Guido Flohr <guido AT imperia DOT
31net>, so that others can benefit from your changes.
32
33The End User's View
34===================
35
36The installation routine for this package will automatically take care that
37your system has a sufficient version of libintl-perl installed.  This is
38basically sufficient for proper operation, but - especially if
39internationalized software is new to you - you should read on carefully in
40order to fully benefit from the internationalization (I18N) features of this
41package.
42
43Perl Setup
44----------
45
46The I18N library libintl-perl will run with a wide range of Perl versions (at
47least from Perl version 5.005_03 to Perl 5.8.0) but you will experience slight
48difference in features and performance depending on the version of Perl you
49use.
50
51With Perl versions prior to 5.7.3 you can use the package for all European
52scripts (including those with Greek or Cyrillic scripts), and also for many
53scripts used outside Europe, like Arabic, Hebrew, Georgian, Vietnamese or
54Thai, more general all scripts using 8 bit charsets.  Other scripts are only
55available if the translations in this package are provided in Unicode and they
56can only be output in Unicode.
57
58Beginning with Perl 5.7.3 the module Encode became part of the Perl core, and
59it offers you a much wider range of possible scripts.  If you plan to use some
60of the lesser used scripts for Chinese, Japanese, and Korean, you should also
61install the module Encode::HanExtra.
62
63Setting Your Language
64---------------------
65
66Most modern systems are already prepared and configured for
67internationalization, and the user interface of the software you have
68installed will already be configured for your preferred language.  Packages
69internationalized with libintl-perl will honor these configuration settings
70and will also operate in your preferred language if the necessary translations
71are available.
72
73The environment variable "LANGUAGE" has the highest precedence for
74translations.  The most common format for this environment variable is a
75(lowercase) two-letter language code and an (uppercase) two-letter country
76code separated by an underscore "_", for example:
77
78     LANGUAGE=fr_BE
79     export LANGUAGE
80
81This will set your language preferences to French ("fr") for Belgium ("BE").
82Other examples are French for France ("fr_FR"), German for Austria ("de_AT"),
83and so on.  You can also omit the country part ("FR", "DE", "IT", "RU", ...)
84in which case a default setting for the country will be assumed.
85
86If there are no translations available for your selected languages, the
87original message (normally in English) will be displayed.
88
89You can also define a chain of languages to be tried separated by a colon:
90
91     LANGUAGE=fr_BE:fr_FR:fr:it
92
93Read this as: "I want translations in French for Belgium.  If they are not
94available try French for France, then any French translation, and finally
95Italian".  Please note that this chain notation is only allowed for the
96environment variable "LANGUAGE", it is not valid for any of the following
97variables.
98
99If "LANGUAGE" is not set, the library checks the variable "LANG".  It has the
100same syntax as "LANGUAGE" but does not allow the preferences chain with the
101colon syntax.  After "LANG" the variable "LC_MESSAGES" (think "locale category
102messages") is tried, and finally "LC_ALL".
103
104Note for Microsoft Windows users: The locale preferences you have configured
105for your system cannot yet be evaluated by libintl-perl.  This may change for
106future versions of libintl-perl but for the moment you have to make do with
107the instructions given above.  In order to set environment variables, you have
108to right-click on the icon "My Computer" on your desktop, select "Properties"
109in the context menu, and then click the tab labelled "Environment variables".
110
111Setting the Output Charset
112--------------------------
113
114Even if you have managed to properly select your preferred language, you may
115still have difficulties reading the program languages, because libintl-perl
116was unable to determine the correct charset to use for messages.  For example,
117it may assume Unicode ("UTF-8") but you really need ISO-Latin-1 (also known as
118"Latin-1" or "ISO-8859-1").  If this is the case, please set the environment
119variable "OUTPUT_CHARSET" to the appropriate value, for example:
120
121     OUTPUT_CHARSET=iso-8859-1
122     export OUTPUT_CHARSET
123
124Charset names are case-insensitive, i. e. "LATIN-1" is the equivalent to
125"Latin-1" or even "lAtIn-1".
126
127Note: The output charset "utf8" is NOT recognized.  Please use the correct
128abbreviation "utf-8" (with a hyphen) instead.
129
130The Translator's View
131=====================
132
133If you want to contribute a new translation to this package, please contact
134the author first.  Somebody may have already started this translation, and
135furthermore the package author will be able to give you detailled instructions
136and help.
137
138Translating a Perl package is not much work and it does not require any
139technical skills.  If you are able to use the software itself, you will also
140be able to contribute a translation for your language.  But why should you do
141that? You are able to read and understand this text and you will also be able
142to understand the English messages that the software spits out by default.
143
144Computers are an integral part of today's society.  Computers are used to
145explore new sources of information, forbidding computers would be a modern
146form of censorship.  Computers may also improve social life, the internet
147helps people to find contacts in their area and all over the world, even if
148they would otherwise be deprived from that because of a handicap, lack of money
149for traveling, or other reasons.  In many societies, the ability to use and
150handle a computer also has a strong impact on your perspectives in life, you
151may not be able to find an adequate job because of your lack of computer
152experience, or you may even lose your job because of that.
153
154Everybody should benefit from computers, regardless of cultural
155background. Computers are expansive goods, and their price is already a high
156barrier to cross.  If computers speak in a foreign language, the learning
157curve gets steeper and the barrier gets even higher.  You can help the people
158that share your native language by contributing a translation.  The author of
159this package has already prepared everything, the rest is up to you!
160
161The Programmer's View
162=====================
163
164You have downloaded this package because you want to use it in your own
165project(s).  The fact that the package is internationalized with libintl-perl
166does not affect its usability in any way.  But you should keep in mind that
167textual messages produced by the package may change according to the locale
168settings at run-time.  This can lead to errors.  For example, if you parse
169error messages produced by the package, you will most probably fail to detect
170what you are looking for, if these error messages are suddenly presented in
171another language or another output charset.
172
173It is probably needless to say that this is bad practice and an indicator for
174a poorly written interface.  Either you have missed the correct method for
175determining the substance of the message in a locale-independent manner, or
176the author of the package has mis-designed the package interface.  In any
177case, this is a technical problem that should be solved by technicians.  You
178should not put that burden on the shoulders of your users but rather solve the
179problem in cooperation with the author of the module that causes it.
180
181If this is absolutely impossible, as a temporary workaround you can completely
182switch off the native language support of the package by setting the
183environment variable "LANGUAGE" to the special value "C":
184
185     BEGIN {
186         $ENV{LANGUAGE} = $ENV{LANG} = "C";
187     }
188
189The value "C" instructs libintl-perl to leave all messages untouched, and you
190can use the package as if it was not internationalized at all.
191
192If the project you are working on is not yet internationalized, you should
193consider to prepare it for internationalization now.  Doing so is only little
194work for yourself, but results in a large benefit for the users of your
195software.  The package "libintl-perl" ships with exhaustive documentation for
196programmers and a sample package that you can use as a skeleton for your own
197project(s).  Internationalizing Perl software with libintl-perl is easy, the
198package that this file is a part of, prooves that.
199
200Guido Flohr
201