NAME

       Crypt::CipherSaber - Perl module implementing CipherSaber encryption.

SYNOPSIS

         use Crypt::CipherSaber;
         my $cs = Crypt::CipherSaber->new('my sad secret key');

         my $coded   = $cs->encrypt('Here is a secret message for you');
         my $decoded = $cs->decrypt($coded);

         # encrypt from and to a file
         open my $in,       'secretletter.txt' or die "Can't open infile: $!";
         open my $out, '>', 'secretletter.cs1' or die "Can't open outfile: $!";
         binmode $in;
         binmode $out;

         $cs->fh_crypt($in, $out, 1);

         # decrypt from and to a file
         open my $in,       'secretletter.txt' or die "Can't open infile: $!";
         open my $out, '>', 'secretletter.cs1' or die "Can't open outfile: $!";

         binmode $in;
         binmode $out;
         $cs->fh_crypt($in, $out);

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. Relatively, given 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 is a required parameter: the key
           used to encrypt or to decrypt messages.  $N is optional.  If provided and greater than
           one, it causes the object to use 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 generates 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 handles binary filesIf 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()" operator), 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.

       fh_crypt( $in_fh, $out_fh, ($iv))
           For the sake of efficiency, Crypt::CipherSaber can operate on filehandles.  It's not
           super brilliant, but it's relatively fast and sane.  If your platform needs to use
           "binmode()", this is your responsibility.  It is also your responsibility to close the
           files.

           You may also pass in an optional third parameter, an IV.  There are three
           possibilities here.  If you pass no IV, "fh_crypt()" will pull the first ten bytes
           from the input filehandle and use that as an IV.  This corresponds to decryption.  If
           you pass in an IV of your own, it will use that when encrypting the file.  If you pass
           in the value 1, it will generate a new, random IV for you.  This corresponds to an
           encryption.

COPYRIGHT AND LICENSE

       Copyright (C) 2000 - 2015 chromatic

       This library is free software; you can use, modify, and redistribute it under the same
       terms as Perl 5.20.x itself.

AUTHOR

       chromatic "chromatic at cpan dot org"

       thanks to jlp for testing, moral support, and never fearing the icky details and to the
       fine folks at PerlMonks <http://perlmonks.org/>.

       Additional thanks to Olivier Salaun and the Sympa project <http://www.sympa.org> for
       testing.

SEE ALSO

       the CipherSaber home page at <http://ciphersaber.gurus.com/>

       perl(1), rand().