Crypt::OpenSSL::RSA(3pm)

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

NAME

6       Crypt::OpenSSL::RSA - RSA encoding and decoding, using the openSSL
7       libraries
8

SYNOPSIS

10         use Crypt::OpenSSL::Random;
11         use Crypt::OpenSSL::RSA;
12
13         # not necessary if we have /dev/random:
14         Crypt::OpenSSL::Random::random_seed($good_entropy);
15         Crypt::OpenSSL::RSA->import_random_seed();
16         $rsa_pub = Crypt::OpenSSL::RSA->new_public_key($key_string);
17         $ciphertext = $rsa->encrypt($plaintext);
18
19         $rsa_priv = Crypt::OpenSSL::RSA->new_private_key($key_string);
20         $plaintext = $rsa->encrypt($ciphertext);
21
22         $rsa = Crypt::OpenSSL::RSA->generate_key(1024); # or
23         $rsa = Crypt::OpenSSL::RSA->generate_key(1024, $prime);
24
25         print "private key is:\n", $rsa->get_private_key_string();
26         print "public key (in PKCS1 format) is:\n",
27               $rsa->get_public_key_string();
28         print "public key (in X509 format) is:\n",
29               $rsa->get_public_key_x509_string();
30
31         $rsa_priv->use_md5_hash(); # insecure. use_sha256_hash or use_sha1_hash are the default
32         $signature = $rsa_priv->sign($plaintext);
33         print "Signed correctly\n" if ($rsa->verify($plaintext, $signature));
34

DESCRIPTION

36       "Crypt::OpenSSL::RSA" provides the ability to RSA encrypt strings which
37       are somewhat shorter than the block size of a key.  It also allows for
38       decryption, signatures and signature verification.
39
40       NOTE: Many of the methods in this package can croak, so use "eval", or
41       Error.pm's try/catch mechanism to capture errors.  Also, while some
42       methods from earlier versions of this package return true on success,
43       this (never documented) behavior is no longer the case.
44

Class Methods

46       new_public_key
47           Create a new "Crypt::OpenSSL::RSA" object by loading a public key
48           in from a string containing Base64/DER-encoding of either the PKCS1
49           or X.509 representation of the key.  The string should include the
50           "-----BEGIN...-----" and "-----END...-----" lines.
51
52           The padding is set to PKCS1_OAEP, but can be changed with the
53           "use_xxx_padding" methods.
54
55       new_private_key
56           Create a new "Crypt::OpenSSL::RSA" object by loading a private key
57           in from an string containing the Base64/DER encoding of the PKCS1
58           representation of the key.  The string should include the
59           "-----BEGIN...-----" and "-----END...-----" lines.  The padding is
60           set to PKCS1_OAEP, but can be changed with "use_xxx_padding".
61
62       generate_key
63           Create a new "Crypt::OpenSSL::RSA" object by constructing a
64           private/public key pair.  The first (mandatory) argument is the key
65           size, while the second optional argument specifies the public
66           exponent (the default public exponent is 65537).  The padding is
67           set to "PKCS1_OAEP", but can be changed with use_xxx_padding
68           methods.
69
70       new_key_from_parameters
71           Given Crypt::OpenSSL::Bignum objects for n, e, and optionally d, p,
72           and q, where p and q are the prime factors of n, e is the public
73           exponent and d is the private exponent, create a new
74           Crypt::OpenSSL::RSA object using these values.  If p and q are
75           provided and d is undef, d is computed.  Note that while p and q
76           are not necessary for a private key, their presence will speed up
77           computation.
78
79       import_random_seed
80           Import a random seed from Crypt::OpenSSL::Random, since the OpenSSL
81           libraries won't allow sharing of random structures across perl XS
82           modules.
83

Instance Methods

85       DESTROY
86           Clean up after ourselves.  In particular, erase and free the memory
87           occupied by the RSA key structure.
88
89       get_public_key_string
90           Return the Base64/DER-encoded PKCS1 representation of the public
91           key.  This string has header and footer lines:
92
93             -----BEGIN RSA PUBLIC KEY------
94             -----END RSA PUBLIC KEY------
95
96       get_public_key_x509_string
97           Return the Base64/DER-encoded representation of the "subject public
98           key", suitable for use in X509 certificates.  This string has
99           header and footer lines:
100
101             -----BEGIN PUBLIC KEY------
102             -----END PUBLIC KEY------
103
104           and is the format that is produced by running "openssl rsa
105           -pubout".
106
107       get_private_key_string
108           Return the Base64/DER-encoded PKCS1 representation of the private
109           key.  This string has header and footer lines:
110
111             -----BEGIN RSA PRIVATE KEY------
112             -----END RSA PRIVATE KEY------
113
114       encrypt
115           Encrypt a binary "string" using the public (portion of the) key.
116
117       decrypt
118           Decrypt a binary "string".  Croaks if the key is public only.
119
120       private_encrypt
121           Encrypt a binary "string" using the private key.  Croaks if the key
122           is public only.
123
124       public_decrypt
125           Decrypt a binary "string" using the public (portion of the) key.
126
127       sign
128           Sign a string using the secret (portion of the) key.
129
130       verify
131           Check the signature on a text.
132
133       use_no_padding
134           Use raw RSA encryption. This mode should only be used to implement
135           cryptographically sound padding modes in the application code.
136           Encrypting user data directly with RSA is insecure.
137
138       use_pkcs1_padding
139           Use PKCS #1 v1.5 padding. This currently is the most widely used
140           mode of padding.
141
142       use_pkcs1_oaep_padding
143           Use "EME-OAEP" padding as defined in PKCS #1 v2.0 with SHA-1, MGF1
144           and an empty encoding parameter. This mode of padding is
145           recommended for all new applications.  It is the default mode used
146           by "Crypt::OpenSSL::RSA".
147
148       use_sslv23_padding
149           Use "PKCS #1 v1.5" padding with an SSL-specific modification that
150           denotes that the server is SSL3 capable.
151
152           Not available since OpenSSL 3.
153
154       use_md5_hash
155           Use the RFC 1321 MD5 hashing algorithm by Ron Rivest when signing
156           and verifying messages.
157
158           Note that this is considered insecure.
159
160       use_sha1_hash
161           Use the RFC 3174 Secure Hashing Algorithm (FIPS 180-1) when signing
162           and verifying messages. This is the default, when use_sha256_hash
163           is not available.
164
165       use_sha224_hash, use_sha256_hash, use_sha384_hash, use_sha512_hash
166           These FIPS 180-2 hash algorithms, for use when signing and
167           verifying messages, are only available with newer openssl versions
168           (>= 0.9.8).
169
170           use_sha256_hash is the default hash mode when available.
171
172       use_ripemd160_hash
173           Dobbertin, Bosselaers and Preneel's RIPEMD hashing algorithm when
174           signing and verifying messages.
175
176       use_whirlpool_hash
177           Vincent Rijmen und Paulo S. L. M. Barreto ISO/IEC 10118-3:2004
178           WHIRLPOOL hashing algorithm when signing and verifying messages.
179
180       size
181           Returns the size, in bytes, of the key.  All encrypted text will be
182           of this size, and depending on the padding mode used, the length of
183           the text to be encrypted should be:
184
185           pkcs1_oaep_padding
186               at most 42 bytes less than this size.
187
188           pkcs1_padding or sslv23_padding
189               at most 11 bytes less than this size.
190
191           no_padding
192               exactly this size.
193
194       check_key
195           This function validates the RSA key, returning a true value if the
196           key is valid, and a false value otherwise.  Croaks if the key is
197           public only.
198
199       get_key_parameters
200           Return "Crypt::OpenSSL::Bignum" objects representing the values of
201           "n", "e", "d", "p", "q", "d mod (p-1)", "d mod (q-1)", and "1/q mod
202           p", where "p" and "q" are the prime factors of "n", "e" is the
203           public exponent and "d" is the private exponent.  Some of these
204           values may return as "undef"; only "n" and "e" will be defined for
205           a public key.  The "Crypt::OpenSSL::Bignum" module must be
206           installed for this to work.
207
208       is_private
209           Return true if this is a private key, and false if it is private
210           only.
211

BUGS

213       There is a small memory leak when generating new keys of more than 512
214       bits.
215

AUTHOR

217       Ian Robertson, "iroberts@cpan.org".  For support, please email
218       "perl-openssl-users@lists.sourceforge.net".
219

ACKNOWLEDGEMENTS

LICENSE

222       Copyright (c) 2001-2011 Ian Robertson.  Crypt::OpenSSL::RSA is free
223       software; you may redistribute it and/or modify it under the same terms
224       as Perl itself.
225