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           An optional parameter can be passed for passphase protected private
63           key:
64
65           passphase
66               The passphase which protects the private key.
67
68       generate_key
69           Create a new "Crypt::OpenSSL::RSA" object by constructing a
70           private/public key pair.  The first (mandatory) argument is the key
71           size, while the second optional argument specifies the public
72           exponent (the default public exponent is 65537).  The padding is
73           set to "PKCS1_OAEP", but can be changed with use_xxx_padding
74           methods.
75
76       new_key_from_parameters
77           Given Crypt::OpenSSL::Bignum objects for n, e, and optionally d, p,
78           and q, where p and q are the prime factors of n, e is the public
79           exponent and d is the private exponent, create a new
80           Crypt::OpenSSL::RSA object using these values.  If p and q are
81           provided and d is undef, d is computed.  Note that while p and q
82           are not necessary for a private key, their presence will speed up
83           computation.
84
85       import_random_seed
86           Import a random seed from Crypt::OpenSSL::Random, since the OpenSSL
87           libraries won't allow sharing of random structures across perl XS
88           modules.
89

Instance Methods

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

BUGS

229       There is a small memory leak when generating new keys of more than 512
230       bits.
231

AUTHOR

233       Ian Robertson, "iroberts@cpan.org".  For support, please email
234       "perl-openssl-users@lists.sourceforge.net".
235

ACKNOWLEDGEMENTS

LICENSE

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