1Crypt::RSA(3) User Contributed Perl Documentation Crypt::RSA(3)
2
6 Crypt::RSA - RSA public-key cryptosystem.
7
9 my $rsa = new Crypt::RSA;
10 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 my $cyphertext =
21 $rsa->encrypt (
22 Message => $message,
23 Key => $public,
24 Armour => 1,
25 ) || die $rsa->errstr();
26 my $plaintext =
29 $rsa->decrypt (
30 Cyphertext => $cyphertext,
31 Key => $private,
32 Armour => 1,
33 ) || die $rsa->errstr();
34 my $signature =
37 $rsa->sign (
38 Message => $message,
39 Key => $private
40 ) || die $rsa->errstr();
41 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
59 blazingly fast PARI library, for big integer arithmetic and number
60 theoretic computations.
61 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 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 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
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 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 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 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
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 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 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 Message
131 An arbitrary length string to be encrypted.
132 Key Public key of the recipient, a Crypt::RSA::Key::Public(3) or
134 compatible object.
135 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 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 Cyphertext
150 Cyphertext of arbitrary length.
151 Key Private key, a Crypt::RSA::Key::Private(3) or compatible
153 object.
154 Armour
156 Boolean parameter that specifies whether the Cyphertext is
157 encoded with a post processor.
158 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 Message
166 A string of arbitrary length to be signed.
167 Key Private key of the sender, a Crypt::RSA::Key::Private(3) or
169 compatible object.
170 Armour
172 A boolean parameter that forces the computed signature to be
173 post processed.
174 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 Message
182 A signed message, a string of arbitrary length.
183 Key Public key of the signer, a Crypt::RSA::Key::Public(3) or
185 compatible object.
186 Sign
188 A signature computed with sign().
189 Armour
191 Boolean parameter that specifies whether the Signature has been
192 post processed.
193
195 Apart from Crypt::RSA, the following modules are intended for
196 application developer and end-user consumption:
197 Crypt::RSA::Key
199 RSA key pair generator.
200 Crypt::RSA::Key::Public
202 RSA Public Key Management.
203 Crypt::RSA::Key::Private
205 RSA Private Key Management.
206 Crypt::RSA::ES::OAEP
208 Plaintext-aware encryption with RSA.
209 Crypt::RSA::SS::PSS
211 Probabilistic Signature Scheme based on RSA.
212 Crypt::RSA::ES::PKCS1v15
214 PKCS #1 v1.5 encryption scheme.
215 Crypt::RSA::SS::PKCS1v15
217 PKCS #1 v1.5 signature scheme.
218
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 my $rsa = new Crypt::RSA ( ES => 'OAEP' );
228 or
230 my $rsa = new Crypt::RSA ( ES => { Module => 'Crypt::RSA::ES::OAEP' } );
232 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 As of this writing, the following names are recognised:
238 ES (Encryption Scheme)
240 'OAEP', 'PKCS1v15'
241 SS (Signature Scheme)
243 'PSS', 'PKCS1v15'
244 KF (Key Format)
246 'Native', 'SSH'
247 PP (Post Processor)
249 'ASCII'
250
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
259 Vipul Ved Prakash, <mail@vipul.net>
260
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
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 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),
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
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 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 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
304 Chronologically sorted (for the most part).
305 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
336 Hey! The above document had some coding errors, which are explained
337 below:
338 Around line 533:
340 Non-ASCII character seen before =encoding in 'Genèche'. Assuming
341 UTF-8
342 Around line 582:
344 =over without closing =back
345perl v5.34.0 2022-01-21 Crypt::RSA(3)