NAME

Crypt::RSA - RSA public-key cryptosystem.

VERSION

$Revision: 1.34 $ (Beta)
$Date: 2001/04/07 16:53:39 $

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.

Crypt::RSA::ES::PKCS1v15

PKCS #1 v1.5 encryption scheme.

Crypt::RSA::SS::PKCS1v15

PKCS #1 v1.5 signature scheme.

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), crypt-rsa-interoperability(3), crypt-rsa-interoperability-table(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).

cpanm Crypt::RSA

perl -MCPAN -e shell
install Crypt::RSA