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         $rsa_pub->use_sslv23_padding(); # use_pkcs1_oaep_padding is the default
18         $ciphertext = $rsa->encrypt($plaintext);
19
20         $rsa_priv = Crypt::OpenSSL::RSA->new_private_key($key_string);
21         $plaintext = $rsa->encrypt($ciphertext);
22
23         $rsa = Crypt::OpenSSL::RSA->generate_key(1024); # or
24         $rsa = Crypt::OpenSSL::RSA->generate_key(1024, $prime);
25
26         print "private key is:\n", $rsa->get_private_key_string();
27         print "public key (in PKCS1 format) is:\n",
28               $rsa->get_public_key_string();
29         print "public key (in X509 format) is:\n",
30               $rsa->get_public_key_x509_string();
31
32         $rsa_priv->use_md5_hash(); # insecure. use_sha256_hash or use_sha1_hash are the default
33         $signature = $rsa_priv->sign($plaintext);
34         print "Signed correctly\n" if ($rsa->verify($plaintext, $signature));
35

DESCRIPTION

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

Class Methods

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

Instance Methods

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

BUGS

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

AUTHOR

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

ACKNOWLEDGEMENTS

LICENSE

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