
NAMECrypt::RSA  RSA publickey cryptosystem.SYNOPSISmy $rsa = new Crypt::RSA; my ($public, $private) = $rsa>keygen ( Identity => 'Lord Macbeth <macbeth@glamis.com>', Size => 1024, Password => 'A day so foul & fair', Verbosity => 1, ) or die $rsa>errstr(); my $cyphertext = $rsa>encrypt ( Message => $message, Key => $public, Armour => 1, )  die $rsa>errstr(); my $plaintext = $rsa>decrypt ( Cyphertext => $cyphertext, Key => $private, Armour => 1, )  die $rsa>errstr(); my $signature = $rsa>sign ( Message => $message, Key => $private )  die $rsa>errstr(); my $verify = $rsa>verify ( Message => $message, Signature => $signature, Key => $public )  die $rsa>errstr(); NOTEThis manual assumes familiarity with publickey cryptography and the RSA algorithm. If you don't know what these are or how they work, please refer to the sci.crypt FAQ[15]. A formal treatment of RSA can be found in [1].DESCRIPTIONCrypt::RSA is a pureperl, cleanroom implementation of the RSA publickey cryptosystem. It uses Math::Pari(3), a perl interface to the blazingly fast PARI library, for big integer arithmetic and number theoretic computations.Crypt::RSA provides arbitrary size keypair generation, plaintextaware encryption (OAEP) and digital signatures with appendix (PSS). For compatibility with SSLv3, RSAREF2, PGP and other applications that follow the PKCS #1 v1.5 standard, it also provides PKCS #1 v1.5 encryption and signatures. Crypt::RSA is structured as bundle of modules that encapsulate different parts of the RSA cryptosystem. The RSA algorithm is implemented in Crypt::RSA::Primitives(3). Encryption schemes, located under Crypt::RSA::ES, and signature schemes, located under Crypt::RSA::SS, use the RSA algorithm to build encryption/signature schemes that employ secure padding. (See the note on Security of Padding Schemes.) The key generation engine and other functions that work on both components of the keypair are encapsulated in Crypt::RSA::Key(3). Crypt::RSA::Key::Public(3) & Crypt::RSA::Key::Private(3) provide mechanisms for storage & retrival of keys from disk, decoding & encoding of keys in certain formats, and secure representation of keys in memory. Finally, the Crypt::RSA module provides a convenient, DWIM wrapper around the rest of the modules in the bundle. SECURITY OF PADDING SCHEMESIt has been conclusively shown that textbook RSA is insecure[3,7]. Secure RSA requires that plaintext is padded in a specific manner before encryption and signing. There are four main standards for padding: PKCS #1 v1.5 encryption & signatures, and OAEP encryption & PSS signatures. Crypt::RSA implements these as four modules that provide overloaded encrypt(), decrypt(), sign() and verify() methods that add padding functionality to the basic RSA operations.Crypt::RSA::ES::PKCS1v15(3) implements PKCS #1 v1.5 encryption, Crypt::RSA::SS::PKCS1v15(3) implements PKCS #1 v1.5 signatures, Crypt::RSA::ES::OAEP(3) implements Optimal Asymmetric Encryption and Crypt::RSA::SS::PSS(3) Probabilistic Signatures. PKCS #1 v1.5 schemes are older and hence more widely deployed, but PKCS #1 v1.5 encryption has certain flaws that make it vulnerable to chosencyphertext attacks[9]. Even though Crypt::RSA works around these vulnerabilities, it is recommended that new applications use OAEP and PSS, both of which are provably secure[13]. In any event, Crypt::RSA::Primitives (without padding) should never be used directly. That said, there exists a scheme called Simple RSA[16] that provides security without padding. However, Crypt::RSA doesn't implement this scheme yet. METHODS
MODULESApart from Crypt::RSA, the following modules are intended for application developer and enduser consumption:
CUSTOMISING A CRYPT::RSA OBJECTA Crypt::RSA object can be customized by passing any of the following keys in a hash to new(): ES to specify the encryption scheme, SS to specify the signature scheme, PP to specify the post processor, and KF to specify the key format. The value associated with these keys can either be a name (a string) or a hash reference that specifies a module name, its constructor, and constructor arguments. For example:my $rsa = new Crypt::RSA ( ES => 'OAEP' ); or my $rsa = new Crypt::RSA ( ES => { Module => 'Crypt::RSA::ES::OAEP' } ); A module thus specified need not be included in the Crypt::RSA bundle, but it must be interface compatible with the ones provided with Crypt::RSA. As of this writing, the following names are recognised:
ERROR HANDLINGAll modules in the Crypt::RSA bundle use a common error handling method (implemented in Crypt::RSA::Errorhandler(3)). When a method fails it returns undef and calls $self>error() with the error message. This error message is available to the caller through the errstr() method. For more details see the Crypt::RSA::Errorhandler(3) manpage.AUTHORVipul Ved Prakash, <mail@vipul.net>ACKNOWLEDGEMENTSThanks to Ilya Zakharevich for help with Math::Pari, Benjamin Trott for several patches including SSH key support, Genèche Ramanoudjame for extensive testing and numerous bug reports, Shizukesa on #perl for suggesting the error handling method used in this module, and Dave Paris for good advice.LICENSECopyright (c) 20002008, Vipul Ved Prakash. This code is free software; it is distributed under the same license as Perl itself.I have received requests for commercial licenses of Crypt::RSA, from those who desire contractual support and indemnification. I'd be happy to provide a commercial license if you need one. Please send me mail at "mail@vipul.net" with the subject "Crypt::RSA license". Please don't send me mail asking if you need a commercial license. You don't, if Artistic of GPL suit you fine. SEE ALSOCrypt::RSA::Primitives(3), Crypt::RSA::DataFormat(3), Crypt::RSA::Errorhandler(3), Crypt::RSA::Debug(3), Crypt::Primes(3), Crypt::Random(3), Crypt::CBC(3), Crypt::Blowfish(3), Tie::EncryptedHash(3), Convert::ASCII::Armour(3), Math::Pari(3), Class::Loader(3), cryptrsainteroperability(3), cryptrsainteroperabilitytable(3).REPORTING BUGSAll bug reports related to Crypt::RSA should go to rt.cpan.org at "http://rt.cpan.org/Dist/Display.html?Queue=CryptRSA"Crypt::RSA is considered to be stable. If you are running into a problem, it's likely of your own making. Please check your code and consult the documentation before posting a bug report. A google search with the error message might also shed light if it is a common mistake that you've made. If the module installation fails with a "Segmentation Fault" or "Bus Error", it is likely a Math::Pari issue. Please consult Math::Pari bugs on rt.cpan.org or open a bug there. There have been known issues on HPUX and SunOS systems (with Math::Pari), so if you are on those OSes, please consult Math::Pari resources before opening a Crypt::RSA bug. BIBLIOGRAPHYChronologically sorted (for the most part).
POD ERRORSHey! The above document had some coding errors, which are explained below:
Visit the GSP FreeBSD Man Page Interface. 