This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Convert/Translit, Next: Convert/UU, Prev: Convert/TNEF, Up: Module List Perl module for string conversion among numerous character sets *************************************************************** NAME ==== Convert::Translit, transliterate, build_substitutes - Perl module for string conversion among numerous character sets SYNOPSIS ======== use Convert::Translit; $translator = new Convert::Translit($result_chset); $translator = new Convert::Translit($orig_chset, $result_chset); $translator = new Convert::Translit($orig_chset, $result_chset, $verbose); $result_st = $translator->transliterate($orig_st); $result_st = Convert::Translit::transliterate($orig_st); build_substitutes Convert::Translit(); Convert::Translit::build_substitutes(); DESCRIPTION =========== This module converts strings among 8-bit character sets defined by IETF RFC 1345 (about 128 sets). The RFC document is included so you can look up character set names and aliases; it's also read by the module when composing conversion maps. Failing functions or objects return undef value. Export_OK Functions: transliterate() returns a string in $result_chset for an argument string in $orig_chset, transliterating by a map composed by new(). build_substitutes() rebuilds the file "substitutes" containing character definitions and approximate substitutions used when a character in $orig_chset isn't defined in $result_chset. For example, "Latin capital A" may be substituted for "Latin capital A with ogonek". It takes a long time to rebuild this file, but you should never need to. Its only source of information is file "rfc1345". Object methods: new() creates a new object for converting from $orig_chset to $result_chset, these being names (or aliases) of 8-bit character sets defined in RFC 1345. If only one argument, then $orig_chset is assumed "ascii". If three arguments, the third is verbosity flag. Verbose output lists approximate substitutions and other compromises. transliterate() is same as the function of that name. build_substitutes() is same as the function of that name. FILES ===== Convert/Translit/rfc1345 (IETF RFC 1345, June 1992) Convert/Translit/substitutes METHODOLGY ========== Only one-to-one character mapping is done, so characters with diacritics (like A-ogonek) are never converted to (letter character, diacritic character) pairs, rather are subject to simplification. If no approximate substitute is available, then a unrelated substitute is chosen, preferably with the same code value. Undefined $orig_chset characters are translated to a chosen indicator character. Transliteration is not guaranteed commutative when substitutions were required. An $orig_chset defined as 7-bit is assumed to be repeated to make an 8-bit set (in the style of "extended ascii"); no such adjustment is made for $result_chset. The few mistakes in the RFC document are corrected in the module. EXAMPLES ======== Convert Russian language text from IBM to ASCII encoding: $xxx = new Convert::Translit("EBCDIC-Cyrillic", "Cyrillic"); $ascii_cyr_st = $xxx->transliterate($ibm_cyr_st); Convert from plain ASCII (default $orig_chset) to Latin2 (Central European): $yyy = new Convert::Translit("Latin2"); $cnt_eur_st = $yyy->transliterate($ascii_st); Since plain ASCII is subset of Latin2, nothing is lost in transliteration. But going the other direction requires numerous simplifications: $zzz = new Convert::Translit("Latin2", "ascii"); $ascii_st = $zzz->transliterate($cnt_eur_st); Back to ASCII again, although substitutions probably mean ($again ne $cnt_eur_st): $again = $yyy->transliterate($ascii_st); The example.pl script converts a Polish language phrase from Latin2 to EBCDIC-US. PORTABILITY =========== Requires Perl version 5. Developed with MacPerl on Macintosh 68040 OS 7.6.1. Tested on Sun Unix 4.1.3. AUTHOR ====== Genji Schmeder Enjoy in good health. Cieszcie sie dobrym zdrowiem. Que gozen con salud. Benutze es heilsam gern! Genki dewa, yorokobi nasai. COPYRIGHT ========= Version 1.03 dated 5 November 1997. Copyright (c) 1997 Genji Schmeder. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ACKNOWLEDGEMENTS ================ Chris Leach, author of EBCDIC.pm Keld Simonsen, author of RFC 1345  File: pm.info, Node: Convert/UU, Next: Convert/UUlib, Prev: Convert/Translit, Up: Module List Perl module for uuencode and uudecode ************************************* NAME ==== Convert::UU, uuencode, uudecode - Perl module for uuencode and uudecode SYNOPSIS ======== use Convert::UU qw(uudecode uuencode); $encoded_string = uuencode($string,[$filename],[$mode]); ($string,$filename,$mode) = uudecode($string); $string = uudecode($string); # in scalar context DESCRIPTION =========== uuencode() takes as the first argument a string that is to be uuencoded. Note, that it is the string that is encoded, not a filename. Alternatively a filehandle may be passed that must be opened for reading. It returns the uuencoded string including begin and end. Second and third argument are optional and specify filename and mode. If unspecified these default to "uuencode.uu" and 644. uudecode() takes a string as argument which will be uudecoded. If the argument is a filehandle this handle will be read instead. If it is a reference to an ARRAY, the elements are treated like lines that form a string. Leading and trailing garbage will be ignored. The function returns the uudecoded string for the first begin/end pair. In array context it returns an array whose first element is the uudecoded string, the second is the filename and the third is the mode. EXPORT ====== Both uudecode and uuencode are in @EXPORT_OK. AUTHOR ====== Andreas Koenig . With code integrated that was posted to USENET from Hans Mulder and Randal L. Schwartz . SEE ALSO ======== puuencode(1), puudecode(1) for examples of how to use this module.  File: pm.info, Node: Convert/UUlib, Next: Convert/Units/Base, Prev: Convert/UU, Up: Module List Perl interface to the uulib library (a.k.a. uudeview/uuenview). *************************************************************** NAME ==== Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview). SYNOPSIS ======== use Convert::UUlib; DESCRIPTION =========== Read the file uulibdoc.dvi.gz and the example-decoder source. Sorry - more to come once people use me ;) SMALL EXAMPLE DECODER ===================== The following code excerpt is a minimal decoder program. It reads all files given on the commandline and decodes any files in it. use Convert::UUlib ':all'; LoadFile($_) for @ARGV; for($i=0; $uu=GetFileListItem($i); $i++) { $uu->decode if $uu->state & FILE_OK; } LARGE EXAMPLE DECODER ===================== This is the file `example-decoder' from the distribution, put here instead of more thorough documentation. # decode all the files in the directory uusrc/ and copy # the resulting files to uudst/ use Convert::UUlib ':all'; sub namefilter { my($path)=@_; $path=~s/^.*[\/\\]//; $path; } sub busycb { my($action,$curfile,$partno,$numparts,$percent,$fsize)=@_; $_[0]=straction($action); print "busy_callback(",join(",",@_),")\n"; 0; } SetOption (OPT_IGNMODE, 1); SetOption (OPT_VERBOSE, 1); # show the three ways you can set callback functions SetFNameFilter (\&namefilter); SetBusyCallback ("busycb",333); SetMsgCallback (sub { my($msg,$level)=@_; print uc(strmsglevel($_[1])),": $msg\n"; }); for() { my($retval,$count)=LoadFile ($_,$_,1); print "file($_), status(",strerror($retval),") parts($count)\n"; } SetOption (OPT_SAVEPATH, "uudst/"); $i=0; while($uu=GetFileListItem($i)) { $i++; print "file nr. $i"; print " state ",$uu->state; print " mode ",$uu->mode; print " uudet ",strencoding($uu->uudet); print " size ",$uu->size; print " filename ",$uu->filename; print " subfname ",$uu->subfname; print " mimeid ",$uu->mimeid; print " mimetype ",$uu->mimetype; print "\n"; # print additional info about all parts for($uu->parts) { while(my($k,$v)=each(%$_)) { print "$k > $v, "; } print "\n"; } $uu->decode_temp; print " temporarily decoded to ",$uu->binfile,"\n"; $uu->remove_temp; print strerror($uu->decode); print " saved as uudst/",$uu->filename,"\n"; } print "cleanup...\n"; CleanUp(); Exported constants ================== Action code constants: ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING File status flags: FILE_DECODED FILE_ERROR FILE_MISPART FILE_NOBEGIN FILE_NODATA FILE_NOEND FILE_OK FILE_READ FILE_TMPFILE Message severity levels: MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING Options: OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE OPT_VERSION Error/Result codes: RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA RET_NOEND RET_NOMEM RET_OK RET_UNSUP Encoding types: B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED XX_ENCODED UU_ENCODED Exported functions ================== Initializing and cleanup (Initialize is automatically called when the module is loaded and allocates quite a bit of memory. CleanUp releases that again). Initialize; # not normally necessary CleanUp; # could be called at the end to release memory Setting and querying options: $option = GetOption OPT_xxx; SetOption OPT_xxx, opt-value; Error and action values => stringified: $msg = straction ACT_xxx; $msg = strerror RET_xxx; Setting various callbacks: SetMsgCallback [callback-function]; SetBusyCallback [callback-function]; SetFileCallback [callback-function]; SetFNameFilter [callback-function]; Call the currently selected FNameFilter: $file = FNameFilter $file; Loading sourcefiles, optionally fuzzy merge and start decoding: ($retval, $count) = LoadFile $fname, [$id, [$delflag]]; $retval = Smerge $pass; $item = GetFileListItem $item_number; The procedural interface is undocumented, use the following methods instead: $retval = $item->rename($newname); $retval = $item->decode_temp; $retval = $item->remove_temp; $retval = $item->decode([$target_path]); $retval = $item->info(callback-function); Querying (and setting) item attributes: $state = $item->state; $mode = $item->mode([newmode]); $uudet = $item->uudet; $size = $item->size; $filename = $item->filename([newfilename}); $subfname = $item->subfname; $mimeid = $item->mimeid; $mimetype = $item->mimetype; $binfile = $item->binfile; Totally undocumented and unsupported(!): $parts = $item->parts; Functions below not documented and not very well tested: int QuickDecode () ; int EncodeMulti () ; int EncodePartial () ; int EncodeToStream () ; int EncodeToFile () ; int E_PrepSingle () ; int E_PrepPartial () ; AUTHOR ====== Marc Lehmann , the original uulib library was written by Frank Pilhofer . SEE ALSO ======== perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.  File: pm.info, Node: Convert/Units/Base, Next: Coy, Prev: Convert/UUlib, Up: Module List base object for performing unit conversions ******************************************* NAME ==== Convert::Units::Base - base object for performing unit conversions DESCRIPTION =========== The Units package is a collection of modules for parsing strings with unit measurements (such as "12pt" or "3 meters") and converting them to some other unit (such as "picas" or "inches"). It uses a base package (Units::Base) which does the dirty work. Other modules define what units they handle and how they are related. Why a Separate Module? ---------------------- It is *intentionally* distinct from the *Math::Units* module. Why? The *Math::Units* module implies that unit conversions are *exact*, with one-to-one relationships. This is fine for scientific work. It's even fine for some general purpose/real-world uses (such as converting Fehrenheight to Celcius). Real-world measurement systems are conflicting. For instance, a "point" in typography is equivalent to 1/72 inch, according to PostScript specs and common usage. Other type systems consider it 1/72.27 inch, or 0.01383 inches, or 0.0148 inches. Outside of that context, a point may be 1/120 or 1/144 inch. Common notations and abbreviations also depend on context. Does "12 pt" mean "12 point", "12 parts" or "12 pints"? Even without conflicts in the definition of a particular unit, there's no need to convert point sizes for fonts into miles or light-years. Typesetters, surveyors and astronomers user different scales as well as systems. People do not think like computers ---------------------------------- Not everyone uses the metric system. And even less people say things like "5.25 feet". Often it's "5 feet, 3 inches" or "5 1/4 feet". Despite having ten fingers and toes, people don't think in tens. They think in twos, threes, fours, twelves, and sixteens. And sometimes they use fractional measurements like quarter-inches, sixteenths-of-an-inch, or half-pints. The purpose of this module is to allow people to use the measurement systems they are familiar with, and that is appropriate to what they are doing. Rationale --------- The Units:: hierarchy is an attempt to keep measurement systems in distinct classes. Thus one can have modules for converting between typography units (points, picas) distinct from common units of length (or area, temperature, etc.), specialized units (for Astronomy, Chemistry, Physics, Textiles, Winery, Navigation, etc.) or even traditional or regional systems (Japanese, Chinese, Egyptian, archaic systems, etc.) and to keep conflicting measurement systems distinct. Release Notes ------------- The current distribution contains the following packages: Convert::Units:: ::Base - a base module that does all of the work ::Length - a module for converting units of length ::Temperature - a module for converting units of temperature ::Type - a module for converting units of type Units::Base by itself does nothing. Another module needs to use it to create definitions of what units of measurement it handles and how they are related to each other (ie, 1 m = 100 cm). The base unit also allows for synonym and abbreviations to be defined. It also allows common "multiples" to be defined, so that it can handle things like "18 half-points" or "6 dozen feet" or even convert millimters to "sixteenths of an inch". (It does not yet handle Greek prefixes like centi- or mega- ... those will have to be manually defined.) Known Issues ------------ The current release should be considered "beta" until further testing and refinements have been made. Then again, maybe "alpha" is more accurate. The current version does not yet handle fractions such as "1/2 in". It should handle decimals such as "0.5 in". Relationships have been rewritten to be handle A(x+b) as well Ax. They may be redone in the future to handle more complex relationships, if the need arises. Unit names much be defined as all lowercase, since strings are munged with *lc()* before processing. In other words, if you define a unit name as "F" or "Fahrenheight" you won't be able to use it. Future Enhancements ------------------- Aside from bug fixes, optimizations, and making the string parsing conform more to the "manifesto" above, obvious additions would be modules for converting between units of area, volume, weight... (although if *Math::Units* does what you need, use that instead.) An example hierarchy for future modules: Convert::Units:: ::Length - general measures of length ::Area ::Pressure ::Volume Convert::Units::Length ::Chinese - specialized regional/traditional systems ::English Convert::Units::Astronomy ::Length - or Distance...? Modules should share a common unit (preferably metric) to allow for conversions. REQUIRED MODULES ================ Carp SEE ALSO ======== *Units::Length*, *Units::Temperature* and *Units::Type* modules, which demonstrate how *Units::Base* is used. AUTHOR ====== Robert Rothenberg LICENSE ======= Copyright (c) 1999-2000 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Coy, Next: Crypt/Beowulf, Prev: Convert/Units/Base, Up: Module List Coy (like Carp only prettier) ***************************** NAME ==== Coy (like Carp only prettier) SYNOPSIS ======== # In your application: # ==================== use Coy; warn "There seems to be a problem"; die "Looks like it might be fatal"; # You can add vocab in the $HOME/.coyrc file: # =========================================== noun { wookie => { category => [ Sentient ], sound => [ "roars", "grunts", "bellows" ], act => { sits => { location => Arborial }, fights => { minimum => 2, association => "argument", }, }, }, }; category { Sentient => { act => { quarrels => { associations => "argument", location => Terrestrial, minimum => 2, synonyms => [qw(bickers argues)], }, laughs => { associations => "happy", location => Terrestrial, non_adjectival => 1, }, }, } }; personage "R2D2"; personage "Darth Vader"; place "Mos Eisley"; place "the Death Star"; tree "Alderaan mangrove"; fruit_tree "Wookie-oak"; # You can also select a different syllable counter via .coyrc # =========================================================== use Lingua::EN::Syllables::syllable; syllable_counter "Lingua::EN::Syllables::syllable"; # or use Lingua::EN::Syllables::syllable; syllable_counter \&Lingua::EN::Syllables::syllable; # or syllable_counter sub { return 1 }; # FAST BUT INACCURATE DESCRIPTION =========== Error messages strewn across my terminal. A vein starts to throb. Their reproof adds the injury of insult to the shame of failure. When a program dies what you need is a moment of serenity. The Coy.pm module brings tranquillity to your debugging. The module alters the behaviour of C and C (and C and C). It also provides C and C -- two Zen alternatives. Like Carp.pm, Coy reports errors from the caller's point-of-view. But it prefaces the bad news of failure with a soothing haiku. The haiku are not "canned", but are generated freshly every time. Once the haiku is complete, it's prepended to the error message. Execution of the original call to C or C resumes. Haiku and error message strew across my screen. A smile starts to form. EXTENDING THE VOCABULARY ======================== Any code placed in "$ENV{HOME}/.coyrc" runs at compile-time. You can use that file to extend Coy.pm's vocabulary. The "SYNOPSIS" at the start of this POD shows how you might set it up. (Eventually this section will detail the full mechanism.) CHANGING THE SYLLABLE COUNTER ============================= If you don't like the syllable counter you can always replace it. Coy provides a sub called C for that very purpose. It is passed a sub reference. That sub is then used to count syllables. You can also pass the sub's I (that is, pass a symbolic reference). The new counter sub should take a string and return its syllable count. C can be called from your code, or from .coyrc. BUGS AND LIMITATIONS ==================== In its current form, the module has four problems and limitations: * Vocabulary: The list of nouns and verbs is too small at present. This limits the range of topics that the haiku produced can cover. That in turn leads to tell-tale repetition (which fails the Turing test). Extending the range of words Coy.pm can use is no problem (though finding the time and the creativity required may be :-). Users of Coy are encouraged to add their own vocabulary. (See the "SYNOPSIS", and also "EXTENDING THE VOCABULARY"). * Associations: The vocabulary has too few topic links. Hence it's often not able to find relevant words for a message. This leads to haiku utterly unrelated to the error text. Again, there is no technical difficulty in adding more links: Defining enough associations isn't hard, just tedious. User-specified vocabularies can solve this problem as well. * Limited grammar: The number of syntactic templates is too small. This leads to haiku that are (structurally, at least) monotonous. Yet again, this needs no technical solution, just time and effort. Of course, such enhanced templates might require richer vocabulary. For example, verb predicates would need extra database structure: Each verb entry would have to be extended with links to object nouns. * Syllable counting: This is perhaps the major problem at present. The algorithmic syllable counter is still being developed. It is currently around 96% accurate (per word). This means that correct syllable counts for haiku can't be guaranteed. Syllable counts for single words are correct to plus-or-minus 1. In a multi-word haiku these errors cancel out in most cases. Thus, the haiku tend to be correct within one or two syllables. As the syllable counter slowly improves, this problem will abate. Alteratively, you can choose to use your own syllable counter. (See above in the section titled "CHANGING THE SYLLABLE COUNTER".) AUTHOR ====== The Coy.pm module was developed by Damian Conway. COPYRIGHT ========= Copyright (c) 1998, Damian Conway. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)  File: pm.info, Node: Crypt/Beowulf, Next: Crypt/Blowfish, Prev: Coy, Up: Module List Beowulf encryption ****************** NAME ==== Crypt::Beowulf - Beowulf encryption SYNOPSIS ======== use Crypt::Beowulf; my $cipher = BeoEncrypt( $text, $passphrase ); my $plain = BeoDecrypt( $text, $passphrase ); # Or you can do the encryption and decryption with # the same method, as follows: my $encrypted = BeoCrypt( $text, $passphrase, "e"); my $decrypted = BeoCrypt( $text, $passphrase, "d"); NOTICE ====== Although I have used this module, personally, a great deal, it has not undergone extensive public testing. As such, it should still be considered to be beta software. If anyone encounters a problem, bug, or loophole, please email me at ceo@neurogames.com. And I'm open to any suggestions that anyone may have to improved either the module or the algorithm itself. DESCRIPTION =========== I originally designed this system in response to a need for an encryption scheme for Neurogames that encrypted text using a fairly standard character set, as opposed to the various and sundry control-characters and meta-characters that end up being part of the ciphertext when using extent encryption modules, such as Crypt::TripleDES and Crypt::GOST. Personally, I ran into several cross-platform problems with the control characters being mis-interpreted by one OS or another, or by text-editing software. In theory at least, the fairly standard ASCII set used by Crypt::Beowulf should remedy that matter. Another advantage is that it is substantially faster than encrypting with TripleDES or GOST. Based on benchmarks encrypting the same text, Crypt::Beowulf is between 3 and 10 times faster than either Crypt::GOST or Crypt::TripleDES. The code is based on 95-element permutation (95!, or approx. 1.033 * 10^148 possible combinations). It should hold up fairly well against brute-force deciphering, though in theory, there could be some sort of shortcut to cracking the code, of which I'm unaware. Please note that in the event that a passphrase is less than 10 characters long, "x" will be padded to the end to reach a minimum of 10 characters. In theory, there is no upper limit to the length of the passphrase. In addition, for the particularly security-conscious, this encryption method supports multiple encryption, so after encrypting your text, you can encrypt the cipher text as many times as you wish (personally, I've never tested this over more than approx. 10 passes), and decryption of a like number of times will be necessary to get the plain text. If one were so inclined, the passphrase could be changed for each pass. If you do this, remember to decrypt using the multiple passphrases in reverse order. METHODS ======= *BeoEncrypt*( $plaintext, $passphrase ); Encrypts $plaintext using $passphrase to initialize the randomization. *BeoDecrypt*( $cyphertext, $passphrase ); Same as BeoEncrypt, only in the other direction. *BeoCrypt*( $text, $passphrase, $mode ); Encryption and decryption included in one nice, neat little package. If we are encrypting, pass a value of "e" for $mode, if we're decrypting, pass a value of "d". LIMITATIONS =========== Due to the nature of the of the ordered code stream, this system is really only designed to be used on text files, or to a lesser degree, word processing documents. The program doesn't like control-characters or meta-characters, and subsequently ignores them. For example, graphic files encrypted with Beowulf will not decrypt correctly. AUTHOR ====== Kurt Kincaid, ceo@neurogames.com  File: pm.info, Node: Crypt/Blowfish, Next: Crypt/Blowfish_PP, Prev: Crypt/Beowulf, Up: Module List Perl Blowfish encryption module ******************************* NAME ==== Crypt::Blowfish - Perl Blowfish encryption module SYNOPSIS ======== use Crypt::Blowfish; Blowfish is capable of strong encryption and can use key sizes up to 56 bytes (a 448 bit key). You're encouraged to take advantage of the full key size to ensure the strongest encryption possible from this module. DESCRIPTION =========== The module implements the Crypt::CBC interface. You're encouraged to read the perldoc for Crypt::CBC if you intend to use this module for Cipher Block Chaining. Crypt::CBC has the following methods: blocksize =item keysize =item encrypt =item decrypt FUNCTIONS ========= blocksize Returns the size (in bytes) of the block cipher. keysize Returns the size (in bytes) of the key. new my $cipher = new Crypt::Blowfish $key; This creates a new Crypt::Blowfish BlockCipher object, using $key, where $key is a key of `keysize()' bytes. encrypt my $cipher = new Crypt::Blowfish $key; my $ciphertext = $cipher->encrypt($plaintext); This function encrypts $plaintext and returns the $ciphertext where $plaintext and $ciphertext should be of `blocksize()' bytes. decrypt my $cipher = new Crypt::Blowfish $key; my $plaintext = $cipher->decrypt($ciphertext); This function decrypts $ciphertext and returns the $plaintext where $plaintext and $ciphertext should be of `blocksize()' bytes. EXAMPLE ======= my $key = pack("H16", "0123456789ABCDEF"); my $cipher = new Crypt::Blowfish $key; my $ciphertext = $cipher->encrypt("plaintex"); # NB - 8 bytes print unpack("H16", $ciphertext), "\n"; PLATFORMS ========= Crypt::Blowfish has been tested *successfully* against the following: Linux 2.2.X (RH6.X, Mandrake 6.5) Solaris 2.7 SPARC FreeBSD 3.4 FreeBSD 3.3 HP-UX B.10.20 (using HP's cc) Crypt::Blowfish has been tested and *failed* against the following: FreeBSD 3.2 Win32 NOTES ===== To use the CBC mode, you must use Crypt::CBC version 1.22 or higher. SEE ALSO ======== Crypt::CBC, Crypt::DES, Crypt::IDEA Bruce Schneier, *Applied Cryptography*, 1995, Second Edition, published by John Wiley & Sons, Inc. COPYRIGHT ========= The implementation of the Blowfish algorithm was developed by, and is copyright of, A.M. Kuchling. Other parts of the perl extension and module are copyright of Systemics Ltd ( http://www.systemics.com/ ). Code revisions, updates, and standalone release is the copyright of W3Works, LLC. AUTHOR ====== Original algorithm, Bruce Shneier. Original implimentation, A.M. Kuchling. Original Perl impilmentation, Systemics Ltd. Current revision and maintainer: Dave Paris THANKS ====== To my wonderful wife for her patience & love. To EFNet #perl, to infobot #perl, to the folks that helped test this module. A special thanks to my friends for guidance and support. Perl couldn't have had this module without ya'll.  File: pm.info, Node: Crypt/Blowfish_PP, Next: Crypt/CBC, Prev: Crypt/Blowfish, Up: Module List Blowfish encryption algorithm implemented purely in Perl ******************************************************** NAME ==== *Crypt::Blowfish_PP* - Blowfish encryption algorithm implemented purely in Perl SYNOPSIS ======== `use Crypt::Blowfish_PP'; $blowfish=new Crypt::Blowfish_PP($key); $ciphertextBlock=$blowfish->encrypt($plaintextBlock); $plaintextBlock=$blowfish->decrypt($ciphertextBlock); DESCRIPTION =========== The *Crypt::Blowfish_PP* module provides for users to use the Blowfish encryption algorithm in perl. The implementation is entirely Object Oriented, as there is quite a lot of context inherent in making blowfish as fast as it is. The key is anywhere between 64 and 448 bits (8 and 56 bytes), and should be passed as a packed string. The transformation itself is a 16-round Feistel Network, and operates on a 64 bit block. Object methods for the Crypt::Blowfish_PP module: new(key) -------- The new() method initialises a blowfish object with the key that is passed. This is the slow part of doing a blowfish encryption or decryption, as it initialises the 18 p-boxes and the 1024 s-boxes that are used for the algorithm. It will return undef if the key is not of a valid length. encrypt(block) -------------- The encrypt() method uses the initialised blowfish object to encrypt 8 bytes of data of the string passed to it. It returns the encrypted block. decrypt(block) -------------- The decrypt() method uses the initialised blowfish object to decrypt 8 bytes of data of the string passed to it. It returns the decrypted block. COMMENTS ======== This is probably crap software, but hey, its for general use. I'm happy to patch it with other people's code... :) If you want speed, then see the Crypt::Blowfish module. AUTHOR ====== Matthew Byng-Maddick <`mbm@colondot.net'> SEE ALSO ======== http://www.counterpane.com/,*Note Crypt/CBC: Crypt/CBC,  File: pm.info, Node: Crypt/CBC, Next: Crypt/CBCeasy, Prev: Crypt/Blowfish_PP, Up: Module List Encrypt Data with Cipher Block Chaining Mode ******************************************** NAME ==== Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode SYNOPSIS ======== use Crypt::CBC; $cipher = new Crypt::CBC('my secret key','IDEA'); $ciphertext = $cipher->encrypt("This data is hush hush"); $plaintext = $cipher->decrypt($ciphertext); $cipher->start('encrypting'); open(F,"./BIG_FILE"); while (read(F,$buffer,1024)) { print $cipher->crypt($buffer); } print $cipher->finish; DESCRIPTION =========== This module is a Perl-only implementation of the cryptographic cipher block chaining mode (CBC). In combination with a block cipher such as DES or IDEA, you can encrypt and decrypt messages of arbitrarily long length. The encrypted messages are compatible with the encryption format used by *SSLeay*. To use this module, you will first create a new Crypt::CBC cipher object with new(). At the time of cipher creation, you specify an encryption key to use and, optionally, a block encryption algorithm. You will then call the start() method to initialize the encryption or decryption process, crypt() to encrypt or decrypt one or more blocks of data, and lastly finish(), to flush the encryption stream. For your convenience, you can call the encrypt() and decrypt() methods to operate on a whole data value at once. new() ----- $cipher = new Crypt::CBC($key,$algorithm); The new() method creates a new Crypt::CBC object. You must provide an encryption/decryption key, which can be any series of characters of any length. Internally, the actual key used is derived from the MD5 hash of the key you provide. The optional second argument is the block encryption algorithm to use, specified as a package name. You may use any block encryption algorithm that you have installed. At the time this was written, only two were available on CPAN, Crypt::DES and Crypt::IDEA. You may refer to them using their full names ("Crypt::IDEA") or in abbreviated form ("IDEA".) If no algorithm is provided, DES is assumed. start() ------- $cipher->start('encrypting'); $cipher->start('decrypting'); The start() method prepares the cipher for a series of encryption or decryption steps, resetting the internal state of the cipher if necessary. You must provide a string indicating whether you wish to encrypt or decrypt. "E" or any word that begins with an "e" indicates encryption. "D" or any word that begins with a "d" indicates decryption. crypt() $ciphertext = $cipher->crypt($plaintext); ------------------------------------------------------ After calling start(), you should call crypt() as many times as necessary to encrypt the desired data. finish() -------- $ciphertext = $cipher->finish(); The CBC algorithm must buffer data blocks inernally until they are even multiples of the encryption algorithm's blocksize (typically 8 bytes). After the last call to crypt() you should call finish(). This flushes the internal buffer and returns any leftover ciphertext. In a typical application you will read the plaintext from a file or input stream and write the result to standard output in a loop that might look like this: $cipher = new Crypt::CBC('hey jude!'); $cipher->start('encrypting'); print $cipher->crypt($_) while <>; print $cipher->finish(); encrypt() --------- $ciphertext = $cipher->encrypt($plaintext) This convenience function runs the entire sequence of start(), crypt() and finish() for you, processing the provided plaintext and returning the corresponding ciphertext. decrypt() --------- $plaintext = $cipher->decrypt($ciphertext) This convenience function runs the entire sequence of start(), crypt() and finish() for you, processing the provided ciphertext and returning the corresponding plaintext. encrypt_hex(), decrypt_hex() ---------------------------- $ciphertext = $cipher->encrypt_hex($plaintext) $plaintext = $cipher->decrypt_hex($ciphertext) These are convenience functions that operate on ciphertext in a hexadecimal representation. *encrypt_hex($plaintext)* is exactly equivalent to *unpack('H*',encrypt($plaintext))*. These functions can be useful if, for example, you wish to place the encrypted information into an e-mail message, Web page or URL. EXAMPLES ======== Two examples, des.pl and idea.pl can be found in the eg/ subdirectory of the Crypt-CBC distribution. These implement command-line DES and IDEA encryption algorithms. LIMITATIONS =========== The encryption and decryption process is about a tenth the speed of the equivalent SSLeay programs (compiled C). This could be improved by implementing this module in C. It may also be worthwhile to optimize the DES and IDEA block algorithms further. BUGS ==== None that I know of. AUTHOR ====== Lincoln Stein, lstein@cshl.org SEE ALSO ======== perl(1), Crypt::DES(3), Crypt::IDEA(3)  File: pm.info, Node: Crypt/CBCeasy, Next: Crypt/CipherSaber, Prev: Crypt/CBC, Up: Module List Easy things make really easy with Crypt::CBC ******************************************** NAME ==== Crypt::CBCeasy - Easy things make really easy with Crypt::CBC SYNOPSIS ======== use Crypt::CBCeasy; # !!! YOU can not 'require' this module !!! IDEA::encipher($my_key, "plain-file", "crypted-file"); $plain_text = DES::decipher($my_key, \*CRYPTO_FILE); $crypted = Blowfish::encipher($my_key, \*PLAIN_SOCKET); ABSTRACT ======== This module is just a helper for Crypt::CBC to make simple and usual jobs just one-liners. The current version of the module is available at CPAN. DESCRIPTION =========== After you call this module as use Crypt::CBCeasy IMPORT-LIST; it creates the `encipher()' and `decipher()' functions in all namespaces (packages) listed in the `IMPORT-LIST'. Without the `IMPORT-LIST' it creates these 2 functions in the *DES::*, *IDEA::* and *Blowfish::* namespaces by default to stay compatible with the previous versions that were capable to handle only these 3 ciphers. You have to install `Crypt::CBC' v. 1.22 or later to work with `Blowfish'. Sure IDEA:: functions will work only if you have Crypt::IDEA installed, DES:: - if you have Crypt::DES, Blowfish:: - if you have Crypt::Blowfish and Crypt::CBC is version 1.22 or above etc. Here's the list of the ciphers that could be called via the `Crypt::CBCeasy' interface today (in fact the same modules that are `Crypt::CBC' compatible): Cipher CPAN module DES Crypt::DES IDEA Crypt::IDEA Blowfish Crypt::Blowfish Twofish2 Crypt::Twofish2 DES_PP Crypt::DES_PP Blowfish_PP Crypt::Blowfish_PP Note that cipher names are case sensitive in the `IMPORT-LIST', so "blowfish" will give an error. Type them exactly as they are written in the correspondent underlying modules. Both `encipher()' and `decipher()' functions take 3 parameters: 1 - en/decryption key 2 - source 3 - destination The sources could be: an existing file, a scalar (just a string that would be encrypted), an opened filehandle, any other object that inherits from the filehandle, for example IO::File or FileHandle object, and socket. Destinations could be any of the above except scalar, because we can not distinguish between scalar and output file name here. Well, it's easier to look at the examples: ($fh vars here are IO::Handle, IO::File or FileHandle objects, variables of type "GLOB", "GLOB" refs or sockets) *IDEA::encipher(* $my_key, "in-file", "out-file" *);* *IDEA::encipher(* $my_key, *IN, "out-file" *);* *IDEA::encipher(* $my_key, \*IN, "out-file" *);* *IDEA::encipher(* $my_key, $fh_in, "out-file" *);* *IDEA::encipher(* $my_key, "in-file", *OUT *);* *IDEA::encipher(* $my_key, "in-file", \*OUT *);* *IDEA::encipher(* $my_key, "in-file", $fh_out *);* *IDEA::encipher(* $my_key, *IN, *OUT *);* *IDEA::encipher(* $my_key, \*IN, \*OUT *);* *IDEA::encipher(* $my_key, $fh_in, $fh_out *);* *IDEA::encipher(* $my_key, $plain_text, "out-file" *);* *IDEA::encipher(* $my_key, $plain_text, *OUT *);* *IDEA::encipher(* $my_key, $plain_text, \*OUT *);* *IDEA::encipher(* $my_key, $plain_text, $fh_out *);* any of the above will work and do what was expected. In addition there is a 2-argument version that returns it's result as scalar: $crypted_text = *IDEA::encipher(* $my_key, $plain_text *);* $crypted_text = *IDEA::encipher(* $my_key, "in-file" *);* $crypted_text = *IDEA::encipher(* $my_key, *IN *);* $crypted_text = *IDEA::encipher(* $my_key, \*IN *);* $crypted_text = *IDEA::encipher(* $my_key, $fh *);* All the same is possible for any of the ciphers in the `IMPORT-LIST'. All functions croak on errors (such as "input file not found"), so if you want to trap errors use them inside the `eval{}' block and check the `$@'. Note that all filehandles are used in binmode whether you claimed them binmode or not. On Win32 for example this will result in CRLF's in $plain_text after $plain_text = DES::decipher($my_key, "crypted_file"); if "crypted_file" was created by DES::encipher($my_key, "text_file", "crypted_file"); If the filehandle was used before - it's your job to rewind it to the beginning and/or close. INSTALLATION ============ As this is just a plain module no special installation is needed. Put it into the /Crypt subdirectory somewhere in your @INC. The standard Makefile.PL make make test make install procedure is provided. In addition make html will produce the HTML-docs. This module requires Crypt::CBC at least 1.20 by Lincoln Stein, lstein@cshl.org one or more of Crypt::IDEA, Crypt::DES, Crypt::Blowfish, Crypt::Blowfish_PP, Crypt::Twofish2, Crypt::DES_PP or other Crypt::CBC compatible modules. CAVEATS ======= This module has been created and tested in a Win95/98/2000Pro environment with Perl 5.004_02 and ActiveState ActivePerl build 618. I expect it to function correctly on other systems too. CHANGES ======= 0.21 Mon Mar 6 07:28:41 2000 - first public release 0.22 Sun Feb 18 13:11:59 2001 A horrible BUG was found by Michael Drumheller In fact 0.21 was ALWAYS using DES despite of the desired cipher. DAMN! Fixed. And the test is modified so that this will never happen again. Now you can define the list of ciphers that are compatible with Crypt::CBC in the import list. You can not call this module with the "require" statement. This is incompatible with the older versions. TODO ==== Any suggestions are much appreciated. BUGS ==== Please report. VERSION ======= This man page documents "Crypt::CBCeasy" version 0.22 February 18, 2001 AUTHOR ====== Mike Blazer, blazer@mail.nevalink.ru http://base.dux.ru/guest/fno/perl/ SEE ALSO ======== Crypt::CBC COPYRIGHT ========= Copyright (C) 2000-2001 Mike Blazer. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Crypt/CipherSaber, Next: Crypt/DES, Prev: Crypt/CBCeasy, Up: Module List Perl module implementing CipherSaber encryption. ************************************************ NAME ==== Crypt::CipherSaber - Perl module implementing CipherSaber encryption. SYNOPSIS ======== use Crypt::CipherSaber; my $cs = Crypt::CipherSaber->new('my pathetic secret key'); my $coded = $cs->encrypt('Here is a secret message for you'); my $decoded = $cs->decrypt($coded); DESCRIPTION =========== The Crypt::CipherSaber module implements CipherSaber encryption, described at http://ciphersaber.gurus.com. It is simple, fairly speedy, and relatively secure algorithm based on RC4. Encryption and decryption are done based on a secret key, which must be shared with all intended recipients of a message. METHODS ======= *new($key, $N)* Initialize a new Crypt::CipherSaber object. $key, the key used to encrypt or to decrypt messages is required. $N is optional. If provided and greater than one, it will implement CipherSaber-2 encryption (slightly slower but more secure). If not specified, or equal to 1, the module defaults to CipherSaber-1 encryption. $N must be a positive integer greater than one. encrypt($message) Encrypt a message. This uses the key stored in the current Crypt::CipherSaber object. It will generate a 10-byte random IV (Initialization Vector) automatically, as defined in the RC4 specification. This returns a string containing the encrypted message. Note that the encrypted message may contain unprintable characters, as it uses the extended ASCII character set (valid numbers 0 through 255). decrypt($message) Decrypt a message. For the curious, the first ten bytes of an encrypted message are the IV, so this must strip it off first. This returns a string containing the decrypted message. The decrypted message may also contain unprintable characters, as the CipherSaber encryption scheme can handle binary files with fair ease. If this is important to you, be sure to treat the results correctly. *crypt($iv, $message)* If you wish to generate the IV with a more cryptographically secure random string (at least compared to Perl's builtin rand() function), you may do so separately, passing it to this method directly. The IV must be a ten-byte string consisting of characters from the extended ASCII set. This is generally only useful for encryption, although you may extract the first ten characters of an encrypted message and pass them in yourself. You might as well call decrypt(), though. The more random the IV, the stronger the encryption tends to be. On some operating systems, you can read from /dev/random. Other approaches are the Math::TrulyRandom module, or compressing a file, removing the headers, and compressing it again. AUTHOR ====== chromatic thanks to jlp for testing, moral support, and never fearing the icky details and to the fine folks at http://perlmonks.org SEE ALSO ======== the CipherSaber home page at http://ciphersaber.gurus.com perl(1), rand().  File: pm.info, Node: Crypt/DES, Next: Crypt/DES_PP, Prev: Crypt/CipherSaber, Up: Module List Perl interface to DES block cipher ********************************** NAME ==== DES - Perl interface to DES block cipher SYNOPSIS ======== use Crypt::DES; DESCRIPTION =========== This perl extension is an implementation of the DES block cipher algorithm. The module implements the Crypt::BlockCipher interface, which has the following methods blocksize =item keysize =item encrypt =item decrypt FUNCTIONS ========= blocksize Returns the size (in bytes) of the block cipher. keysize Returns the size (in bytes) of the key. new my $cipher = new DES $key; This creates a new DES BlockCipher object, using $key, where $key is a key of `keysize()' bytes. encrypt my $cipher = new DES $key; my $ciphertext = $cipher->encrypt($plaintext); This function encrypts $plaintext and returns the $ciphertext where $plaintext and $ciphertext should be of `blocksize()' bytes. decrypt my $cipher = new DES $key; my $plaintext = $cipher->decrypt($ciphertext); This function decrypts $ciphertext and returns the $plaintext where $plaintext and $ciphertext should be of `blocksize()' bytes. EXAMPLE ======= my $key = pack("H16", "0123456789ABCDEF"); my $cipher = new DES $key; my $ciphertext = $cipher->encrypt("plaintex"); # NB - 8 bytes print unpack("H16", $ciphertext), "\n"; SEE ALSO ======== Crypt::IDEA Bruce Schneier, *Applied Cryptography*, 1995, Second Edition, published by John Wiley & Sons, Inc. COPYRIGHT ========= The implementation of the DES algorithm was developed by, and is copyright of, Eric Young (eay@mincom.oz.au). Other parts of this perl extension are copyright of Systemics Ltd ( http://www.systemics.com/ ).  File: pm.info, Node: Crypt/DES_PP, Next: Crypt/ECB, Prev: Crypt/DES, Up: Module List Perl extension for DES encryption ********************************* NAME ==== Crypt::DES_PP - Perl extension for DES encryption SYNOPSIS ======== use Crypt::DES_PP; $des = Crypt::DES_PP->new ($key); $cipher = $des->encrypt ($plain); $plain = $des->decrypt ($cipher); $blocksize = $des->blocksize; $keysize = $des->keysize; DESCRIPTION =========== The Data Encryption Standard (DES), also known as Data Encryption Algorithm (DEA) is a semi-strong encryption and decryption algorithm. The module is 100 % compatible to Crypt::DES but is implemented entirely in Perl. That means that you do not need a C compiler to build and install this extension. The module implements the Crypt::CBC interface. You are encouraged to read the documentation for Crypt::CBC if you intend to use this module for Cipher Block Chaining. The minimum (and maximum) key size is 8 bytes. Shorter keys will cause an exception, longer keys will get silently truncated. Data is encrypted and decrypted in blocks of 8 bytes. The module implements the Ultra-Fast-Crypt (UFC) algorithm as found for example in the GNU libc. On the Perl side a lot has been done in order to make the module as fast as possible (function inlining, use integer, ...). Note: For performance issues the source code for the module is first preprocessed by m4. That means that you need an m4 macro processor in order to hack on the sources. This is of no concern for you if you only want to use the module, the preprocessed output is always included in the distribution. BUGS ==== Nothing known. The module has not been tested on 64 bit architectures. AUTHOR ====== This implementation was written by Guido Flohr (guido@imperia.net). It is available under the terms of the Lesser GNU General Public License (LGPL) version 2 or - at your choice - any later version, see the file "COPYING.LIB". The original C implementation of the Ultra-Fast-Crypt algorithm was written by Michael Glad (glad@daimi.aau.dk) and has been donated to the Free Software Foundation, Inc. It is covered by the GNU library license version 2, see the file "COPYING.LIB". SEE ALSO ======== Crypt::CBC(3), Crypt::DES(3), perl(1), m4(1).