1Crypt::RSA(3) User Contributed Perl Documentation Crypt::RSA(3)
2
6 Crypt::RSA - RSA public-key cryptosystem.
7
9 $Revision: 1.48 $ (Beta)
10 $Date: 2001/09/25 12:44:55 $
11
13 my $rsa = new Crypt::RSA;
14 my ($public, $private) =
16 $rsa->keygen (
17 Identity => 'Lord Macbeth <macbeth@glamis.com>',
18 Size => 1024,
19 Password => 'A day so foul & fair',
20 Verbosity => 1,
21 ) or die $rsa->errstr();
22 my $cyphertext =
24 $rsa->encrypt (
25 Message => $message,
26 Key => $public,
27 Armour => 1,
28 ) ⎪⎪ die $rsa->errstr();
29 my $plaintext =
31 $rsa->decrypt (
32 Cyphertext => $cyphertext,
33 Key => $private,
34 Armour => 1,
35 ) ⎪⎪ die $rsa->errstr();
36 my $signature =
38 $rsa->sign (
39 Message => $message,
40 Key => $private
41 ) ⎪⎪ die $rsa->errstr();
42 my $verify =
44 $rsa->verify (
45 Message => $message,
46 Signature => $signature,
47 Key => $public
48 ) ⎪⎪ die $rsa->errstr();
49
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
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 blaz‐
59 ingly fast PARI library, for big integer arithmetic and number theo‐
60 retic computations.
61 Crypt::RSA provides arbitrary size key-pair generation, plaintext-aware
63 encryption (OAEP) and digital signatures with appendix (PSS). For com‐
64 patibility with SSLv3, RSAREF2, PGP and other applications that follow
65 the PKCS #1 v1.5 standard, it also provides PKCS #1 v1.5 encryption and
66 signatures.
67 Crypt::RSA is structured as bundle of modules that encapsulate differ‐
69 ent parts of the RSA cryptosystem. The RSA algorithm is implemented in
70 Crypt::RSA::Primitives(3). Encryption schemes, located under
71 Crypt::RSA::ES, and signature schemes, located under Crypt::RSA::SS,
72 use the RSA algorithm to build encryption/signature schemes that employ
73 secure padding. (See the note on Security of Padding Schemes.)
74 The key generation engine and other functions that work on both compo‐
76 nents of the key-pair are encapsulated in Crypt::RSA::Key(3).
77 Crypt::RSA::Key::Public(3) & Crypt::RSA::Key::Private(3) provide mecha‐
78 nisms for storage & retrival of keys from disk, decoding & encoding of
79 keys in certain formats, and secure representation of keys in memory.
80 Finally, the Crypt::RSA module provides a convenient, DWIM wrapper
81 around the rest of the modules in the bundle.
82
84 It has been conclusively shown that textbook RSA is insecure[3,7].
85 Secure RSA requires that plaintext is padded in a specific manner
86 before encryption and signing. There are four main standards for pad‐
87 ding: PKCS #1 v1.5 encryption & signatures, and OAEP encryption & PSS
88 signatures. Crypt::RSA implements these as four modules that provide
89 overloaded encrypt(), decrypt(), sign() and verify() methods that add
90 padding functionality to the basic RSA operations.
91 Crypt::RSA::ES::PKCS1v15(3) implements PKCS #1 v1.5 encryption,
93 Crypt::RSA::SS::PKCS1v15(3) implements PKCS #1 v1.5 signatures,
94 Crypt::RSA::ES::OAEP(3) implements Optimal Asymmetric Encryption and
95 Crypt::RSA::SS::PSS(3) Probabilistic Signatures.
96 PKCS #1 v1.5 schemes are older and hence more widely deployed, but PKCS
98 #1 v1.5 encryption has certain flaws that make it vulnerable to chosen-
99 cyphertext attacks[9]. Even though Crypt::RSA works around these vul‐
100 nerabilities, it is recommended that new applications use OAEP and PSS,
101 both of which are provably secure[13]. In any event, Crypt::RSA::Primi‐
102 tives (without padding) should never be used directly.
103 That said, there exists a scheme called Simple RSA[16] that provides
105 security without padding. However, Crypt::RSA doesn't implement this
106 scheme yet.
107
109 new()
110 The constructor. When no arguments are provided, new() returns an
111 object loaded with default values. This object can be customized by
112 specifying encryption & signature schemes, key formats and post
113 processors. For details see the section on Customizing the
114 Crypt::RSA object later in this manpage.
115 keygen()
117 keygen() generates and returns an RSA key-pair of specified bit‐
118 size. keygen() is a synonym for Crypt::RSA::Key::generate().
119 Parameters and return values are described in the
120 Crypt::RSA::Key(3) manpage.
121 encrypt()
123 encrypt() performs RSA encryption on a string of arbitrary length
124 with a public key using the encryption scheme bound to the object.
125 The default scheme is OAEP. encrypt() returns cyphertext (a string)
126 on success and undef on failure. It takes a hash as argument with
127 following keys:
128 Message
130 An arbitrary length string to be encrypted.
131 Key Public key of the recipient, a Crypt::RSA::Key::Public(3) or
133 compatible object.
134 Armour
136 A boolean parameter that forces cyphertext through a post pro‐
137 cessor after encrpytion. The default post processor is Con‐
138 vert::ASCII::Armour(3) that encodes binary octets in 6-bit
139 clean ASCII messages. The cyphertext is returned as-is, when
140 the Armour key is not present.
141 decrypt()
143 decrypt() performs RSA decryption with a private key using the
144 encryption scheme bound to the object. The default scheme is OAEP.
145 decrypt() returns plaintext on success and undef on failure. It
146 takes a hash as argument with following keys:
147 Cyphertext
149 Cyphertext of arbitrary length.
150 Key Private key, a Crypt::RSA::Key::Private(3) or compatible
152 object.
153 Armour
155 Boolean parameter that specifies whether the Cyphertext is
156 encoded with a post processor.
157 sign()
159 sign() creates an RSA signature on a string with a private key
160 using the signature scheme bound to the object. The default scheme
161 is PSS. sign() returns a signature on success and undef on failure.
162 It takes a hash as argument with following keys:
163 Message
165 A string of arbitrary length to be signed.
166 Key Private key of the sender, a Crypt::RSA::Key::Private(3) or
168 compatible object.
169 Armour
171 A boolean parameter that forces the computed signature to be
172 post processed.
173 verify()
175 verify() verifies an RSA signature with a public key using the sig‐
176 nature scheme bound to the object. The default scheme is PSS. ver‐
177 ify() returns a true value on success and undef on failure. It
178 takes a hash as argument with following keys:
179 Message
181 A signed message, a string of arbitrary length.
182 Key Public key of the signer, a Crypt::RSA::Key::Public(3) or com‐
184 patible object.
185 Sign
187 A signature computed with sign().
188 Armour
190 Boolean parameter that specifies whether the Signature has been
191 post processed.
192
194 Apart from Crypt::RSA, the following modules are intended for applica‐
195 tion developer and end-user consumption:
196 Crypt::RSA::Key
198 RSA key pair generator.
199 Crypt::RSA::Key::Public
201 RSA Public Key Management.
202 Crypt::RSA::Key::Private
204 RSA Private Key Management.
205 Crypt::RSA::ES::OAEP
207 Plaintext-aware encryption with RSA.
208 Crypt::RSA::SS::PSS
210 Probabilistic Signature Scheme based on RSA.
211 Crypt::RSA::ES::PKCS1v15
213 PKCS #1 v1.5 encryption scheme.
214 Crypt::RSA::SS::PKCS1v15
216 PKCS #1 v1.5 signature scheme.
217
219 A Crypt::RSA object can be customized by passing any of the following
220 keys in a hash to new(): ES to specify the encryption scheme, SS to
221 specify the signature scheme, PP to specify the post processor, and KF
222 to specify the key format. The value associated with these keys can
223 either be a name (a string) or a hash reference that specifies a module
224 name, its constructor, and constructor arguments. For example:
225 my $rsa = new Crypt::RSA ( ES => 'OAEP' );
227 or
229 my $rsa = new Crypt::RSA ( ES => { Module => 'Crypt::RSA::ES::OAEP' } );
231 A module thus specified need not be included in the Crypt::RSA bundle,
233 but it must be interface compatible with the ones provided with
234 Crypt::RSA.
235 As of this writing, the following names are recognised:
237 ES (Encryption Scheme)
239 'OAEP', 'PKCS1v15'
240 SS (Signature Scheme)
242 'PSS', 'PKCS1v15'
243 KF (Key Format)
245 'Native', 'SSH'
246 PP (Post Processor)
248 'ASCII'
249
251 All modules in the Crypt::RSA bundle use a common error handling method
252 (implemented in Crypt::RSA::Errorhandler(3)). When a method fails it
253 returns undef and calls $self->error() with the error message. This
254 error message is available to the caller through the errstr() method.
255 For more details see the Crypt::RSA::Errorhandler(3) manpage.
256
258 Vipul Ved Prakash, <mail@vipul.net>
259
261 Thanks to Ilya Zakharevich for help with Math::Pari, Benjamin Trott for
262 several patches including SSH key support, Genèche Ramanoudjame for
263 extensive testing and numerous bug reports, Shizukesa on #perl for sug‐
264 gesting the error handling method used in this module, and Dave Paris
265 for good advice.
266
268 Copyright (c) 2000-2005, Vipul Ved Prakash. All rights reserved. This
269 code is free software; it is distributed under a disjunctive Artis‐
270 tic/GPL license, like Perl itself.
271 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
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), Tie::Encrypted‐
283 Hash(3), Convert::ASCII::Armour(3), Math::Pari(3), Class::Loader(3),
284 crypt-rsa-interoperability(3), crypt-rsa-interoperability-table(3).
285
287 All bug reports related to Crypt::RSA should go to rt.cpan.org at
288 "http://rt.cpan.org/Dist/Display.html?Queue=Crypt-RSA"
289 Crypt::RSA is considered to be stable. If you are running into a prob‐
291 lem, it's likely of your own making. Please check your code and consult
292 the documentation before posting a bug report. A google search with the
293 error message might also shed light if it is a common mistake that
294 you've made.
295 If the module installation fails with a "Segmentation Fault" or "Bus
297 Error", it is likely a Math::Pari issue. Please consult Math::Pari bugs
298 on rt.cpan.org or open a bug there. There have been known issues on HP-
299 UX and SunOS systems (with Math::Pari), so if you are on those OSes,
300 please consult Math::Pari resources before opening a Crypt::RSA bug.
301
303 Chronologically sorted (for the most part).
304 1 R. Rivest, A. Shamir, L. Aldeman. A Method for Obtaining Digital Sig‐
306 natures and Public-Key Cryptosystems (1978).
307 2 U. Maurer. Fast Generation of Prime Numbers and Secure Public-Key
308 Cryptographic Parameters (1994).
309 3 M. Bellare, P. Rogaway. Optimal Asymmetric Encryption - How to
310 Encrypt with RSA (1995).
311 4 M. Bellare, P. Rogaway. The Exact Security of Digital Signatures -
312 How to sign with RSA and Rabin (1996).
313 5 B. Schneier. Applied Cryptography, Second Edition (1996).
314 6 A. Menezes, P. Oorschot, S. Vanstone. Handbook of Applied Cryptogra‐
315 phy (1997).
316 7 D. Boneh. Twenty Years of Attacks on the RSA Cryptosystem (1998).
317 8 D. Bleichenbacher, M. Joye, J. Quisquater. A New and Optimal Chosen-
318 message Attack on RSA-type Cryptosystems (1998).
319 9 B. Kaliski, J. Staddon. Recent Results on PKCS #1: RSA Encryption
320 Standard, RSA Labs Bulletin Number 7 (1998).
321 10 B. Kaliski, J. Staddon. PKCS #1: RSA Cryptography Specifications
322 v2.0, RFC 2437 (1998).
323 11 SSH Communications Security. SSH 1.2.7 source code (1998).
324 12 S. Simpson. PGP DH vs. RSA FAQ v1.5 (1999).
325 13 RSA Laboratories. Draft I, PKCS #1 v2.1: RSA Cryptography Standard
326 (1999).
327 14 E. Young, T. Hudson, OpenSSL Team. OpenSSL 0.9.5a source code
328 (2000).
329 15 Several Authors. The sci.crypt FAQ at http://www.faqs.org/faqs/cryp‐
330 tography-faq/part01/index.html
331 16 Victor Shoup. A Proposal for an ISO Standard for Public Key Encryp‐
332 tion (2001).
333perl v5.8.8 2007-04-17 Crypt::RSA(3)