1Crypt::RSA(3)         User Contributed Perl Documentation        Crypt::RSA(3)
2
3
4

NAME

6       Crypt::RSA - RSA public-key cryptosystem.
7

SYNOPSIS

9           my $rsa = new Crypt::RSA;
10
11           my ($public, $private) =
12               $rsa->keygen (
13                   Identity  => 'Lord Macbeth <macbeth@glamis.com>',
14                   Size      => 1024,
15                   Password  => 'A day so foul & fair',
16                   Verbosity => 1,
17               ) or die $rsa->errstr();
18
19
20           my $cyphertext =
21               $rsa->encrypt (
22                   Message    => $message,
23                   Key        => $public,
24                   Armour     => 1,
25               ) || die $rsa->errstr();
26
27
28           my $plaintext =
29               $rsa->decrypt (
30                   Cyphertext => $cyphertext,
31                   Key        => $private,
32                   Armour     => 1,
33               ) || die $rsa->errstr();
34
35
36           my $signature =
37               $rsa->sign (
38                   Message    => $message,
39                   Key        => $private
40               ) || die $rsa->errstr();
41
42
43           my $verify =
44               $rsa->verify (
45                   Message    => $message,
46                   Signature  => $signature,
47                   Key        => $public
48               ) || die $rsa->errstr();
49

NOTE

51       This manual assumes familiarity with public-key cryptography and the
52       RSA algorithm. If you don't know what these are or how they work,
53       please refer to the sci.crypt FAQ[15]. A formal treatment of RSA can be
54       found in [1].
55

DESCRIPTION

57       Crypt::RSA is a pure-perl, cleanroom implementation of the RSA public-
58       key cryptosystem. It uses Math::Pari(3), a perl interface to the
59       blazingly fast PARI library, for big integer arithmetic and number
60       theoretic computations.
61
62       Crypt::RSA provides arbitrary size key-pair generation, plaintext-aware
63       encryption (OAEP) and digital signatures with appendix (PSS). For
64       compatibility with SSLv3, RSAREF2, PGP and other applications that
65       follow the PKCS #1 v1.5 standard, it also provides PKCS #1 v1.5
66       encryption and signatures.
67
68       Crypt::RSA is structured as bundle of modules that encapsulate
69       different parts of the RSA cryptosystem. The RSA algorithm is
70       implemented in Crypt::RSA::Primitives(3). Encryption schemes, located
71       under Crypt::RSA::ES, and signature schemes, located under
72       Crypt::RSA::SS, use the RSA algorithm to build encryption/signature
73       schemes that employ secure padding. (See the note on Security of
74       Padding Schemes.)
75
76       The key generation engine and other functions that work on both
77       components of the key-pair are encapsulated in Crypt::RSA::Key(3).
78       Crypt::RSA::Key::Public(3) & Crypt::RSA::Key::Private(3) provide
79       mechanisms for storage & retrival of keys from disk, decoding &
80       encoding of keys in certain formats, and secure representation of keys
81       in memory.  Finally, the Crypt::RSA module provides a convenient, DWIM
82       wrapper around the rest of the modules in the bundle.
83

SECURITY OF PADDING SCHEMES

85       It has been conclusively shown that textbook RSA is insecure[3,7].
86       Secure RSA requires that plaintext is padded in a specific manner
87       before encryption and signing. There are four main standards for
88       padding: PKCS #1 v1.5 encryption & signatures, and OAEP encryption &
89       PSS signatures.  Crypt::RSA implements these as four modules that
90       provide overloaded encrypt(), decrypt(), sign() and verify() methods
91       that add padding functionality to the basic RSA operations.
92
93       Crypt::RSA::ES::PKCS1v15(3) implements PKCS #1 v1.5 encryption,
94       Crypt::RSA::SS::PKCS1v15(3) implements PKCS #1 v1.5 signatures,
95       Crypt::RSA::ES::OAEP(3) implements Optimal Asymmetric Encryption and
96       Crypt::RSA::SS::PSS(3) Probabilistic Signatures.
97
98       PKCS #1 v1.5 schemes are older and hence more widely deployed, but PKCS
99       #1 v1.5 encryption has certain flaws that make it vulnerable to chosen-
100       cyphertext attacks[9]. Even though Crypt::RSA works around these
101       vulnerabilities, it is recommended that new applications use OAEP and
102       PSS, both of which are provably secure[13]. In any event,
103       Crypt::RSA::Primitives (without padding) should never be used directly.
104
105       That said, there exists a scheme called Simple RSA[16] that provides
106       security without padding. However, Crypt::RSA doesn't implement this
107       scheme yet.
108

METHODS

110       new()
111           The constructor. When no arguments are provided, new() returns an
112           object loaded with default values. This object can be customized by
113           specifying encryption & signature schemes, key formats and post
114           processors. For details see the section on Customizing the
115           Crypt::RSA object later in this manpage.
116
117       keygen()
118           keygen() generates and returns an RSA key-pair of specified
119           bitsize.  keygen() is a synonym for Crypt::RSA::Key::generate().
120           Parameters and return values are described in the
121           Crypt::RSA::Key(3) manpage.
122
123       encrypt()
124           encrypt() performs RSA encryption on a string of arbitrary length
125           with a public key using the encryption scheme bound to the object.
126           The default scheme is OAEP. encrypt() returns cyphertext (a string)
127           on success and undef on failure. It takes a hash as argument with
128           following keys:
129
130           Message
131               An arbitrary length string to be encrypted.
132
133           Key Public key of the recipient, a Crypt::RSA::Key::Public(3) or
134               compatible object.
135
136           Armour
137               A boolean parameter that forces cyphertext through a post
138               processor after encrpytion. The default post processor is
139               Convert::ASCII::Armour(3) that encodes binary octets in 6-bit
140               clean ASCII messages. The cyphertext is returned as-is, when
141               the Armour key is not present.
142
143       decrypt()
144           decrypt() performs RSA decryption with a private key using the
145           encryption scheme bound to the object. The default scheme is OAEP.
146           decrypt() returns plaintext on success and undef on failure. It
147           takes a hash as argument with following keys:
148
149           Cyphertext
150               Cyphertext of arbitrary length.
151
152           Key Private key, a Crypt::RSA::Key::Private(3) or compatible
153               object.
154
155           Armour
156               Boolean parameter that specifies whether the Cyphertext is
157               encoded with a post processor.
158
159       sign()
160           sign() creates an RSA signature on a string with a private key
161           using the signature scheme bound to the object. The default scheme
162           is PSS. sign() returns a signature on success and undef on failure.
163           It takes a hash as argument with following keys:
164
165           Message
166               A string of arbitrary length to be signed.
167
168           Key Private key of the sender, a Crypt::RSA::Key::Private(3) or
169               compatible object.
170
171           Armour
172               A boolean parameter that forces the computed signature to be
173               post processed.
174
175       verify()
176           verify() verifies an RSA signature with a public key using the
177           signature scheme bound to the object. The default scheme is PSS.
178           verify() returns a true value on success and undef on failure. It
179           takes a hash as argument with following keys:
180
181           Message
182               A signed message, a string of arbitrary length.
183
184           Key Public key of the signer, a Crypt::RSA::Key::Public(3) or
185               compatible object.
186
187           Sign
188               A signature computed with sign().
189
190           Armour
191               Boolean parameter that specifies whether the Signature has been
192               post processed.
193

MODULES

195       Apart from Crypt::RSA, the following modules are intended for
196       application developer and end-user consumption:
197
198       Crypt::RSA::Key
199           RSA key pair generator.
200
201       Crypt::RSA::Key::Public
202           RSA Public Key Management.
203
204       Crypt::RSA::Key::Private
205           RSA Private Key Management.
206
207       Crypt::RSA::ES::OAEP
208           Plaintext-aware encryption with RSA.
209
210       Crypt::RSA::SS::PSS
211           Probabilistic Signature Scheme based on RSA.
212
213       Crypt::RSA::ES::PKCS1v15
214           PKCS #1 v1.5 encryption scheme.
215
216       Crypt::RSA::SS::PKCS1v15
217           PKCS #1 v1.5 signature scheme.
218

CUSTOMISING A CRYPT::RSA OBJECT

220       A Crypt::RSA object can be customized by passing any of the following
221       keys in a hash to new(): ES to specify the encryption scheme, SS to
222       specify the signature scheme, PP to specify the post processor, and KF
223       to specify the key format. The value associated with these keys can
224       either be a name (a string) or a hash reference that specifies a module
225       name, its constructor, and constructor arguments. For example:
226
227           my $rsa = new Crypt::RSA ( ES => 'OAEP' );
228
229                           or
230
231           my $rsa = new Crypt::RSA ( ES => { Module => 'Crypt::RSA::ES::OAEP' } );
232
233       A module thus specified need not be included in the Crypt::RSA bundle,
234       but it must be interface compatible with the ones provided with
235       Crypt::RSA.
236
237       As of this writing, the following names are recognised:
238
239       ES (Encryption Scheme)
240               'OAEP', 'PKCS1v15'
241
242       SS (Signature Scheme)
243               'PSS', 'PKCS1v15'
244
245       KF (Key Format)
246               'Native', 'SSH'
247
248       PP (Post Processor)
249               'ASCII'
250

ERROR HANDLING

252       All modules in the Crypt::RSA bundle use a common error handling method
253       (implemented in Crypt::RSA::Errorhandler(3)). When a method fails it
254       returns undef and calls $self->error() with the error message. This
255       error message is available to the caller through the errstr() method.
256       For more details see the Crypt::RSA::Errorhandler(3) manpage.
257

AUTHOR

259       Vipul Ved Prakash, <mail@vipul.net>
260

ACKNOWLEDGEMENTS

262       Thanks to Ilya Zakharevich for help with Math::Pari, Benjamin Trott for
263       several patches including SSH key support, Genèche Ramanoudjame for
264       extensive testing and numerous bug reports, Shizukesa on #perl for
265       suggesting the error handling method used in this module, and Dave
266       Paris for good advice.
267

LICENSE

269       Copyright (c) 2000-2008, Vipul Ved Prakash. This code is free software;
270       it is distributed under the same license as Perl itself.
271
272       I have received requests for commercial licenses of Crypt::RSA, from
273       those who desire contractual support and indemnification. I'd be happy
274       to provide a commercial license if you need one. Please send me mail at
275       "mail@vipul.net" with the subject "Crypt::RSA license". Please don't
276       send me mail asking if you need a commercial license. You don't, if
277       Artistic of GPL suit you fine.
278

SEE ALSO

280       Crypt::RSA::Primitives(3), Crypt::RSA::DataFormat(3),
281       Crypt::RSA::Errorhandler(3), Crypt::RSA::Debug(3), Crypt::Primes(3),
282       Crypt::Random(3), Crypt::CBC(3), Crypt::Blowfish(3),
283       Tie::EncryptedHash(3), Convert::ASCII::Armour(3), Math::Pari(3),
284       Class::Loader(3), crypt-rsa-interoperability(3),
285       crypt-rsa-interoperability-table(3).
286

REPORTING BUGS

288       All bug reports related to Crypt::RSA should go to rt.cpan.org at
289       "http://rt.cpan.org/Dist/Display.html?Queue=Crypt-RSA"
290
291       Crypt::RSA is considered to be stable. If you are running into a
292       problem, it's likely of your own making. Please check your code and
293       consult the documentation before posting a bug report. A google search
294       with the error message might also shed light if it is a common mistake
295       that you've made.
296
297       If the module installation fails with a "Segmentation Fault" or "Bus
298       Error", it is likely a Math::Pari issue. Please consult Math::Pari bugs
299       on rt.cpan.org or open a bug there. There have been known issues on HP-
300       UX and SunOS systems (with Math::Pari), so if you are on those OSes,
301       please consult Math::Pari resources before opening a Crypt::RSA bug.
302

BIBLIOGRAPHY

304       Chronologically sorted (for the most part).
305
306       1 R. Rivest, A. Shamir, L. Aldeman. A Method for Obtaining Digital
307       Signatures and Public-Key Cryptosystems (1978).
308       2 U. Maurer. Fast Generation of Prime Numbers and Secure Public-Key
309       Cryptographic Parameters (1994).
310       3 M. Bellare, P. Rogaway. Optimal Asymmetric Encryption - How to
311       Encrypt with RSA (1995).
312       4 M. Bellare, P. Rogaway. The Exact Security of Digital Signatures -
313       How to sign with RSA and Rabin (1996).
314       5 B. Schneier. Applied Cryptography, Second Edition (1996).
315       6 A. Menezes, P. Oorschot, S. Vanstone. Handbook of Applied
316       Cryptography (1997).
317       7 D. Boneh. Twenty Years of Attacks on the RSA Cryptosystem (1998).
318       8 D. Bleichenbacher, M. Joye, J. Quisquater. A New and Optimal Chosen-
319       message Attack on RSA-type Cryptosystems (1998).
320       9 B. Kaliski, J. Staddon. Recent Results on PKCS #1: RSA Encryption
321       Standard, RSA Labs Bulletin Number 7 (1998).
322       10 B. Kaliski, J. Staddon. PKCS #1: RSA Cryptography Specifications
323       v2.0, RFC 2437 (1998).
324       11 SSH Communications Security. SSH 1.2.7 source code (1998).
325       12 S. Simpson. PGP DH vs. RSA FAQ v1.5 (1999).
326       13 RSA Laboratories. Draft I, PKCS #1 v2.1: RSA Cryptography Standard
327       (1999).
328       14 E. Young, T. Hudson, OpenSSL Team. OpenSSL 0.9.5a source code
329       (2000).
330       15 Several Authors. The sci.crypt FAQ at
331       http://www.faqs.org/faqs/cryptography-faq/part01/index.html
332       16 Victor Shoup. A Proposal for an ISO Standard for Public Key
333       Encryption (2001).
334

POD ERRORS

336       Hey! The above document had some coding errors, which are explained
337       below:
338
339       Around line 533:
340           Non-ASCII character seen before =encoding in 'Genèche'. Assuming
341           UTF-8
342
343       Around line 582:
344           =over without closing =back
345
346
347
348perl v5.34.0                      2021-07-22                     Crypt::RSA(3)
Impressum