My_Module_PM - metacpan.org

package Crypt::My_Module;

use strict;
#use warnings;
use vars qw($VERSION @ISA);

require Exporter;
require DynaLoader;
*import = \&Exporter::import;

#use AutoLoader qw(AUTOLOAD);

@ISA = qw(Exporter DynaLoader);

$VERSION = '1.00';

bootstrap Crypt::My_Module $VERSION;

# Preloaded methods go here.

*reset		= \&new_md5;
*rc4		= \&crypt;
*RC4		= \&crypt;
*decrypt	= \&crypt;
*decrypt_fileIO	= \&crypt_fileIO;

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__

=head1 NAME

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

=head1 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


=head1 DESCRIPTION

The C<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.

=head1 FUNCTIONS

No functions are exported.

=head1 MD5 METHODS

The following methods are available:

=over 4

=item $md5 = Crypt::My_Module->new

The constructor returns a new C<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.

=item $md5 = Crypt::My_Module->new_md5

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

=item $md5 = Crypt::My_Module->reset

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

=item $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.

=item $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.

=item $md5->digest

Return the binary digest for the message.

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

However, if initialized by any of the C<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.

=item $md5->hexdigest

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

=item $md5->b64digest

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

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

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

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

Same as $md5->md5($data), but will return the hexadecimal digest.
	
=item $md5->md5_base64($data[,data,...])

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

=back

=head1 RC4 METHODS

The following methods are available:

=over 4

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

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

=item $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.

=item $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.

=item $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.

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

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

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

Decrypts the text string using selected RC4 method.

=item $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.

=item $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.
 
=item $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.

=item $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);

=item $x_vector = $crypt->x($new_X)

Read or optionally set the C<x> vector or the RC4 state array.

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

Read or optionally set the C<y> vector or the RC4 state array.

=item $start_x_vector = $crypt->hx

Read the starting C<x> value of the RC4 state array

=item $start_y_vector = $crypt->hy

Read the starting C<y> value of the RC4 state array

=back

=head1 SEE ALSO

L<Digest::MD5>,
L<Crypt::RC4>,
RFC 1321

=head1 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:

=over 4

=item

Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
rights reserved.

License to copy and use this software is granted provided that it
is identified as the "RSA Data Security, Inc. MD5 Message-Digest
Algorithm" in all material mentioning or referencing this software
or this function.

License is also granted to make and use derivative works provided
that such works are identified as "derived from the RSA Data
Security, Inc. MD5 Message-Digest Algorithm" in all material
mentioning or referencing the derived work.

RSA Data Security, Inc. makes no representations concerning either
the merchantability of this software or the suitability of this
software for any particular purpose. It is provided "as is"
without express or implied warranty of any kind.

These notices must be retained in any copies of any part of this
documentation and/or software.

=back

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

=head1 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:
S<http://www.uni-koblenz.de/~motzek/html/dsds/rc4.htm>

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

=head1 SEE ALSO

L<Digest::MD5>,
L<Crypt::RC4>,
L<Crypt::License>,
RFC 1321

=cut
	Global
`s`	Focus search bar
`?`	Bring up this help dialog
	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)
	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse
	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)