Crypt:...rSaber(3pm)

💖 Crypt::CipherSaber 💖

okay bestie, gather round, because today we're talking about Crypt::CipherSaber — a Perl module that does CipherSaber encryption, and it's from the 3pm section of the manual (that's the Perl module pages, iykyk 🎀).

---

✨ NAME ✨

Crypt::CipherSaber — a Perl module implementing CipherSaber encryption. that's it, that's the whole vibe 💅

---

🌸 SYNOPSIS 🌸

okay so here's the whole thing in action, no notes:

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 🦋

Crypt::CipherSaber implements CipherSaber encryption, which is described over at <http://ciphersaber.gurus.com/>. it's a simple algorithm, it's fairly speedy, and it's relatively secure, and it's based on RC4. and like… relatively, okay? given RC4. we said what we said 😭

so the tea is: encryption and decryption both happen based on a secret key, and you have to share that key with every single person who's supposed to be able to read the message. all the intended recipients. no key, no tea. periodt 💅

---

👑 METHODS 👑

💜 new($key, $N)

spins up a brand-new Crypt::CipherSaber object, slay.

• $key — required, bestie. this is the key that gets used to encrypt or decrypt messages. you literally cannot skip it.
• $N — optional. if you pass it in and it's greater than one, the object switches to CipherSaber-2 encryption, which is a lil slower but also a lil more secure. if you don't specify it, or if it's equal to 1, the module just defaults to CipherSaber-1 encryption.

🫶 heads up: $N has to be a positive integer greater than one.

🎀 encrypt($message)

encrypts a message, using the key that's already chilling inside the current Crypt::CipherSaber object. it auto-generates a 10-byte random IV (that's Initialization Vector, bestie) all by itself, exactly as defined in the RC4 specification. it hands you back a string with the encrypted message in it. iconic behavior honestly.

⚠️ note that the encrypted message may contain unprintable characters, because it's using the extended ASCII character set (valid numbers 0 through 255). so like… don't be weird about it.

🌈 decrypt($message)

decrypts a message. for the curious girlies: the first ten bytes of an encrypted message are the IV, so this has to strip that off first. it returns a string with the decrypted message inside.

the decrypted message can also contain unprintable characters, since the CipherSaber encryption scheme handles binary files. if that matters to you, please treat the results correctly, fr fr 🙈

🧚 crypt($iv, $message)

so if you wanna generate the IV yourself with something more cryptographically secure — at least compared to Perl's builtin rand() operator — you can totally do that separately and pass it straight into this method. the IV has to be a ten-byte string made of characters from the extended ASCII set. no cap.

this is generally only useful for encryption, though you can pull the first ten characters off an encrypted message and pass them in yourself. but like… you might as well just call decrypt(), bestie. the more random the IV is, 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. yes, really. 💀

⭐ 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, and honestly? we'll take it. 🫶

if your platform needs to use binmode(), that is your responsibility. it is also your responsibility to close the files. the module is not your mom.

you can also pass in an optional third parameter: an IV. there are three possibilities here, so let's break it down:

1. no IV passed — fh_crypt() pulls the first ten bytes from the input filehandle and uses that as the IV. this corresponds to decryption.
2. you pass in an IV of your own — it uses that when encrypting the file.
3. you pass in the value 1 — it generates a brand-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. besties really showed up for this one 🎀

---

🔥 SEE ALSO 🔥

• the CipherSaber home page at <http://ciphersaber.gurus.com/> ✨
• perl(1), rand().

---

and that's the whole page, bestie 💜 this lil doc came to you from perl v5.36.0, dated 2023-10-02, and it lives at Crypt:...rSaber(3pm) in the User Contributed Perl Documentation. go encrypt something cute, mwah 🎀💖✨