1NAME
2 Crypt::SSLeay - OpenSSL glue that provides LWP https support
3
4SYNOPSIS
5 lwp-request https://www.example.com
6
7 use LWP::UserAgent;
8 my $ua = new LWP::UserAgent;
9 my $req = new HTTP::Request('GET', 'https://www.example.com');
10 my $res = $ua->request($req);
11 print $res->code."\n";
12
13 # PROXY SUPPORT
14 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
15
16 # PROXY_BASIC_AUTH
17 $ENV{HTTPS_PROXY_USERNAME} = 'username';
18 $ENV{HTTPS_PROXY_PASSWORD} = 'password';
19
20 # DEBUGGING SWITCH / LOW LEVEL SSL DIAGNOSTICS
21 $ENV{HTTPS_DEBUG} = 1;
22
23 # DEFAULT SSL VERSION
24 $ENV{HTTPS_VERSION} = '3';
25
26 # CLIENT CERT SUPPORT
27 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
28 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem';
29
30 # CA CERT PEER VERIFICATION
31 $ENV{HTTPS_CA_FILE} = 'certs/ca-bundle.crt';
32 $ENV{HTTPS_CA_DIR} = 'certs/';
33
34 # CLIENT PKCS12 CERT SUPPORT
35 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12';
36 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
37
38DESCRIPTION
39 This perl module provides support for the https protocol under LWP, so
40 that a LWP::UserAgent can make https GET & HEAD & POST requests. Please
41 see perldoc LWP for more information on POST requests.
42
43 The Crypt::SSLeay package contains Net::SSL, which is automatically
44 loaded by LWP::Protocol::https on https requests, and provides the
45 necessary SSL glue for that module to work via these deprecated modules:
46
47 Crypt::SSLeay::CTX
48 Crypt::SSLeay::Conn
49 Crypt::SSLeay::X509
50
51 Work on Crypt::SSLeay has been continued only to provide https support
52 for the LWP - libwww perl libraries. If you want access to the OpenSSL
53 API via perl, check out Sampo's Net::SSLeay.
54
55INSTALL
56 OpenSSL
57 You must have OpenSSL or SSLeay installed before compiling this module.
58 You can get the latest OpenSSL package from:
59
60 http://www.openssl.org
61
62 On Debian systems, you will need to install the libssl-dev package,
63 at least for the duration of the build (it may be removed afterwards).
64
65 Other package-based systems may require something similar. The key is
66 that Crypt::SSLeay makes calls to the OpenSSL library, and how to do
67 so is specified in the C header files that come with the library.
68 Some systems break out the header files into a separate package from
69 that of the libraries. Once the program has been built, you don't
70 need the headers any more.
71
72 When installing openssl make sure your config looks like:
73
74 ./config --openssldir=/usr/local/openssl
75 or
76 ./config --openssldir=/usr/local/ssl
77
78 If you are planning on upgrading the default OpenSSL libraries on a
79 system like RedHat, not that I would recommend this, then you might try
80 something like:
81
82 ./config --openssldir=/usr --shared
83
84 The --shared option to config will set up building the .so shared
85 libraries which is important for such systems.
86
87 then
88 make
89 make test
90 make install
91
92 This way Crypt::SSLeay will pick up the includes and libraries
93 automatically. If your includes end up going into a separate directory
94 like /usr/local/include, then you may need to symlink
95 /usr/local/openssl/include to /usr/local/include
96
97 Crypt::SSLeay
98 The latest Crypt::SSLeay can be found at your nearest CPAN, and also:
99
100 http://www.perl.com/CPAN-local/modules/by-module/Crypt/
101
102 Once you have downloaded it, Crypt::SSLeay installs easily using the
103 make or nmake commands as shown below.
104
105 perl Makefile.PL
106 make
107 make test
108 make install
109
110 * use nmake or dmake for win32
111
112 For unattended (batch) installations, to be absolutely certain that
113 F<Makefile.PL> does not prompt for questions on STDIN, set the
114 following environment variable beforehand:
115
116 PERL_MM_USE_DEFAULT=1
117
118 (This is true for any CPAN module that uses C<ExtUtils::MakeMaker>).
119
120 Windows
121 For Activestate users, the ActiveState company does not have a permit
122 from the Canadian Federal Government to distribute cryptographic
123 software. This prevents "Crypt::SSLeay" from being distributed as a PPM
124 package from their repository. See
125 <http://aspn.activestate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-faq2.html#crypto_packages>
126 for more information on this issue.
127
128 You may download it from Randy Kobes's PPM repository by using the
129 following command:
130
131 ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd
132
133 An alternative is to add the uwinnipeg.ca PPM repository to your local
134 installation. See <http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html> for
135 more details.
136
137PROXY SUPPORT
138 LWP::UserAgent and Crypt::SSLeay have their own versions of proxy
139 support. Please read these sections to see which one may be right for
140 you.
141
142 LWP::UserAgent Proxy Support
143 LWP::UserAgent has its own methods of proxying which may work for you
144 and is likely incompatible with Crypt::SSLeay proxy support. To use
145 LWP::UserAgent proxy support, try something like:
146
147 my $ua = new LWP::UserAgent;
148 $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port");
149
150 At the time of this writing, libwww v5.6 seems to proxy https requests
151 fine with an Apache mod_proxy server. It sends a line like:
152
153 GET https://www.example.com HTTP/1.1
154
155 to the proxy server, which is not the CONNECT request that some proxies
156 would expect, so this may not work with other proxy servers than
157 mod_proxy. The CONNECT method is used by Crypt::SSLeay's internal proxy
158 support.
159
160 Crypt::SSLeay Proxy Support
161 For native Crypt::SSLeay proxy support of https requests, you need to
162 set an environment variable HTTPS_PROXY to your proxy server & port, as
163 in:
164
165 # PROXY SUPPORT
166 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
167 $ENV{HTTPS_PROXY} = '127.0.0.1:8080';
168
169 Use of the HTTPS_PROXY environment variable in this way is similar to
170 LWP::UserAgent->env_proxy() usage, but calling that method will likely
171 override or break the Crypt::SSLeay support, so do not mix the two.
172
173 Basic auth credentials to the proxy server can be provided this way:
174
175 # PROXY_BASIC_AUTH
176 $ENV{HTTPS_PROXY_USERNAME} = 'username';
177 $ENV{HTTPS_PROXY_PASSWORD} = 'password';
178
179 For an example of LWP scripting with Crypt::SSLeay native proxy support,
180 please see the source of the eg/lwp-ssl-test script in the Crypt::SSLeay
181 distribution.
182
183CLIENT CERTIFICATE SUPPORT
184 Certificate support is new provided by patches from Tobias Manthey. Is
185 ALPHA as of .25, but looking pretty stable as of .29.
186
187 PEM encoded certificate and private key files may be used like this:
188
189 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
190 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem';
191
192 You may test your files with the eg/net-ssl-test program by issuing a
193 command like:
194
195 perl eg/net-ssl-test -cert=certs/notacacert.pem -key=certs/notacakeynopass.pem -d GET $HOST_NAME
196
197 Additionally, if you would like to tell the client where the CA file is,
198 you may set these. These *CA* configs are ALPHA as of version .29.
199
200 $ENV{HTTPS_CA_FILE} = "some_file";
201 $ENV{HTTPS_CA_DIR} = "some_dir";
202
203 There is no sample CA cert file at this time for testing, but you may
204 configure eg/net_ssl_test to use your CA cert with the -CAfile option.
205
206 Creating a Test Certificate
207 To create simple test certificates with openssl, you may:
208
209 /usr/local/openssl/bin/openssl req -config /usr/local/openssl/openssl.cnf -new -days 365 -newkey rsa:1024 -x509 -keyout notacakey.pem -out notacacert.pem
210
211 To remove the pass phrase from the key file, execute this:
212 /usr/local/openssl/bin/openssl rsa -in notacakey.pem -out
213 notacakeynopass.pem
214
215 PKCS12
216 New as of version .45 is PKCS12 certificate support thanks to Daisuke
217 Kuroda The directives for enabling use of these certificates is:
218
219 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12';
220 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
221
222 Use of this type of certificate will take precedence over previous
223 certificate settings described.
224
225SSL VERSIONS
226 Crypt::SSLeay tries very hard to connect to ANY SSL web server trying to
227 accomodate servers that are buggy, old or simply not standards
228 compliant. To this effect, this module will try SSL connections in this
229 order:
230
231 SSL v23 - should allow v2 & v3 servers to pick their best type
232 SSL v3 - best connection type
233 SSL v2 - old connection type
234
235 Unfortunately, some servers seem not to handle a reconnect to SSL v3
236 after a failed connect of SSL v23 is tried, so you may set before using
237 LWP or Net::SSL:
238
239 $ENV{HTTPS_VERSION} = 3;
240
241 so that a SSL v3 connection is tried first. At this time only a SSL v2
242 connection will be tried after this, as the connection attempt order
243 remains unchanged by this setting.
244
245COMPATIBILITY
246 This module has been compiled on the following platforms:
247
248 PLATFORM CPU SSL PERL VER DATE WHO
249 -------- --- --- ---- --- ---- ---
250 Linux 2.4.7 x86 OpenSSL 0.9.7 5.00800 .51 2003-06-10 Joshua Chamas
251 Linux 2.4.7 x86 OpenSSL 0.9.6g 5.00800 .49 2003-01-29 Joshua Chamas
252 Win2000 SP2 x86 OpenSSL 0.9.7 5.00601 .49 2003-01-29 Joshua Chamas
253 WinNT SP6 x86 OpenSSL 0.9.6a 5.00601 .45 2002-08-01 Joshua Chamas
254 Linux 2.4.7 x86 OpenSSL 0.9.6d 5.00800 .45 2002-08-01 Joshua Chamas
255 Linux 2.4.7 x86 OpenSSL 0.9.6 5.00601 .39 2002-06-23 Joshua Chamas
256 Solaris 2.8 Sparc ? 5.00503 .37 2002-05-31 Christopher Biow
257 OpenBSD 2.8 Sparc ? 5.00600 .25 2001-04-11 Tim Ayers
258 Linux 2.2.14 x86 OpenSSL 0.9.6 5.00503 .25 2001-04-10 Joshua Chamas
259 WinNT SP6 x86 OpenSSL 0.9.4 5.00404 .25 2001-04-10 Joshua Chamas
260 Solaris 2.7 Sparc OpenSSL 0.9.6 5.00503 .22 2001-03-01 Dave Paris
261 AIX 4.3.2 RS/6000 OpenSSL 0.9.6 5.6.0 .19 2001-01-08 Peter Heimann
262 Solaris 2.6 x86 OpenSSL 0.9.5a 5.00501 .17 2000-09-04 Joshua Chamas
263 Linux 2.2.12 x86 OpenSSL 0.9.5a 5.00503 .16 2000-07-13 David Harris
264 FreeBSD 3.2 ?x86 OpenSSL 0.9.2b 5.00503 ? 1999-09-29 Rip Toren
265 Solaris 2.6 ?Sparc OpenSSL 0.9.4 5.00404 ? 1999-08-24 Patrick Killelea
266 FreeBSD 2.2.5 x86 OpenSSL 0.9.3 5.00404 ? 1999-08-19 Andy Lee
267 Solaris 2.5.1 USparc OpenSSL 0.9.4 5.00503 ? 1999-08-18 Marek Rouchal
268 Solaris 2.6 x86 SSLeay 0.8.0 5.00501 ? 1999-08-12 Joshua Chamas
269 Linux 2.2.10 x86 OpenSSL 0.9.4 5.00503 ? 1999-08-11 John Barrett
270 WinNT SP4 x86 SSLeay 0.9.2 5.00404 ? 1999-08-10 Joshua Chamas
271
272BUILD NOTES
273 Win32, WinNT, Win2000, can't build
274 If you cannot get it to build on your windows box, try ActiveState perl,
275 at least their builds 522 & 618 are known to have a ppm install of
276 Crypt::SSLeay available. Please see http://www.activestate.com for more
277 info.
278
279 AIX 4.3.2 - Symbol Error: __umoddi3 : referenced symbol not found
280 The __umoddi3 problem applies here as well when compiling with gcc.
281
282 Alternative solution: In Makefile.PL, prepend "-L"/usr/local/<path to
283 your gcc lib>/<version> to the $LIBS value. Add after line 82:
284
285 $LIBS = '-L' . dirname(`gcc -print-libgcc-file-name`) . ' ' . $LIBS;
286
287 Solaris x86 - Symbol Error: __umoddi3 : referenced symbol not found
288 Problem:
289
290 On Solaris x86, the default PERL configuration, and preferred, is to use
291 the ld linker that comes with the OS, not gcc. Unfortunately during the
292 OpenSSL build process, gcc generates in libcrypto.a, from bn_word.c, the
293 undefined symbol __umoddi3, which is supposed to be later resolved by
294 gcc from libgcc.a
295
296 The system ld linker does not know about libgcc.a by default, so when
297 building Crypt::SSLeay, there is a linker error for __umoddi3
298
299 Solution:
300
301 The fix for this symlink your libgcc.a to some standard directory like
302 /usr/local/lib, so that the system linker, ld, can find it when building
303 Crypt::SSLeay.
304
305 FreeBSD 2.x.x / Solaris - ... des.h:96 #error _ is defined ...
306 If you encounter this error: "...des.h:96: #error _ is defined, but some
307 strange definition the DES library cannot handle that...," then you need
308 to edit the des.h file and comment out the "#error" line.
309
310 Its looks like this error might be common to other operating systems,
311 and that occurs with OpenSSL 0.9.3. Upgrades to 0.9.4 seem to fix this
312 problem.
313
314 SunOS 4.1.4, Perl 5.004_04 - ld.so: Undefined symbol: _CRYPT_mem_ctrl
315 Problems: (initial build was fine, but execution of Perl scripts had
316 problems)
317
318 Got a message "ld.so: Undefined symbol: _CRYPT_mem_ctrl" solution: In
319 the Makefile, comment out the line with "-fpic" (also try changing to
320 "-fPIC", and this works also, not sure if one is preferred).
321
322OTHER MODULES
323
324A number of CPAN modules list Crypt-SSLeay as a pre-requisite. As of
325March 2007, this list included
326
327 Acme-SDUM-Renew ROOT
328 ASNMTAP ASNMTAP
329 Business-Billing-TMobile-UK SRSHAH
330 Business-OnlinePayment-Protx TEEJAY
331 Business-PayPal-IPN SHERZODR
332 Finance-Bank-CreditMut CBOUVI
333 Finance-Bank-Fubon-TW AUTRIJUS
334 Finance-Bank-HDFC ROHAN
335 Finance-Quote HAMPTON
336 Finance-SE-PPM ERWAN
337 GMail-IMAPD KRS
338 Google-Checkout DZHUO
339 Hey-heyPass WILSOND
340 HTTP-QuickBase CVONROES
341 Mail-Webmail-Gmail MINCUS
342 Module-Release BDFOY
343 Net-Artera IVAN
344 Net-eBay ICHUDOV
345 Net-SMS-MessageNet DDICK
346 Net-SMS-MessageNet DDICK
347 Net-SMS-O2 AWRIGLEY
348 Net-SMS-Optimus ROOT
349 Net-SMS-PChome SNOWFLY
350 Net-UPS SHERZODR
351 Net-XRC IVAN
352 o2sms MACKERS
353 WebService-CIA IMALPASS
354 WWW-FleXtel NICOLAW
355 WWW-GMail XANTUS
356 WWW-Hotmail XANTUS
357 WWW-Mail15 REFLOG
358 WWW-Myspace GRANTG
359 WWW-Postini PGUZIS
360 WWW-RIPE-LIRPortal RIPENCC
361 WWW-Scraper-Gmail KASTNER
362 WWW-Yahoo-Groups SPOON
363 Yahoo-Marketing JLAVALLEE
364
365NOTES
366 Many thanks to Gisle Aas for the original writing of this module and
367 many others including libwww for perl. The web will never be the same :)
368
369 Ben Laurie deserves kudos for his excellent patches for better error
370 handling, SSL information inspection, and random seeding.
371
372 Thanks to Dongqiang Bai for host name resolution fix when using a proxy.
373
374 Thanks to Stuart Horner of Core Communications, Inc. who found the need
375 for building --shared OpenSSL libraries.
376
377 Thanks to Pavel Hlavnicka for a patch for freeing memory when using a
378 pkcs12 file, and for inspiring more robust read() behavior.
379
380 James Woodyatt is a champ for finding a ridiculous memory leak that has
381 been the bane of many a Crypt::SSLeay user.
382
383 Thanks to Bryan Hart for his patch adding proxy support, and thanks to
384 Tobias Manthey for submitting another approach.
385
386 Thanks to Alex Rhomberg for Alpha linux ccc patch.
387
388 Thanks to Tobias Manthey for his patches for client certificate support.
389
390 Thanks to Gamid Isayev for CA cert support and insight into error
391 messaging.
392
393 Thanks to Jeff Long for working through a tricky CA cert SSLClientVerify
394 issue.
395
396 Thanks to Chip Turner for patch to build under perl 5.8.0
397
398 Thanks to Joshua Chamas for the time he spent maintaining the
399 module.
400
401SUPPORT
402 For use of Crypt::SSLeay & Net::SSL with perl's LWP, please send email
403 to libwww@perl.org .
404
405 For OpenSSL or general SSL support please email the openssl user mailing
406 list at openssl-users@openssl.org . This includes issues associated with
407 building and installing OpenSSL on one's system.
408
409 Please report all bugs at
410 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>.
411
412 This module was originally written by Gisle Aas, and was subsequently
413 maintained by Joshua Chamas. It is currently maintained by David
414 Landgren.
415
416COPYRIGHT
417 Copyright (c) 2006-2007 David Landgren.
418 Copyright (c) 1999-2003 Joshua Chamas.
419 Copyright (c) 1998 Gisle Aas.
420
421 This program is free software; you can redistribute it and/or modify it
422 under the same terms as Perl itself.
423
424