This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Crypt/RSA, Next: Crypt/RSA/DataFormat, Prev: Crypt/RIPEMD160/MAC, Up: Module List RSA public-key cryptosystem. **************************** NAME ==== Crypt::RSA - RSA public-key cryptosystem. VERSION ======= $Revision: 1.23 $ (Beta) $Date: 2001/03/07 15:39:55 $ DESCRIPTION =========== Crypt::RSA is a pure-perl, cleanroom implementation of the RSA public-key cryptosystem, written atop the blazingly fast number theory library PARI. As far as possible, Crypt::RSA conforms with *PKCS #1, RSA Cryptography Specifications v2.1*[13]. This implementation is structured as a bundle of modules that provide key pair generation and management, plaintext-aware encryption and digital signatures with appendix. Crypt::RSA is a DWIM wrapper around the other modules in the bundle. WARNINGS ======== This is beta, and largely untested, software. Please use at your own risk! Due to lack of a suitable ASN.1 encoder in perl, ASN.1 encoded formats are not supported yet. MODULES ======= As of this writing, Crypt::RSA is just a placeholder for the wrapper code, which will appear soon. In the meantime, please use the following modules directly: Crypt::RSA::Key RSA key pair generator. Crypt::RSA::Key::Public RSA Public Key Management. Crypt::RSA::Key::Private RSA Private Key Management. Crypt::RSA::EME::OAEP Plaintext-aware encryption with RSA. Crypt::RSA::SSA::PSS Probablistic Signature Scheme based on RSA. ERROR HANDLING ============== All modules in the Crypt::RSA bundle use a common error handling method. When a method fails it returns a non-true value and sets $self->errstr to a string that explains the reason for the error. Private keys and plaintext representations passed to the method in question are wiped from memory. AUTHOR ====== Vipul Ved Prakash, ACKNOWLEDGEMENTS ================ Thanks to Ilya Zakharevich for answering even the goofiest of my questions regarding Math::Pari with unwavering paitence. Shizukesa on #perl for clueing me into the error handling method used in this module and a-mused for good advice. LICENSE ======= Copyright (c) 1998-2001, Vipul Ved Prakash. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== Crypt::RSA::Primitives(3), Crypt::RSA::DataFormat(3), Crypt::RSA::Errorhandler(3), Crypt::RSA::Debug(3), Crypt::Primes(3), Crypt::Random(3), Crypt::CBC(3), Crypt::Blowfish(3), Tie::EncryptedHash(3), Math::Pari(3). MAILING LIST ============ pac@lists.vipul.net is a mailing list for discussing development of asymmetric cryptography modules in perl. Please send Crypt::RSA related communications directly to the list address. Subscription interface for pac is at http://lists.vipul.net/mailman/listinfo/pac/ BIBLIOGRAPHY ============ (Chronologically sorted.) 1. *R. Rivest, A. Shamir, L. Aldeman.* A Method for Obtaining Digital Signatures and Public-Key Cryptosystems (1978). 2. *U. Maurer.* Fast Generation of Prime Numbers and Secure Public-Key Cryptographic Parameters (1994). 3. *M. Bellare, P. Rogaway.* Optimal Asymmetric Encryption - How to Encrypt with RSA (1995). 4. *M. Bellare, P. Rogaway.* The Exact Security of Digital Signatures - How to sign with RSA and Rabin (1996). 5. *B. Schneier.* Applied Cryptography, Second Edition (1996). 6. *A. Menezes, P. Oorschot, S. Vanstone.* Handbook of Applied Cryptography (1997). 7. *D. Boneh.* Twenty Years of Attacks on the RSA Cryptosystem (1998). 8. *D. Bleichenbacher, M. Joye, J. Quisquater.* A New and Optimal Chosen-message Attack on RSA-type Cryptosystems (1998). 9. *B. Kaliski, J. Staddon.* Recent Results on PKCS #1: RSA Encryption Standard, RSA Labs Bulletin Number 7 (1998). 10. *B. Kaliski, J. Staddon.* PKCS #1: RSA Cryptography Specifications v2.0, RFC 2437 (1998). 11. *SSH Communications Security.* SSH 1.2.7 source code (1998). 12. *S. Simpson.* PGP DH vs. RSA FAQ v1.5 (1999). 13. *RSA Laboratories* Draft I, PKCS #1 v2.1: RSA Cryptography Standard (1999). 14. *E. Young, T. Hudson, OpenSSL Team.* OpenSSL 0.9.5a source code (2000).  File: pm.info, Node: Crypt/RSA/DataFormat, Next: Crypt/RSA/Debug, Prev: Crypt/RSA, Up: Module List Data creation, conversion and reporting primitives. *************************************************** NAME ==== Crypt::RSA::DataFormat - Data creation, conversion and reporting primitives. DESCRIPTION =========== This module implements several data creation, conversion and reporting primitives used throughout the Crypt::RSA implementation. Primitives are available as exportable functions. FUNCTIONS ========= i2osp Integer, Length Integer To Octet String Primitive. Converts an integer into its equivalent octet string representative of length Length. If necessary, the resulting string is prefixed with nulls. os2ip String Octet String to Integer Primitive. Converts an octet string into its equivalent integer representative. generate_random_octet Length, Strength Generates a random octet string of length Length. Strength specifies the degree of randomness. See Crypt::Random(3) for an explanation of the Strength parameter. bitsize Integer Returns the length of the Integer in bits. octet_xor String1, String2 Returns the result of *String1* XOR *String2*. AUTHOR ====== Vipul Ved Prakash,  File: pm.info, Node: Crypt/RSA/Debug, Next: Crypt/RSA/EME/OAEP, Prev: Crypt/RSA/DataFormat, Up: Module List Debug routine for Crypt::RSA. ***************************** NAME ==== Crypt::RSA::Debug - Debug routine for Crypt::RSA. SYNOPSIS ======== use Crypt::RSA::Debug qw(debug); debug ("oops!"); DESCRIPTION =========== The module provides support for the print method of debugging! FUNCTION ======== debug String Prints String on STDOUT, along with caller's function name and line number. AUTHOR ====== Vipul Ved Prakash,  File: pm.info, Node: Crypt/RSA/EME/OAEP, Next: Crypt/RSA/Errorhandler, Prev: Crypt/RSA/Debug, Up: Module List Plaintext-aware encryption with RSA. ************************************ NAME ==== Crypt::RSA::EME::OAEP - Plaintext-aware encryption with RSA. SYNOPSIS ======== my $oaep = new Crypt::RSA::EME::OAEP; my $ct = $oaep->encrypt (Key => $key, Message => $message) || die $oaep->errstr; my $pt = $oaep->decrypt (Key => $key, Cyphertext => $ct) || die $oaep->errstr; DESCRIPTION =========== This module implements "plaintext-aware encryption" with RSA. Plaintext-aware means it's computationally infeasible to obtain full or partial information about a message from a cyphertext, and computationally infeasible to generate a valid cyphertext without knowing the corresponding message. It's impossible to mount chosen cyphertext attacks against this scheme. For more information on plaintext-aware encryption, see [3], [9] & [13]. METHODS ======= new() ----- Constructor. encrypt() --------- Encrypts a string with a public key and returns the encrypted string on success. encrypt() takes a hash argument with the following mandatory keys: Message A string to be encrypted. The length of this string should not exceed k-42 octets, where k is the octet length of the RSA modulus. If Message is longer than k-42, the method will fail and set $self->errstr to "Message too long." Key Public key of the recepient, a Crypt::RSA::Key::Public object. decrypt() --------- Decrypts cyphertext with a private key and returns plaintext on success. $self->errstr is set to "Decryption Error." or appropriate error on failure. decrypt() takes a hash argument with the following mandatory keys: Cyphertext A string encrypted with encrypt(). The length of the cyphertext must be k octets, where k is the length of the RSA modulus. Key Private key of the reciever, a Crypt::RSA::Key::Private object. ERROR HANDLING ============== See ERROR HANDLING in Crypt::RSA(3) manpage. BIBLIOGRAPHY ============ See BIBLIOGRAPHY in Crypt::RSA(3) manpage. AUTHOR ====== Vipul Ved Prakash, SEE ALSO ======== Crypt::RSA(3), Crypt::RSA::Primitives(3), Crypt::RSA::Keys(3), Crypt::RSA::SSA::PSS(3)  File: pm.info, Node: Crypt/RSA/Errorhandler, Next: Crypt/RSA/Key, Prev: Crypt/RSA/EME/OAEP, Up: Module List Parent class for Crypt::RSA::*, provides error handling capabilities. ********************************************************************* NAME ==== Crypt::RSA::Errorhandler - Parent class for Crypt::RSA::*, provides error handling capabilities. AUTHOR ====== Vipul Ved Prakash,  File: pm.info, Node: Crypt/RSA/Key, Next: Crypt/RSA/Key/Private, Prev: Crypt/RSA/Errorhandler, Up: Module List RSA Key Pair Generator. *********************** NAME ==== Crypt::RSA::Key - RSA Key Pair Generator. SYNOPSIS ======== my $keychain = new Crypt::RSA::Key; my ($public, $private) = $keychain->generate ( Identity => 'Lord Macbeth ', Size => 2048, Password => 'A day so foul & fair', Verbosity => 1, ); die $keychain->errstr() unless $public && $private; DESCRIPTION =========== This module provides a method to generate an RSA key pair. METHODS ======= new() ----- Constructor. generate() ---------- Generates an RSA key of specified bitsize. generate() returns a list of two elements, a Crypt::RSA::Key::Public object that holds the public part of the key pair and a Crypt::RSA::Key::Private object that holds that private part. On failure, it sets $self->errstr to approriate error string. generate() takes a hash argument with the following keys: Size Bitsize of the key to be generated. This should be an even integer > 48. Bitsize is a mandatory argument. Password String with which the private key will be encrypted. Password is a mandatory argument. Identity A string that identifies the owner of the key. This string usually takes the form of a name and an email address. The identity is not bound to the key with a signature. However, a future release or another module will provide this facility. Identity is a mandatory argument. Cipher The block cipher which is used for encrypting the private key. Defaults to `Blowfish'. Cipher could be set to any value that works with Crypt::CBC(3) and Tie::EncryptedHash(3). Verbosity When set to 1, generate() will draw a progress display on console. Filename The generated key pair will be written to disk, in $Filename.public and $Filename.private files, if this argument is provided. Disk writes can be deffered by skipping this argument and achieved later with the write() method of Crypt::RSA::Key::Public(3) and Crypt::RSA::Key::Private(3). ERROR HANDLING ============== See ERROR HANDLING in Crypt::RSA(3) manpage. BUGS ==== There's an inefficiency in the way generate() ensures the key pair is exactly Size bits long. This will be fixed in a future release. AUTHOR ====== Vipul Ved Prakash, SEE ALSO ======== Crypt::RSA(3), Crypt::RSA::Key::Public(3), Crypt::RSA::Key::Private(3), Crypt::Primes(3), Tie::EncryptedHash(3)  File: pm.info, Node: Crypt/RSA/Key/Private, Next: Crypt/RSA/Key/Public, Prev: Crypt/RSA/Key, Up: Module List RSA Private Key Management. *************************** NAME ==== Crypt::RSA::Key::Private - RSA Private Key Management. SYNOPSIS ======== $key = new Crypt::RSA::Private::Key ( Identity => 'Lord Banquo ', Password => 'The earth hath bubbles', ); $key->hide (); $key->reveal ( Password => 'The earth hath bubbles' ); $key->write ( Filename => 'rsakeys/banquo.private' ); $akey = new Crypt::RSA::Private::Key ( Filename => 'rsakeys-banque.private' ); DESCRIPTION =========== [coming soon] AUTHOR ====== Vipul Ved Prakash, SEE ALSO ======== Crypt::RSA::Key(3), Crypt::RSA::Public(3)  File: pm.info, Node: Crypt/RSA/Key/Public, Next: Crypt/RSA/Primitives, Prev: Crypt/RSA/Key/Private, Up: Module List RSA Public Key Management. ************************** NAME ==== Crypt::RSA::Key::Public - RSA Public Key Management. SYNOPSIS ======== $key = new Crypt::RSA::Key::Public; $key->write ( Filename => 'rsakeys/banquo.public' ); $akey = new Crypt::RSA::Public ( Filename => 'rsakeys/banquo.public' ); DESCRIPTION =========== [coming soon] AUTHOR ====== Vipul Ved Prakash, SEE ALSO ======== Crypt::RSA::Key(3), Crypt::RSA::Private(3)  File: pm.info, Node: Crypt/RSA/Primitives, Next: Crypt/RSA/SSA/PSS, Prev: Crypt/RSA/Key/Public, Up: Module List RSA encryption, decryption, signature and verification primitives. ****************************************************************** NAME ==== Crypt::RSA::Primitives - RSA encryption, decryption, signature and verification primitives. SYNOPSIS ======== my $prim = new Crypt::RSA::Primitives; my $ctxt = $prim->core_encrypt (Key => $key, Plaintext => $string); my $ptxt = $prim->core_decrypt (Key => $key, Cyphertext => $ctxt); my $sign = $prim->core_sign (Key => $key, Message => $string); my $vrfy = $prim->core_verify (Key => $key, Signature => $sig); DESCRIPTION =========== This module implements RSA encryption, decryption, signature and verfication primitives. These primitives should only be used in the context of an encryption or signing scheme. See Crypt::RSA::EME::OAEP(3), and Crypt::RSA::SSA::PSS(3) for the implementation of two such schemes. ERROR HANDLING ============== See ERROR HANDLING in Crypt::RSA(3) manpage. AUTHOR ====== Vipul Ved Prakash, SEE ALSO ======== Crypt::RSA(3), Crypt::RSA::Key(3), Crypt::RSA::EME::OAEP(3), Crypt::RSA::SSA::PSS(3)  File: pm.info, Node: Crypt/RSA/SSA/PSS, Next: Crypt/RandPasswd, Prev: Crypt/RSA/Primitives, Up: Module List Probablistic Signature Scheme based on RSA. ******************************************* NAME ==== Crypt::RSA::SSA::PSS - Probablistic Signature Scheme based on RSA. SYNOPSIS ======== my $pss = new Crypt::RSA::SSA::PSS; my $signature = $pss->sign ( Message => $message, Key => $private, ) || die $pss->errstr; my $verify = $pss->verify ( Message => $message, Key => $key, Signature => $signature, ) || die $pss->errstr; DESCRIPTION =========== PSS (Probabilistic Signature Scheme) is a provably secure method of creating digital signatures with RSA. "Provable" means that the difficulty of forging signatures can be directly related to inverting the RSA function. "Probablistic" alludes to the randomly generated salt value included in the signature to enchance security. For more details on PSS, see [4] & [13]. METHODS ======= new() ----- Constructor. sign() ------ Computes a PSS signature on a message with the private key of the signer. In scalar context, sign() returns the computed signature. In array context, it returns the signature and the random salt. The signature can verified with verify() or verify_with_salt(). sign() takes a hash argument with the following mandatory keys: Message Message to be signed, a string of arbitary length. Key Private key of the signer, a Crypt::RSA::Key::Private object. verify() -------- Verfies a signature generated with sign(). The salt is recovered from the signature and need not be passed. Returns a true value on success and false on failure. $self->errstr is set to "Invalid signature." or appropriate error on failure. verify() takes a hash argument with the following mandatory keys: Key Public key of the signer, a Crypt::RSA::Key::Public object. Message The original signed message, a string of arbitary length. Signature Signature computed with sign(), a string. verify_with_salt() ------------------ Verifies a signature given the salt. Takes the same arguments as verify() in addition to *Salt*, which is a 20-byte string returned by sign() in array context. ERROR HANDLING ============== See ERROR HANDLING in Crypt::RSA(3) manpage. BIBLIOGRAPHY ============ See BIBLIOGRAPHY in Crypt::RSA(3) manpage. AUTHOR ====== Vipul Ved Prakash, SEE ALSO ======== Crypt::RSA(3), Crypt::RSA::Primitives(3), Crypt::RSA::Keys(3), Crypt::RSA::EME::OAEP(3)  File: pm.info, Node: Crypt/RandPasswd, Next: Crypt/Random, Prev: Crypt/RSA/SSA/PSS, Up: Module List random password generator based on FIPS-181 ******************************************* NAME ==== Crypt::RandPasswd - random password generator based on FIPS-181 SYNOPSIS ======== use Crypt::RandPasswd; ( $word, $hyphenated ) = Crypt::RandPasswd->word( $minlen, $maxlen ); $word = Crypt::RandPasswd->word( $minlen, $maxlen ); $word = Crypt::RandPasswd->letters( $minlen, $maxlen ); $word = Crypt::RandPasswd->chars( $minlen, $maxlen ); # override the defaults for these functions: *Crypt::RandPasswd::rng = \&my_random_number_generator; *Crypt::RandPasswd::restrict = \&my_restriction_filter; Run as Script ------------- perl Crypt/RandPasswd.pm -help SEE ALSO ======== FIPS 181 - (APG), Automated Password Generator: http://www.itl.nist.gov/fipspubs/fip181.htm DESCRIPTION =========== This code is a Perl language implementation of the Automated Password Generator standard, like the program described in "A Random Word Generator For Pronounceable Passwords" (not available on-line). This code is a re-engineering of the program contained in Appendix A of FIPS Publication 181, "Standard for Automated Password Generator". In accordance with the standard, the results obtained from this program are logically equivalent to those produced by the standard. CAVEATS ======= Bugs ---- The function to generate a password can sometimes take an extremely long time. Deviations From Standard ------------------------ This implementation deviates in one critical way from the standard upon which it is based: the random number generator in this implementation does not use DES. Instead, it uses perl's built-in `rand()' function, which in turn is (usually) built on the pseudo-random number generator functions of the underlying C library. However, the random function can be replaced by the user if desired. (See `' in this node.) Functions ========= word ---- word = word( minlen, maxlen ); ( word, hyphenated_form ) = word( minlen, maxlen ); Generates a random word, as well as its hyphenated form. The length of the returned word will be between minlen and maxlen. letters ------- word = letters( minlen, maxlen ); Generates a string of random letters. The length of the returned word is between minlen and maxlen. Calls `random_chars_in_range( 'a' =' 'z' )>. chars ----- word = chars( minlen, maxlen ); Generates a string of random printable characters. The length of the returned word is between minlen and maxlen. Calls `random_chars_in_range( '!' =' '~' )>. random_chars_in_range --------------------- word = random_chars_in_range( minlen, maxlen, lo_char => hi_char ); Generates a string of printable characters. The length of the returned string is between minlen and maxlen. Each character is selected from the range of ASCII characters delimited by (lo_char,hi_char). rand_int_in_range ----------------- n = rand_int_in_range( min, max ); Returns an integer between min and max, inclusive. Calls rng like so: n = min + int( rng( max - min + 1 ) ) random_element -------------- e = random_element( \@elts ) Selects a random element from an array, which is passed by ref. rng --- r = rng( n ); rng is designed to have the same interface as the built-in rand function. The default implementation here is a simple wrapper around rand, which is typically a wrapper for some pseudo-random number function in the underlying C library. The reason for having this simple wrapper is so the user can easily substitute a different random number generator if desired. Since many rng's have the same interface as rand, replacing `rng()' is as simple as { local $^W; # squelch sub redef warning. *Crypt::RandPasswd::rng = \&my_rng; } See `rand' in this node. restrict -------- word = restrict( word ); A filter. Returns the arg unchanged if it is allowable; returns undef if not. The default version of `restrict()' allows everything. You may install a different form to implement other restrictions, by doing something like this: { local $^W; # squelch sub redef warning. *Crypt::RandPasswd::restrict = \&my_filter; } init ---- This initializes the environment, which by default simply seeds the random number generator. _random_word ------------ This is the routine that returns a random word. It collects random syllables until a predetermined word length is found. If a retry threshold is reached, another word is tried. returns ( word, hyphenated_word ). _random_unit ------------ Selects a gram (aka "unit"). This is the standard random unit generating routine for get_syllable(). This routine attempts to return grams (units) with a distribution approaching that of the distribution of the units in English. The distribution of the units may be altered in this procedure without affecting the digram table or any other programs using the random_word subroutine, as long as the set of grams (units) is kept consistent throughout this library. *NOTE that where this func used to return a numeric index into the 'rules' C-array, it now returns a gram.* _improper_word -------------- Check that the word does not contain illegal combinations that may span syllables. Specifically, these are: 1. An illegal pair of units between syllables. 2. Three consecutive vowel units. 3. Three consecutive consonant units. The checks are made against units (1 or 2 letters), not against the individual letters, so three consecutive units can have the length of 6 at most. returns boolean _have_initial_y --------------- Treating y as a vowel is sometimes a problem. Some words get formed that look irregular. One special group is when y starts a word and is the only vowel in the first syllable. The word ycl is one example. We discard words like these. return boolean _have_final_split ----------------- Besides the problem with the letter y, there is one with a silent e at the end of words, like face or nice. We allow this silent e, but we do not allow it as the only vowel at the end of the word or syllables like ble will be generated. returns boolean get_syllable ------------ Generate next unit to password, making sure that it follows these rules: 1. Each syllable must contain exactly 1 or 2 consecutive vowels, where y is considered a vowel. 2. Syllable end is determined as follows: a. Vowel is generated and previous unit is a consonant and syllable already has a vowel. In this case, new syllable is started and already contains a vowel. b. A pair determined to be a "break" pair is encountered. In this case new syllable is started with second unit of this pair. c. End of password is encountered. d. "begin" pair is encountered legally. New syllable is started with this pair. e. "end" pair is legally encountered. New syllable has nothing yet. 3. Try generating another unit if: a. third consecutive vowel and not y. b. "break" pair generated but no vowel yet in current or previous 2 units are "not_end". c. "begin" pair generated but no vowel in syllable preceding begin pair, or both previous 2 pairs are designated "not_end". d. "end" pair generated but no vowel in current syllable or in "end" pair. e. "not_begin" pair generated but new syllable must begin (because previous syllable ended as defined in 2 above). f. vowel is generated and 2a is satisfied, but no syllable break is possible in previous 3 pairs. g. Second and third units of syllable must begin, and first unit is "alternate_vowel". alt_get_syllable ---------------- Takes an integer, the maximum number of chars to generate. (or is it minimum?) returns a list of ( string, units-in-syllable ) *This is an alternative version of `get_syllable()', which can be useful for unit testing the other functions.* _illegal_placement ------------------ goes through an individual syllable and checks for illegal combinations of letters that go beyond looking at digrams. We look at things like 3 consecutive vowels or consonants, or syllables with consonants between vowels (unless one of them is the final silent e). returns boolean. AUTHOR ====== JDPORTER@cpan.org (John Porter) COPYRIGHT ========= This perl module is free software; it may be redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Crypt/Random, Next: Crypt/Rijndael, Prev: Crypt/RandPasswd, Up: Module List Cryptographically Secure, True Random Number Generator. ******************************************************* NAME ==== Crypt::Random - Cryptographically Secure, True Random Number Generator. VERSION ======= $Revision: 0.33 $ $Date: 2001/02/18 20:56:07 $ SYNOPSIS ======== use Crypt::Random qw( makerandom ); my $r = makerandom ( Size => 512, Strength => 1 ); DESCRIPTION =========== Crypt::Random is an interface module to the /dev/random device found on most modern Unix systems. The /dev/random driver gathers environmental noise from various non-deterministic sources including inter-keyboard timings and inter-interrupt timings that occur within the operating system environment. The /dev/random driver maintains an estimate of true randomness in the pool and decreases it every time random strings are requested for use. When the estimate goes down to zero, the routine blocks and waits for the occurrence of non-deterministic events to refresh the pool. The /dev/random kernel module also provides another interface, /dev/urandom, that does not wait for the entropy-pool to recharge and returns as many bytes as requested. /dev/urandom is considerably faster at generation compared to /dev/random, which should be used only when very high quality randomness is desired. METHODS ======= makerandom() Generates a random number of requested bitsize in base 10. Following arguments can be specified. Size Bitsize of the random number. Strength 0 || 1 Value of 1 implies that /dev/random should be used for requesting random bits while 0 implies /dev/urandom. Device Alternate device to request random bits from. makerandom_itv() Generates a random number in the specified interval. In addition to the arguments to makerandom() following attributes can be specified. Lower Inclusive Lower limit. Upper Exclusive Upper limit. DEPENDENCIES ============ Crypt::Random needs Math::Pari 2.001802 or higher. As of this writing, the latest version of Math::Pari isn't available from CPAN. Fetch it from ftp://ftp.math.ohio-state.edu/pub/users/ilya/perl/modules/ BIBLIOGRAPHY ============ 1. random.c by Theodore Ts'o. Found in drivers/char directory of the Linux kernel sources. 2. Handbook of Applied Cryptography by Menezes, Paul C. van Oorschot and Scott Vanstone. AUTHOR ====== Vipul Ved Prakash,  File: pm.info, Node: Crypt/Rijndael, Next: Crypt/Rot13, Prev: Crypt/Random, Up: Module List Crypt::CBC compliant Rijndael encryption module *********************************************** NAME ==== Crypt::Rijndael - Crypt::CBC compliant Rijndael encryption module SYNOPSIS ======== use Crypt::Rijndael; # keysize() is 32, but 24 and 16 are also possible # blocksize() is 16 $cipher = new Crypt::Rijndael "a" x 32, Crypt::Rijndael::MODE_CBC; $crypted = $cipher->encrypt($plaintext); # - OR - $plaintext = $cipher->decrypt($crypted); DESCRIPTION =========== This module implements the Rijndael cipher, which has just been selected as the Advanced Encryption Standard. keysize Returns the keysize, which is 32 (bytes). The Rijndael 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 Rijndael is 16 bytes (128 bits), although the algorithm actually supports any blocksize that is any multiple of our bytes. 128 bits, is however, the AES-specified block size, so this is all we support for now. $cipher = new $key [, $mode] Create a new `Crypt::Rijndael' 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 codebook mode, the default) or `MODE_CBC' (cipher block chaining, the same that `Crypt::CBC' does). ECB mode is very insecure (read a book on cryptography if you dont know why!), so you should probably use CBC mode. $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) Decrypts $data. SEE ALSO ======== L BUGS ==== Should EXPORT or EXPORT_OK the MODE constants. There should be a way to access initial IV contents :( There may be endian issues involved in this particular implementation of Rijndael. I have not tested my implementation on big-endian architectures but it is my belief that at the very least, this code running on big endian architectures will be interoperable with the same code running on other big endian architectures, but will not produce the correct results vis-a-vis the Rijndael testsuites. I do not have access to a big-endian machine and thus have no way of testing this assertion. AUTHOR ====== Rafael R. Sevilla The Rijndael Algorithm was developed by Vincent Rijmen and Joan Daemen, and has been selected as the US Government's Advanced Encryption Standard.  File: pm.info, Node: Crypt/Rot13, Next: Crypt/SSLeay, Prev: Crypt/Rijndael, Up: Module List a rotational deviator ********************* NAME ==== Crypt::Rot13 - a rotational deviator SYNOPSIS ======== #!/usr/bin/env perl $^W = 1; use strict; use Crypt::Rot13; my $cryptochango = new Crypt::Rot13; $cryptochango->charge("Someone help us, please!"); print $cryptochango->rot13(5), "\n"; DESCRIPTION =========== Rot13 provides an object into which arrays may be placed, and then returned to you in altered - specifically: rotated - form. The above code would print, "Xtrjtsj mjqu zx, uqjfxj!". If instead of rot13(5), rot13(11) had been used the result would have been "Dzxpzyp spwa fd, awpldp!", and of course just rot13() would have resulted in the expected, "Fbzrbar uryc hf, cyrnfr!". Valid rot13() arguments are 0-26, though 0 and 26 do not alter the array. Crypt::Rot13 has the following methods. new standard constructor, this creates an array object, which is most convienent for mass text deviation. (For clarification, the object *is* an array; not a hash as most are. This is better suited to mass rotations.) charge defines the array object. peek returns unaltered value of array object NOTE: rot13 as described above does not alter the object! rot13 degree rotates alphabetical characters of array object degree times toward the Unreachable Wrapping Z, or 13 times if degree is omitted. LICENSE ======= Copyright (C) 1999 julian fondren This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA AUTHOR ====== Julian Fondren is julian@imaji.net, and can usually be found on #Perl, EFnet IRC. SEE ALSO ======== perl(1)  File: pm.info, Node: Crypt/SSLeay, Next: Crypt/Solitaire, Prev: Crypt/Rot13, Up: Module List OpenSSL glue that provides LWP https support ******************************************** NAME ==== Crypt::SSLeay - OpenSSL glue that provides LWP https support SYNOPSIS ======== lwp-request https://www.nodeworks.com use LWP::UserAgent; my $ua = new LWP::UserAgent; my $req = new HTTP::Request('GET', 'https://www.nodeworks.com'); my $res = $ua->request($req); print $res->code."\n"; # PROXY SUPPORT $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port'; # PROXY_BASIC_AUTH $ENV{HTTPS_PROXY_USERNAME} = 'username'; $ENV{HTTPS_PROXY_PASSWORD} = 'password'; # DEFAULT SSL VERSION $ENV{HTTPS_VERSION} = '3'; DESCRIPTION =========== This perl module provides support for the https protocol under LWP, so that a LWP::UserAgent can make https GET & HEAD & POST requests. Please see perldoc LWP for more information on POST requests. The Crypt::SSLeay package contains Net::SSL, which is automatically loaded by LWP::Protocol::https on https requests, and provides the necessary SSL glue for that module to work via these deprecated modules: Crypt::SSLeay::CTX Crypt::SSLeay::Conn Crypt::SSLeay::X509 Work on Crypt::SSLeay has been continued only to provide https support for the LWP - libwww perl libraries. If you want access to the OpenSSL API via perl, check out Sampo's Net::SSLeay. INSTALL ======= OpenSSL ------- You must have OpenSSL or SSLeay installed before compiling this module. You can get the latest OpenSSL package from: http://www.openssl.org When installing openssl make sure your config looks like: > ./config --openssldir=/usr/local/openssl or > ./config --openssldir=/usr/local/ssl then > make > make test > make install This way Crypt::SSLeay will pick up the includes and libraries automatically. If your includes end up going into a separate directory like /usr/local/include, then you may need to symlink /usr/local/openssl/include to /usr/local/include Crypt::SSLeay ------------- The latest Crypt::SSLeay can be found at your nearest CPAN, and also: http://www.perl.com/CPAN-local/modules/by-module/Crypt/ Once you have downloaded it, Crypt::SSLeay installs easily using the make or nmake commands as shown below. > perl Makefile.PL > make > make test > make install * use nmake for win32 !!! NOTE for Win32 users, few people seem to be able to build W Crypt::SSLeay successfully on that platform. You don't need I to because ActiveState has already compiled it for you, N and is available for their perl builds 618 & 522 as a ppm 3 install. It may also be available for their latest build. 2 Keywords: WinNT, Win95, Win98, 95, 98, NT, 2000 !!! Please see http://www.activestate.com/ PROXY SUPPORT ============= For proxying web requests, like with LWP::UserAgent->proxy(), or lwp-request -p ..., you need to set an environment variable HTTPS_PROXY to your proxy server & port, as in: # PROXY SUPPORT $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port'; $ENV{HTTPS_PROXY} = '127.0.0.1:8080'; Use of the HTTPS_PROXY environment variable in this way is compatible with LWP::UserAgent->env_proxy() usage. If we could find the current LWP object executing while in Net::SSL context, then we could support proxy() method too, but it does not seem feasible to do so at this time. Basic auth credentials to the proxy server can be provided this way: # PROXY_BASIC_AUTH $ENV{HTTPS_PROXY_USERNAME} = 'username'; $ENV{HTTPS_PROXY_PASSWORD} = 'password'; SSL VERSIONS ============ Crypt::SSLeay tries very hard to connect to ANY SSL web server trying to accomodate servers that are buggy, old or simply not standards compliant. To this effect, this module will try SSL connections in this order: SSL v23 - should allow v2 & v3 servers to pick their best type SSL v3 - best connection type SSL v2 - old connection type Unfortunately, some servers seem not to handle a reconnect to SSL v3 after a failed connect of SSL v23 is tried, so you may set before using LWP or Net::SSL: $ENV{HTTPS_VERSION} = 3; so that a SSL v3 connection is tried first. At this time only a SSL v2 connection will be tried after this, as the connection attempt order remains unchanged by this setting. COMPATIBILITY ============= This module has been compiled on the following platforms: PLATFORM CPU SSL PERL VER DATE WHO -------- --- --- ---- --- ---- --- Linux 2.2.14 x86 OpenSSL 0.9.6 5.00503 .21 2001-01-10 Joshua Chamas WinNT SP6 x86 OpenSSL 0.9.4 5.00404 .21 2001-01-10 Joshua Chamas AIX 4.3.2 RS/6000 OpenSSL 0.9.6 5.6.0 .19 2001-01-08 Peter Heimann Solaris 2.6 x86 OpenSSL 0.9.5a 5.00501 .17 2000-09-04 Joshua Chamas Linux 2.2.12 x86 OpenSSL 0.9.5a 5.00503 .16 2000-07-13 David Harris FreeBSD 3.2 ?x86 OpenSSL 0.9.2b 5.00503 ? 1999-09-29 Rip Toren Solaris 2.6 ?Sparc OpenSSL 0.9.4 5.00404 ? 1999-08-24 Patrick Killelea FreeBSD 2.2.5 x86 OpenSSL 0.9.3 5.00404 ? 1999-08-19 Andy Lee Solaris 2.5.1 USparc OpenSSL 0.9.4 5.00503 ? 1999-08-18 Marek Rouchal Solaris 2.6 x86 SSLeay 0.8.0 5.00501 ? 1999-08-12 Joshua Chamas Linux 2.2.10 x86 OpenSSL 0.9.4 5.00503 ? 1999-08-11 John Barrett WinNT SP4 x86 SSLeay 0.9.2 5.00404 ? 1999-08-10 Joshua Chamas BUILD NOTES =========== Win32, WinNT, Win2000, can't build ---------------------------------- If you cannot get it to build on your windows box, try ActiveState perl, at least their builds 522 & 618 are known to have a ppm install of Crypt::SSLeay available. Please see http://www.activestate.com for more info. AIX 4.3.2 - Symbol Error: __umoddi3 : referenced symbol not found ----------------------------------------------------------------- The __umoddi3 problem applies here as well when compiling with gcc. Alternative solution: In Makefile.PL, prepend -L/usr/local// to the $LIBS value. Add after line 82: $LIBS = '-L' . dirname(`gcc -print-libgcc-file-name`) . ' ' . $LIBS; Solaris x86 - Symbol Error: __umoddi3 : referenced symbol not found ------------------------------------------------------------------- Problem: On Solaris x86, the default PERL configuration, and preferred, is to use the ld linker that comes with the OS, not gcc. Unfortunately during the OpenSSL build process, gcc generates in libcrypto.a, from bn_word.c, the undefined symbol __umoddi3, which is supposed to be later resolved by gcc from libgcc.a The system ld linker does not know about libgcc.a by default, so when building Crypt::SSLeay, there is a linker error for __umoddi3 Solution: The fix for this symlink your libgcc.a to some standard directory like /usr/local/lib, so that the system linker, ld, can find it when building Crypt::SSLeay. FreeBSD 2.x.x / Solaris - ... des.h:96 #error _ is defined ... -------------------------------------------------------------- If you encounter this error: "...des.h:96: #error _ is defined, but some strange definition the DES library cannot handle that...," then you need to edit the des.h file and comment out the "#error" line. Its looks like this error might be common to other operating systems, and that occurs with OpenSSL 0.9.3. Upgrades to 0.9.4 seem to fix this problem. NOTES ===== Many thanks to Gisle Aas for the original writing of this module and many others including libwww for perl. The web will never be the same :) Ben Laurie deserves kudos for his excellent patches for better error handling, SSL information inspection, and random seeding. James Woodyatt is a champ for finding a ridiculous memory leak that has been the bane of many a Crypt::SSLeay user. Thanks to Bryan Hart for his patch adding proxy support, and thanks to Tobias Manthey for submitting another approach. SUPPORT ======= For OpenSSL and Crypt::SSLeay support, please email the openssl user mailing list at openssl-users@openssl.org Emails to the list sent with at least Crypt::SSLeay in the subject line will be responded to more quickly by myself. Please make the subject line informative like Subject: [Crypt::SSLeay] compile problems on Solaris This module was originally written by Gisle Aas, and I am now maintaining it. COPYRIGHT ========= Copyright (c) 1999-2001 Joshua Chamas. Copyright (c) 1998 Gisle Aas. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Crypt/Solitaire, Next: Crypt/TripleDES, Prev: Crypt/SSLeay, Up: Module List Solitaire encryption ******************** NAME ==== Crypt::Solitaire - Solitaire encryption SYNOPSIS ======== use Crypt::Solitaire; my $encrypted = Pontifex( $plaintext, $passphrase, $mode ); DESCRIPTION =========== Solitaire is a top-notch pencil-and-paper encryption system developed by Bruce Schneier. Here is the description in Schneier's own words: "In Neal Stephenson's novel Cryptonomicon, the character Enoch Root describes a cryptosystem code-named "Pontifex" to another character named Randy Waterhouse, and later reveals that the steps of the algorithm are intended to be carried out using a deck of playing cards. These two characters go on to exchange several encrypted messages using this system. The system is called "Solitaire" (in the novel, "Pontifex" is a code name intended to temporarily conceal the fact that it employs a deck of cards) and I designed it to allow field agents to communicate securely without having to rely on electronics or having to carry incriminating tools. An agent might be in a situation where he just does not have access to a computer, or may be prosecuted if he has tools for secret communication. But a deck of cards...what harm is that? "Solitaire gets its security from the inherent randomness in a shuffled deck of cards. By manipulating this deck, a communicant can create a string of "random" letters that he then combines with his message. Of course Solitaire can be simulated on a computer, but it is designed to be implemented by hand. "Solitaire may be low-tech, but its security is intended to be high-tech. I designed Solitaire to be secure even against the most well-funded military adversaries with the biggest computers and the smartest cryptanalysts. Of course, there is no guarantee that someone won't find a clever attack against Solitaire, but the algorithm is certainly better than any other pencil-and-paper cipher I've ever seen." Simple system, easy to use, and relatively fast. LIMITATIONS =========== Restricted only to letters A..Z. Lower case letters are converted to upper case, and due to the fact that Solitaire applies its own formatting to the text, the output can be a little tricky at first glance. METHODS ======= Pontifex $text, $passphrase, $mode $text is encrypted using $passphrase. Encrypts or decrypts, based on $mode. Mode must be set to "e" or "d," for encrypting and decrypting, respectively. AUTHOR ====== Designed by Bruce Schneier (President, Counterpane Systems) Original Perl Code by Ian Goldberg , 19980817 Minor changes and module-ification by Kurt Kincaid SEE ALSO ======== perl(1), Counterpane System (http://www.counterpane.com).  File: pm.info, Node: Crypt/TripleDES, Next: Crypt/Twofish2, Prev: Crypt/Solitaire, Up: Module List Triple DES encyption. ********************* NAME ==== Crypt::TripleDES - Triple DES encyption. SYNOPSIS ======== my $des = new Crypt::TripleDES; my $cyphertext = $des->encrypt3 ( $plaintext, $passphrase ); my $plaintext = $des->decrypt3 ( $cyphertext, $passphrase ); DESCRIPTION =========== This module implements 3DES encryption in ECB mode. The code is based on Eric Young's implementation of DES in pure perl. It's quite slow because of the way Perl handles bit operations and is not recommended for use with large texts. METHODS ======= new The constructor. encrypt3 $plaintext, $passphrase Encrypts the plaintext string using the passphrase. Whitespace characters are appended to the string if its length is not a multiple of eight. User applications can correct for this by storing plaintext size with the cyphertext. The passphrase is an ASCII character string of upto 48 characters. decrypt3 $cyphertext, $passphrase Inverse of encrypt3(). AUTHOR ====== Vipul Ved Prakash, mail@vipul.net Eric Young, eay@psych.psy.uq.oz.au Patches: Jonathan Mayer  File: pm.info, Node: Crypt/Twofish2, Next: Crypt/UnixCrypt, Prev: Crypt/TripleDES, Up: Module List Crypt::CBC compliant Twofish encryption module ********************************************** 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 thw 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), since `Crypt::Twofish2' can work in either ECB or CBC mode. 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 ======== *Note Crypt/CBC: Crypt/CBC,, `Crypt::Twofish' in this node. BUGS ==== Should EXPORT or EXPORT_OK the MODE constants. The testsuite does not check wether the encrypted valued are correct. 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 ;) AUTHOR ====== Marc Lehmann http://www.goof.com/pcg/marc/ The actualy twofish encryption is written in horribly microsoft'ish looking almost ansi-c by Doug Whiting.