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(); # use_sha1_hash is 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 in
49           from a string containing Base64/DER-encoding of either the PKCS1 or
50           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 in
58           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 set
61           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 (mandetory) 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 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 DER-encoded PKCS1 representation of the private key.
109
110       encrypt
111           Encrypt a binary "string" using the public (portion of the) key.
112
113       decrypt
114           Decrypt a binary "string".  Croaks if the key is public only.
115
116       private_encrypt
117           Encrypt a binary "string" using the private key.  Croaks if the key
118           is public only.
119
120       public_decrypt
121           Decrypt a binary "string" using the public (portion of the) key.
122
123       sign
124           Sign a string using the secret (portion of the) key.
125
126       verify
127           Check the signature on a text.
128
129       use_no_padding
130           Use raw RSA encryption. This mode should only be used to implement
131           cryptographically sound padding modes in the application code.
132           Encrypting user data directly with RSA is insecure.
133
134       use_pkcs1_padding
135           Use PKCS #1 v1.5 padding. This currently is the most widely used
136           mode of padding.
137
138       use_pkcs1_oaep_padding
139           Use EME-OAEP padding as defined in PKCS #1 v2.0 with SHA-1, MGF1
140           and an empty encoding parameter. This mode of padding is
141           recommended for all new applications.  It is the default mode used
142           by Crypt::OpenSSL::RSA.
143
144       use_sslv23_padding
145           Use PKCS #1 v1.5 padding with an SSL-specific modification that
146           denotes that the server is SSL3 capable.
147
148       use_md5_hash
149           Use the RFC 1321 MD5 hashing algorithm by Ron Rivest when signing
150           and verifying messages.
151
152       use_sha1_hash
153           Use the RFC 3174 Secure Hashing Algorithm (FIPS 180-1) when signing
154           and verifying messages. This is the default.
155
156       use_sha224_hash, use_sha256_hash, use_sha384_hash, use_sha512_hash
157           These FIPS 180-2 hash algorithms, for use when signing and
158           verifying messages, are only available with newer openssl versions
159           (>= 0.9.8).
160
161       use_ripemd160_hash
162           Dobbertin, Bosselaers and Preneel's RIPEMD hashing algorithm when
163           signing and verifying messages.
164
165       size
166           Returns the size, in bytes, of the key.  All encrypted text will be
167           of this size, and depending on the padding mode used, the length of
168           the text to be encrypted should be:
169
170           pkcs1_oaep_padding
171               at most 42 bytes less than this size.
172
173           pkcs1_padding or sslv23_padding
174               at most 11 bytes less than this size.
175
176           no_padding
177               exactly this size.
178
179       check_key
180           This function validates the RSA key, returning a true value if the
181           key is valid, and a false value otherwise.  Croaks if the key is
182           public only.
183
184       get_key_parameters
185           Return Crypt::OpenSSL::Bignum objects representing the values of n,
186           e, d, p, q, d mod (p-1), d mod (q-1), and 1/q mod p, where p and q
187           are the prime factors of n, e is the public exponent and d is the
188           private exponent.  Some of these values may return as undef; only n
189           and e will be defined for a public key.  The Crypt::OpenSSL::Bignum
190           module must be installed for this to work.
191
192       is_private
193           Return true if this is a private key, and false if it is private
194           only.
195

BUGS

197       There is a small memory leak when generating new keys of more than 512
198       bits.
199

AUTHOR

201       Ian Robertson, iroberts@cpan.org.  For support, please email
202       perl-openssl-users@lists.sourceforge.net.
203