.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Crypt::CipherSaber 3pm"
.TH Crypt::CipherSaber 3pm "2023-10-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::CipherSaber \- Perl module implementing CipherSaber encryption.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Crypt::CipherSaber;
\&  my $cs = Crypt::CipherSaber\->new(\*(Aqmy sad secret key\*(Aq);
\&
\&  my $coded   = $cs\->encrypt(\*(AqHere is a secret message for you\*(Aq);
\&  my $decoded = $cs\->decrypt($coded);
\&
\&  # encrypt from and to a file
\&  open my $in,       \*(Aqsecretletter.txt\*(Aq or die "Can\*(Aqt open infile: $!";
\&  open my $out, \*(Aq>\*(Aq, \*(Aqsecretletter.cs1\*(Aq or die "Can\*(Aqt open outfile: $!";
\&  binmode $in;
\&  binmode $out;
\&
\&  $cs\->fh_crypt($in, $out, 1);
\&
\&  # decrypt from and to a file
\&  open my $in,       \*(Aqsecretletter.txt\*(Aq or die "Can\*(Aqt open infile: $!";
\&  open my $out, \*(Aq>\*(Aq, \*(Aqsecretletter.cs1\*(Aq or die "Can\*(Aqt open outfile: $!";
\&
\&  binmode $in;
\&  binmode $out;
\&  $cs\->fh_crypt($in, $out);
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1RC4.\s0 \fIRelatively\fR, given \s-1RC4.\s0
.PP
Encryption and decryption are done based on a secret key, which must be shared
with all intended recipients of a message.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew($key, \f(CB$N\fB)\fR" 4
.IX Item "new($key, $N)"
Initialize a new Crypt::CipherSaber object.  \f(CW$key\fR is a required parameter:
the key used to encrypt or to decrypt messages.  \f(CW$N\fR 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.  \f(CW$N\fR must be a positive
integer greater than one.
.IP "\fBencrypt($message)\fR" 4
.IX Item "encrypt($message)"
Encrypt a message.  This uses the key stored in the current Crypt::CipherSaber
object.  It generates a 10\-byte random \s-1IV\s0 (Initialization Vector)
automatically, as defined in the \s-1RC4\s0 specification.  This returns a string
containing the encrypted message.
.Sp
Note that the encrypted message may contain unprintable characters, as it uses
the extended \s-1ASCII\s0 character set (valid numbers 0 through 255).
.IP "\fBdecrypt($message)\fR" 4
.IX Item "decrypt($message)"
Decrypt a message.  For the curious, the first ten bytes of an encrypted
message are the \s-1IV,\s0 so this must strip it off first.  This returns a string
containing the decrypted message.
.Sp
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.
.IP "\fBcrypt($iv, \f(CB$message\fB)\fR" 4
.IX Item "crypt($iv, $message)"
If you wish to generate the \s-1IV\s0 with a more cryptographically secure random
string (at least compared to Perl's builtin \f(CW\*(C`rand()\*(C'\fR operator), you may do so
separately, passing it to this method directly.  The \s-1IV\s0 must be a ten-byte
string consisting of characters from the extended \s-1ASCII\s0 set.
.Sp
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 \fB\fBdecrypt()\fB\fR, though.  The more random the \s-1IV,\s0 the stronger
the encryption tends to be.  On some operating systems, you can read from
\&\fI/dev/random\fR.  Other approaches are the Math::TrulyRandom module, or
compressing a file, removing the headers, and compressing it again.
.IP "\fBfh_crypt( \f(CB$in_fh\fB, \f(CB$out_fh\fB, ($iv))\fR" 4
.IX Item "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 \f(CW\*(C`binmode()\*(C'\fR, this is your responsibility.  It is also your
responsibility to close the files.
.Sp
You may also pass in an optional third parameter, an \s-1IV.\s0  There are three
possibilities here.  If you pass no \s-1IV,\s0 \f(CW\*(C`fh_crypt()\*(C'\fR will pull the first ten
bytes from the input filehandle and use that as an \s-1IV.\s0  This corresponds to
decryption.  If you pass in an \s-1IV\s0 of your own, it will use that when encrypting
the file.  If you pass in the value \f(CW1\fR, it will generate a new, random \s-1IV\s0 for
you.  This corresponds to an encryption.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2000 \- 2015 chromatic
.PP
This library is free software; you can use, modify, and redistribute it under
the same terms as Perl 5.20.x itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
chromatic \f(CW\*(C`chromatic at cpan dot org\*(C'\fR
.PP
thanks to jlp for testing, moral support, and never fearing the icky details
and to the fine folks at PerlMonks <http://perlmonks.org/>.
.PP
Additional thanks to Olivier Salaun and the Sympa project
<http://www.sympa.org> for testing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
the CipherSaber home page at <http://ciphersaber.gurus.com/>
.PP
\&\fBperl\fR\|(1), \fBrand()\fR.