NAME
Crypt::RSA - RSA public-key cryptosystem.
VERSION
$Revision: 1.31 $ (Beta)
$Date: 2001/03/31 02:45:22 $
SYNOPSIS
my $rsa = new Crypt::RSA;
my ($public, $private) = $rsa->keygen (
Identity => 'Lord Macbeth <macbeth@glamis.com>',
Size => 2048,
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 => $message,
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();
DESCRIPTION
Crypt::RSA is a pure-perl, cleanroom implementation of the RSA public-key cryptosystem, written atop the blazingly fast number theory library PARI. As far as possible, Crypt::RSA conforms with PKCS #1, RSA Cryptography Specifications v2.1[13].
Crypt::RSA is structured as a bundle of modules that provide arbitrary length key pair generation, plaintext-aware encryption (OAEP) and digital signatures with appendix (PSS). Crypt::RSA provides a convenient, scheme-independent interface to the other modules in the bundle.
WARNINGS
- ASN.1 encoded formats are not supported yet.
- This is beta, and largely untested, software. Please use at your own risk!
METHODS
new()
Constructor.
keygen()
keygen() is a synonym for Crypt::RSA::Key::generate(). See Crypt::RSA::Key(3) manpage for usage details.
encrypt()
encrypt() performs RSA encryption on a string of arbitrary length with a public key using the encryption scheme bound to the object at creation. The default scheme is OAEP, implemented in Crypt::RSA::ES::OAEP(3). encrypt() returns cyphertext (a string) on success and a non-true value on failure. It takes a hash as argument with following keys:
- Message
-
An arbitrary length string to be encrypted.
- Key
-
Public key of the recipient, a Crypt::RSA::Key::Public object.
- Armour
-
An optional boolean parameter that causes encrypt() to encode the cyphertext as a 6-bit clean ASCII message.
decrypt()
decrypt() performs RSA decryption with a private key using the encryption scheme bound to the object at creation. The default scheme is OAEP, implemented in Crypt::RSA::ES::OAEP(3). decrypt() returns plaintext on success and a non-true value on failure. It takes a hash as argument with following keys:
- Cyphertext
-
Encrypted text or arbitrary length.
- Key
-
Private key, a Crypt::RSA::Key::Private object.
- Armour
-
Boolean parameter that specifies whether the Cyphertext is encoded in 6-bit ASCII.
sign()
sign() creates an RSA signature on a string with a private key using the signature scheme bound to the object at creation. The default scheme is PSS, implemented in Crypt::RSA::SS::PSS(3). sign() returns a signature on success and a non-true value on failure. It takes a hash as argument with following keys:
- Message
-
A string to be signed.
- Key
-
Private key of the sender, a Crypt::RSA::Key::Private object.
- Armour
-
An optional boolean parameter that causes sign() to encode the signature as a 6-bit clean ASCII message.
verify()
verify() verifies an RSA signature with a public key using the signature scheme bound to the object at creation. The default scheme is PSS, implemented in Crypt::RSA::SS::PSS(3). verify() returns a true value on success and a non-true value on failure. It takes a hash as argument with following keys:
- Message
-
The original signed message, a string of arbitrary length.
- Key
-
Public key of the signer, a Crypt::RSA::Key::Public object.
- Sign
-
Signature computed with sign(), a string.
- Armour
-
Boolean parameter that specifies whether the Signature is encoded in 6-bit ASCII.
MODULES
Apart from Crypt::RSA, the following modules are intended for application developer and end-user consumption:
- Crypt::RSA::Key
-
RSA key pair generator.
- Crypt::RSA::Key::Public
-
RSA Public Key Management.
- Crypt::RSA::Key::Private
-
RSA Private Key Management.
- Crypt::RSA::ES::OAEP
-
Plaintext-aware encryption with RSA.
- Crypt::RSA::SS::PSS
-
Probabilistic Signature Scheme based on RSA.
ERROR HANDLING
All modules in the Crypt::RSA bundle use a common error handling method. When a method fails it returns a non-true value and sets $self->errstr to a string that explains the reason for the error. Private keys and plaintext representations passed to the method in question are wiped from memory.
AUTHOR
Vipul Ved Prakash, <mail@vipul.net>
ACKNOWLEDGEMENTS
Thanks to Ilya Zakharevich for answering even the goofiest of my questions regarding Math::Pari with unwavering patience. Shizukesa on #perl for clueing me into the error handling method used in this module and a-mused for good advice.
LICENSE
Copyright (c) 2000-2001, Vipul Ved Prakash. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
Crypt::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).
MAILING LIST
pac@lists.vipul.net is a mailing list for discussing development of asymmetric cryptography modules in perl. Please send Crypt::RSA related communications directly to the list address. Subscription interface for pac is at http://lists.vipul.net/mailman/listinfo/pac/
BIBLIOGRAPHY
(Chronologically sorted.)
- 1 R. Rivest, A. Shamir, L. Aldeman. A Method for Obtaining Digital Signatures and Public-Key Cryptosystems (1978).
- 2 U. Maurer. Fast Generation of Prime Numbers and Secure Public-Key Cryptographic Parameters (1994).
- 3 M. Bellare, P. Rogaway. Optimal Asymmetric Encryption - How to Encrypt with RSA (1995).
- 4 M. Bellare, P. Rogaway. The Exact Security of Digital Signatures - How to sign with RSA and Rabin (1996).
- 5 B. Schneier. Applied Cryptography, Second Edition (1996).
- 6 A. Menezes, P. Oorschot, S. Vanstone. Handbook of Applied Cryptography (1997).
- 7 D. Boneh. Twenty Years of Attacks on the RSA Cryptosystem (1998).
- 8 D. Bleichenbacher, M. Joye, J. Quisquater. A New and Optimal Chosen-message Attack on RSA-type Cryptosystems (1998).
- 9 B. Kaliski, J. Staddon. Recent Results on PKCS #1: RSA Encryption Standard, RSA Labs Bulletin Number 7 (1998).
- 10 B. Kaliski, J. Staddon. PKCS #1: RSA Cryptography Specifications v2.0, RFC 2437 (1998).
- 11 SSH Communications Security. SSH 1.2.7 source code (1998).
- 12 S. Simpson. PGP DH vs. RSA FAQ v1.5 (1999).
- 13 RSA Laboratories Draft I, PKCS #1 v2.1: RSA Cryptography Standard (1999).
- 14 E. Young, T. Hudson, OpenSSL Team. OpenSSL 0.9.5a source code (2000).
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 433:
=over without closing =back