Michael Robinton > Crypt-CapnMidNite > My_Module

Download:
Crypt-CapnMidNite-1.00.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

My_Module - Perl interface to MD5, RC4, encrypt/decrypt

SYNOPSIS ^

 use Crypt::MyModule;

Swiss army knife encode/decode, hash methods.

This mirrors the OO functionality of Digest::MD5, available from CPAN.org

 $md5 = Crypt::My_Module->new;          # for MD5
 $md5 = Crypt::My_Module->new_md5;      # same as above
 $md5 = Crypt::My_Module->reset;                # same as above

        or equivalent

 $md5 = new Crypt::My_Module;
 $md5 = new_md5 Crypt::My_Module; 
 $md5 = reset Crypt::My_Module;

 $md5 = $md5->add($data[,data,...]);
 $md5 = $md5->addfile(*FILE);

 $digest = $md5->digest;
 $digest = $md5->hexdigest;
 $digest = $md5->b64digest;

        or in one operation (after "new")

 $digest = $md5->md5($data[,data,...]);
 $digest = $md5->md5_hex($data[,data,...]);
 $digest = $md5->md5_base64($data[,data,...]);

RC4 stream encryptation is provide similar funcationality may be found in the module Crypt::RC4, available from CPAN.org. In addition, this module contains modified asymetric RC4 encryption/decryption methods that are not readily reversible and must use discreet encrypt and decrypt mechanisms.

 $crypt = Crypt::My_Module->new_rc4($key);
 $crypt = Crypt::My_Module->new_md5_rc4($key);  # use MD5 of key
 $crypt = Crypt::My_Module->new_crypt($key);    # modified RC4
 $crypt = Crypt::My_Module->new_md5_crypt($key);        # as above + MD5

* $encrypted = $crypt->encrypt($decrypted); $decrypted = $crypt->decrypt($encrypted);

  aliases for above

  $decrypted = $crypt->crypt($encrypted);
  $decrypted = $crypt->rc4($encrypted);
  $decrypted = $crypt->RC4($encrypted);

* $crypt = $crypt->encrypt_fileIO(*IN_FILE,*OUT_FILE); $crypt = $crypt->decrypt_fileIO(*IN_FILE,*OUT_FILE);

  alias for above

  $crypt = $crypt->crypt_fileIO(*IN_FILE,*OUT_FILE);

NOTE: * above not implemented in CapnMidNite for asymetric RC4 operation.

Special function for Crypt::Loader.pm. Returns a pointer to the crypt object but performs the crypt operation destructively on the $data

  $crypt = Crypt::My_Module->decode($key,$data);

Special function for Crypt::License.pm. Returns the seconds remaining until expiration, now() if no expiration or undef on failure.

  $expires = Crypt::My_Module->license(@mac_txt,$expire_time,$key)

Crypt related test functions:

        read or read/set RC4 x,y vectors

 $x_vector = $crypt->x($new_X | undef);
 $y_vector = $crypt->y($new_Y | undef);

        read encrypt/decrypt starting vectors

 $start_x_vector = $crypt->hx;  # sum of even bytes of $key % 256
 $start_y_vector = $crypt->hy;  # sum of odd bytes of $key % 256

DESCRIPTION ^

The Crypt::My_Module module allows you to use the RSA Data Security Inc. MD5 Message Digest algorithm, RC4 stream crypt function and a modified, not readily reversible RC4 based stream crypt from within Perl programs.

The MD5 functions in the module provide an object oriented interface that can handle messages of arbitrary length and which can read files directly.

A binary MD5 digest will be 16 bytes long. A hex MD5 digest will be 32 characters long. A base64 MD5 digest will be 22 characters long.

RC4 crypt functions provide conventional stream cipher with optional MD5 on the input key. As with the MD5 interface, the crypt functions can handle messages of arbitrary length and can read files directly.

The modified RC4 encryption/decryption scheme provides a non-symetric algorithm that is not readily reversible and must use discreet encrypt and decrypt mechanisms. Controls are provided to read and adjust the starting vector for the RC4 crypt array. These vectors are set automatically for x,y using the mod 256 sum of the even/odd bytes of the initialization key when the modified RC4 form is selected.

FUNCTIONS ^

No functions are exported.

MD5 METHODS ^

The following methods are available:

$md5 = Crypt::My_Module->new

The constructor returns a new Crypt::My_Module object which encapsulate the state of the MD5 message-digest algorithm. You can add data to the object and finally ask for the digest.

If called as a instance method (i.e. $md5->new) it will just reset the state the object to the state of a newly created object. No new object is created in this case.

$md5 = Crypt::My_Module->new_md5

This is just an alias for $md5->new.

$md5 = Crypt::My_Module->reset

This is just an alias for $md5->new.

$md5->add($data[,data,...])

The $data provided as argument are appended to the message we calculate the digest for. The return value is the $md5 object itself.

$md5->addfile($io_handle)

The $io_handle is read until EOF and the content is appended to the message we calculate the digest for. The return value is the $md5 object itself.

$md5->digest

Return the binary digest for the message.

Note that if initialized with new new_md5 reset, the digest operation is effectively a destructive, read-once operation. Once it has been performed, the Crypt::My_Module object is automatically reset and can be used to calculate another digest value.

However, if initialized by any of the new_md5_CRYPT methods below, $md5->digest will return the digest value of the crypt $key whenever $md5->digest method is called without effecting the the key or a subsequent digest method call.

$md5->hexdigest

Same as $md5->digest, but will return the digest in hexadecimal form.

$md5->b64digest

Same as $md5->digest, but will return a base64 encoded digest.

$md5->md5($data[,data,...])

Performs the same operation as $md5->add($data[,data,...]) $md5->digest

$md5->md5_hex($data[,data,...])

Same as $md5->md5($data), but will return the hexadecimal digest.

$md5->md5_base64($data[,data,...])

Same as $md5->md5($data), but will return a base64 encoded digest.

RC4 METHODS ^

The following methods are available:

$crypt = Crypt::My_Module->new_rc4($key)

The constructor returns a new Crypt::My_Module object which encapsulate the state of the RC4 algorithm. You can pass data through the object or directly process file IO.

$crypt = Crypt::My_Module->new_md5_rc4($key)

Same as above, except prior to initializing the virgin RC4 state, an MD5 operation is performed on the $key value. This MD5 value it then used to initialize the RC4 state.

$crypt = Crypt::My_Module->new_crypt($key)

Similar to new_rc4($key) except that asymetric encryption/decryption is enabled and the x,y starting vectors and preset to value determined by the $key value.

$crypt = Crypt::My_Module->new_md5_crypt($key)

Similar to new_crypt($key) above, except that an MD5 operation is performend as with new_md5_rc4($key) above prior to $key use.

$encrypted = $crypt->encrypt($decrypted)

Asymetric RC4 operation is not implemented in CapnMidNite. Encrypts text string using selected RC4 method.

$decrypted = $crypt->decrypt($encrypted)

Decrypts the text string using selected RC4 method.

$crypt->encrypt_fileIO(*IN_FILE,*OUT_FILE)

Asymetric encryptation not implemented in CapnMidNite. Encrypts an input file to an output file using selected RC4 method. The return value is the $crypt object itself.

$crypt->decrypt_fileIO(*IN_FILE,*OUT_FILE)

Decrypts an input file to an output file using selected RC4 method. The return value is the $crypt object itself.

$crypt = Crypt::My_Module->decode($key,$data)

Performs Asymetric crypt in the same fashion as:

  Crypt::My_Module->new_md5_crypt($key)->decrypt($data)

except that it returns the $crypt object rather than the crypted data. The data is operated on in place and may used directly as though data pointer \$data had been used.

$expires = Crypt::My_Module->license(@mac_txt,$expire_time,$key)

Presets the decoder with key based on license data and returns the time remaining until expiration of the License object or now() if no expiration or undef on failure. Decrypt using either of the standard 'crypt' methods. Use as follows:

  $crypt = Crypt::My_Module->new;
  $expires = $crypt->license(@mac_txt,$expire_time,$key);
  $decrypted = $crypt->decrypt($encrypted);
 or
  $crypt->decrypt_fileIO(*IN_FILE,*OUT_FILE);
$x_vector = $crypt->x($new_X)

Read or optionally set the x vector or the RC4 state array.

$y_vector = $crypt->y($new_Y)

Read or optionally set the y vector or the RC4 state array.

$start_x_vector = $crypt->hx

Read the starting x value of the RC4 state array

$start_y_vector = $crypt->hy

Read the starting y value of the RC4 state array

SEE ALSO ^

Digest::MD5, Crypt::RC4, RFC 1321

COPYRIGHT ^

 Copyright 2002 Michael Robinton, BizSystems
 Copyright 1998-1999 Gisle Aas.
 Copyright 1995-1996 Neil Winton.
 Copyright 1991-1992 RSA Data Security, Inc.

This module is free software; you can redistribute it and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free Software 
  Foundation; either version 1, or (at your option) any later version,

  or

  b) the "Artistic License" which comes with this module.

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 either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

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

The MD5 algorithm is defined in RFC 1321. The basic C code implementing the algorithm is derived from that in the RFC and is covered by the following copyright:

This copyright does not prohibit distribution of any version of Perl containing this extension under the terms of the GNU or Artistic licenses.

AUTHORS ^

RC4 (TM) was designed by Ron Rivest, and was previously a trade secret of RSA Data Security, Inc. The algorithm is now in the public domain. The name "RC4" is a trademark of RSA Data Security, Inc.

This RC4 stream encryptation an implementation based on the email posting of sterndark@netcom.com (David Sterndark) to the nwsgroups: sci.crypt,alt.security,comp.security.misc,alt.privacy on Sept. 14, 1994.

See: http://www.uni-koblenz.de/~motzek/html/dsds/rc4.htm

The original MD5 interface was written by Neil Winton (N.Winton@axion.bt.co.uk) and modified by Gisle Aas <gisle@aas.no>

SEE ALSO ^

Digest::MD5, Crypt::RC4, Crypt::License, RFC 1321

syntax highlighting: