1SSLeay(3) User Contributed Perl Documentation SSLeay(3)
2
3
4
6 Crypt::SSLeay - OpenSSL support for LWP
7
9 lwp-request https://www.example.com
10
11 use LWP::UserAgent;
12 my $ua = LWP::UserAgent->new;
13 my $response = $ua->get('https://www.example.com/');
14 print $response->content, "\n";
15
17 This Perl module provides support for the HTTPS protocol under LWP, to
18 allow an "LWP::UserAgent" object to perform GET, HEAD and POST
19 requests. Please see LWP for more information on POST requests.
20
21 The "Crypt::SSLeay" package provides "Net::SSL", which is loaded by
22 "LWP::Protocol::https" for https requests and provides the necessary
23 SSL glue.
24
25 This distribution also makes following deprecated modules available:
26
27 Crypt::SSLeay::CTX
28 Crypt::SSLeay::Conn
29 Crypt::SSLeay::X509
30
31 Work on Crypt::SSLeay has been continued only to provide https support
32 for the LWP (libwww-perl) libraries.
33
35 The following environment variables change the way "Crypt::SSLeay" and
36 "Net::SSL" behave.
37
38 # proxy support
39 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
40
41 # proxy_basic_auth
42 $ENV{HTTPS_PROXY_USERNAME} = 'username';
43 $ENV{HTTPS_PROXY_PASSWORD} = 'password';
44
45 # debugging (SSL diagnostics)
46 $ENV{HTTPS_DEBUG} = 1;
47
48 # default ssl version
49 $ENV{HTTPS_VERSION} = '3';
50
51 # client certificate support
52 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
53 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem';
54
55 # CA cert peer verification
56 $ENV{HTTPS_CA_FILE} = 'certs/ca-bundle.crt';
57 $ENV{HTTPS_CA_DIR} = 'certs/';
58
59 # Client PKCS12 cert support
60 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12';
61 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
62
64 OpenSSL
65 You must have OpenSSL or SSLeay installed before compiling this module.
66 You can get the latest OpenSSL package from <http://www.openssl.org/>.
67
68 On Debian systems, you will need to install the "libssl-dev" package,
69 at least for the duration of the build (it may be removed afterwards).
70
71 Other package-based systems may require something similar. The key is
72 that "Crypt::SSLeay" makes calls to the OpenSSL library, and how to do
73 so is specified in the C header files that come with the library. Some
74 systems break out the header files into a separate package from that of
75 the libraries. Once the program has been built, you don't need the
76 headers any more.
77
78 When installing openssl make sure your config looks like:
79
80 ./config --openssldir=/usr/local/openssl
81
82 or
83
84 ./config --openssldir=/usr/local/ssl
85
86 If you are planning on upgrading the default OpenSSL libraries on a
87 system like RedHat, (not recommended), then try something like:
88
89 ./config --openssldir=/usr --shared
90
91 The "--shared" option to config will set up building the .so shared
92 libraries which is important for such systems. This is followed by:
93
94 make
95 make test
96 make install
97
98 This way "Crypt::SSLeay" will pick up the includes and libraries
99 automatically. If your includes end up going into a separate directory
100 like /usr/local/include, then you may need to symlink
101 /usr/local/openssl/include to /usr/local/include
102
103 Crypt::SSLeay
104 The latest Crypt::SSLeay can be found at your nearest CPAN, as well as
105 http://search.cpan.org/dist/Crypt-SSLeay/
106 <http://search.cpan.org/dist/Crypt-SSLeay/>
107
108 Once you have downloaded it, Crypt::SSLeay installs easily using the
109 "make" * commands as shown below.
110
111 perl Makefile.PL
112 make
113 make test
114 make install
115
116 On Windows systems, both Strawberry Perl and ActiveState (as a separate
117 download via ppm) projects include a MingW based compiler distribution
118 and "dmake" which can be used to build both OpenSSL and "Crypt-SSLeay".
119 If you have such a set up, use "dmake" above.
120
121 For unattended (batch) installations, to be absolutely certain that
122 Makefile.PL does not prompt for questions on STDIN, set the following
123 environment variable beforehand:
124
125 PERL_MM_USE_DEFAULT=1
126
127 (This is true for any CPAN module that uses "ExtUtils::MakeMaker").
128
129 To skip live tests, you can use
130
131 perl Makefile.PL --no-live-tests
132
133 and to force live tests, you can use
134
135 perl Makefile.PL --live-tests
136
137 Windows
138
139 "Crypt::SSLeay" builds correctly with Strawberry Perl.
140
141 For ActiveState Perl users, the ActiveState company does not have a
142 permit from the Canadian Federal Government to distribute cryptographic
143 software. This prevents "Crypt::SSLeay" from being distributed as a PPM
144 package from their repository. See
145 http://aspn.activestate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-faq2.html#crypto_packages
146 <http://aspn.activestate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-
147 faq2.html#crypto_packages> for more information on this issue.
148
149 You may download it from Randy Kobes's PPM repository by using the
150 following command:
151
152 ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd
153
154 An alternative is to add the uwinnipeg.ca PPM repository to your local
155 installation. See <http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html> for
156 more details.
157
158 VMS
159
160 It is assumed that the OpenSSL installation is located at /ssl$root.
161 Define this logical to point to the appropriate place in the
162 filesystem.
163
165 LWP::UserAgent and Crypt::SSLeay have their own versions of proxy
166 support. Please read these sections to see which one is appropriate.
167
168 LWP::UserAgent proxy support
169 "LWP::UserAgent" has its own methods of proxying which may work for you
170 and is likely to be incompatible with "Crypt::SSLeay" proxy support.
171 To use "LWP::UserAgent" proxy support, try something like:
172
173 my $ua = LWP::UserAgent->new;
174 $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port");
175
176 At the time of this writing, libwww v5.6 seems to proxy https requests
177 fine with an Apache mod_proxy server. It sends a line like:
178
179 GET https://www.example.com HTTP/1.1
180
181 to the proxy server, which is not the "CONNECT" request that some
182 proxies would expect, so this may not work with other proxy servers
183 than mod_proxy. The "CONNECT" method is used by "Crypt::SSLeay"'s
184 internal proxy support.
185
186 Crypt::SSLeay proxy support
187 For native "Crypt::SSLeay" proxy support of https requests, you need to
188 set the environment variable "HTTPS_PROXY" to your proxy server and
189 port, as in:
190
191 # proxy support
192 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
193 $ENV{HTTPS_PROXY} = '127.0.0.1:8080';
194
195 Use of the "HTTPS_PROXY" environment variable in this way is similar to
196 "LWP::UserAgent-"env_proxy()> usage, but calling that method will
197 likely override or break the "Crypt::SSLeay" support, so do not mix the
198 two.
199
200 Basic auth credentials to the proxy server can be provided this way:
201
202 # proxy_basic_auth
203 $ENV{HTTPS_PROXY_USERNAME} = 'username';
204 $ENV{HTTPS_PROXY_PASSWORD} = 'password';
205
206 For an example of LWP scripting with "Crypt::SSLeay" native proxy
207 support, please look at the eg/lwp-ssl-test script in the
208 "Crypt::SSLeay" distribution.
209
211 Client certificates are supported. PEM encoded certificate and private
212 key files may be used like this:
213
214 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
215 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem';
216
217 You may test your files with the eg/net-ssl-test program, bundled with
218 the distribution, by issuing a command like:
219
220 perl eg/net-ssl-test -cert=certs/notacacert.pem \
221 -key=certs/notacakeynopass.pem -d GET $HOST_NAME
222
223 Additionally, if you would like to tell the client where the CA file
224 is, you may set these.
225
226 $ENV{HTTPS_CA_FILE} = "some_file";
227 $ENV{HTTPS_CA_DIR} = "some_dir";
228
229 Note that, if specified, $ENV{HTTPS_CA_FILE} must point to the actual
230 certificate file. That is, $ENV{HTTPS_CA_DIR} is *not* the path were
231 $ENV{HTTPS_CA_FILE} is located.
232
233 For certificates in $ENV{HTTPS_CA_DIR} to be picked up, follow the
234 instructions on
235 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
236
237 There is no sample CA cert file at this time for testing, but you may
238 configure eg/net-ssl-test to use your CA cert with the -CAfile option.
239 (TODO: then what is the ./certs directory in the distribution?)
240
241 Creating a test certificate
242 To create simple test certificates with OpenSSL, you may run the
243 following command:
244
245 openssl req -config /usr/local/openssl/openssl.cnf \
246 -new -days 365 -newkey rsa:1024 -x509 \
247 -keyout notacakey.pem -out notacacert.pem
248
249 To remove the pass phrase from the key file, run:
250
251 openssl rsa -in notacakey.pem -out notacakeynopass.pem
252
253 PKCS12 support
254 The directives for enabling use of PKCS12 certificates is:
255
256 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12';
257 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
258
259 Use of this type of certificate takes precedence over previous
260 certificate settings described. (TODO: unclear? Meaning "the presence
261 of this type of certificate"?)
262
264 "Crypt::SSLeay" tries very hard to connect to any SSL web server
265 accomodating servers that are buggy, old or simply not standards-
266 compliant. To this effect, this module will try SSL connections in this
267 order:
268
269 SSL v23
270 should allow v2 and v3 servers to pick their best type
271
272 SSL v3
273 best connection type
274
275 SSL v2
276 old connection type
277
278 Unfortunately, some servers seem not to handle a reconnect to SSL v3
279 after a failed connect of SSL v23 is tried, so you may set before using
280 LWP or Net::SSL:
281
282 $ENV{HTTPS_VERSION} = 3;
283
284 to force a version 3 SSL connection first. At this time only a version
285 2 SSL connection will be tried after this, as the connection attempt
286 order remains unchanged by this setting.
287
289 Many thanks to the following individuals who helped improve
290 "Crypt-SSLeay":
291
292 Gisle Aas for writing this module and many others including libwww, for
293 perl. The web will never be the same :)
294
295 Ben Laurie deserves kudos for his excellent patches for better error
296 handling, SSL information inspection, and random seeding.
297
298 Dongqiang Bai for host name resolution fix when using a proxy.
299
300 Stuart Horner of Core Communications, Inc. who found the need for
301 building "--shared" OpenSSL libraries.
302
303 Pavel Hlavnicka for a patch for freeing memory when using a pkcs12
304 file, and for inspiring more robust "read()" behavior.
305
306 James Woodyatt is a champ for finding a ridiculous memory leak that has
307 been the bane of many a Crypt::SSLeay user.
308
309 Bryan Hart for his patch adding proxy support, and thanks to Tobias
310 Manthey for submitting another approach.
311
312 Alex Rhomberg for Alpha linux ccc patch.
313
314 Tobias Manthey for his patches for client certificate support.
315
316 Daisuke Kuroda for adding PKCS12 certificate support.
317
318 Gamid Isayev for CA cert support and insights into error messaging.
319
320 Jeff Long for working through a tricky CA cert SSLClientVerify issue.
321
322 Chip Turner for a patch to build under perl 5.8.0.
323
324 Joshua Chamas for the time he spent maintaining the module.
325
326 Jeff Lavallee for help with alarms on read failures (CPAN bug #12444).
327
328 Guenter Knauf for significant improvements in configuring things in
329 Win32 and Netware lands and Jan Dubois for various suggestions for
330 improvements.
331
332 and many others who provided bug reports, suggestions, fixes and
333 patches.
334
336 Net::SSL
337 If you have downloaded this distribution as of a dependency of
338 another distribution, it's probably due to this module (which is
339 included in this distribution).
340
341 Net::SSLeay
342 Net::SSLeay provides access to the OpenSSL API directly from Perl.
343 See http://search.cpan.org/dist/Net-SSLeay/
344 <http://search.cpan.org/dist/Net-SSLeay/>.
345
346 OpenSSL binary packages for Windows
347 See <http://www.openssl.org/related/binaries.html>.
348
350 For use of Crypt::SSLeay & Net::SSL with Perl's LWP, please send email
351 to libwww@perl.org <mailto:libwww@perl.org>.
352
353 For OpenSSL or general SSL support, including issues associated with
354 building and installing OpenSSL on your system, please email the
355 OpenSSL users mailing list at openssl-users@openssl.org
356 <mailto:openssl-users@openssl.org>. See
357 <http://www.openssl.org/support/community.html> for other mailing lists
358 and archives.
359
360 Please report all bugs at
361 "/rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay"" in "http:.
362
364 This module was originally written by Gisle Aas, and was subsequently
365 maintained by Joshua Chamas, David Landgren, brian d foy and Sinan
366 Unur.
367
369 Copyright (c) 2010 A. Sinan Unur
370
371 Copyright (c) 2006-2007 David Landgren
372
373 Copyright (c) 1999-2003 Joshua Chamas
374
375 Copyright (c) 1998 Gisle Aas
376
378 This program is free software; you can redistribute it and/or modify it
379 under the same terms as Perl itself.
380
381
382
383perl v5.12.1 2010-08-24 SSLeay(3)