File Coverage

blib/lib/Crypt/SSLeay.pm
Criterion Covered Total %
statement 13 15 86.7
branch n/a
condition n/a
subroutine 5 7 71.4
pod n/a
total 18 22 81.8


line stmt bran cond sub pod time code
1             package Crypt::SSLeay;
2              
3 2     2   1230 use Crypt::SSLeay::X509;
  2         24  
  2         60  
4              
5 2     2   31 use strict;
  2         19  
  2         30  
6 2     2   30 use vars qw(@ISA $VERSION %CIPHERS);
  2         17  
  2         29  
7              
8             require DynaLoader;
9              
10             @ISA = qw(DynaLoader);
11             $VERSION = '0.53';
12              
13             bootstrap Crypt::SSLeay $VERSION;
14              
15 2     2   33 use vars qw(%CIPHERS);
  2         18  
  2         27  
16             %CIPHERS = (
17                'NULL-MD5' => "No encryption with a MD5 MAC",
18                'RC4-MD5' => "128 bit RC4 encryption with a MD5 MAC",
19                'EXP-RC4-MD5' => "40 bit RC4 encryption with a MD5 MAC",
20                'RC2-CBC-MD5' => "128 bit RC2 encryption with a MD5 MAC",
21                'EXP-RC2-CBC-MD5' => "40 bit RC2 encryption with a MD5 MAC",
22                'IDEA-CBC-MD5' => "128 bit IDEA encryption with a MD5 MAC",
23                'DES-CBC-MD5' => "56 bit DES encryption with a MD5 MAC",
24                'DES-CBC-SHA' => "56 bit DES encryption with a SHA MAC",
25                'DES-CBC3-MD5' => "192 bit EDE3 DES encryption with a MD5 MAC",
26                'DES-CBC3-SHA' => "192 bit EDE3 DES encryption with a SHA MAC",
27                'DES-CFB-M1' => "56 bit CFB64 DES encryption with a one byte MD5 MAC",
28             );
29              
30              
31             # A xsupp bug made this nessesary
32 2     2   51 sub Crypt::SSLeay::CTX::DESTROY { shift->free; }
33 0     0     sub Crypt::SSLeay::Conn::DESTROY { shift->free; }
34 0     0     sub Crypt::SSLeay::X509::DESTROY { shift->free; }
35              
36             1;
37              
38             __END__
39            
40             =head1 NAME
41            
42             Crypt::SSLeay - OpenSSL glue that provides LWP https support
43            
44             =head1 SYNOPSIS
45            
46             lwp-request https://www.example.com
47            
48             use LWP::UserAgent;
49             my $ua = new LWP::UserAgent;
50             my $req = new HTTP::Request('GET', 'https://www.example.com');
51             my $res = $ua->request($req);
52             print $res->code."\n";
53            
54             # proxy support
55             $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
56            
57             # proxy_basic_auth
58             $ENV{HTTPS_PROXY_USERNAME} = 'username';
59             $ENV{HTTPS_PROXY_PASSWORD} = 'password';
60            
61             # debugging (SSL diagnostics)
62             $ENV{HTTPS_DEBUG} = 1;
63            
64             # default ssl version
65             $ENV{HTTPS_VERSION} = '3';
66            
67             # client certificate support
68             $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
69             $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem';
70            
71             # CA cert peer verification
72             $ENV{HTTPS_CA_FILE} = 'certs/ca-bundle.crt';
73             $ENV{HTTPS_CA_DIR} = 'certs/';
74            
75             # Client PKCS12 cert support
76             $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12';
77             $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
78            
79             =head1 DESCRIPTION
80            
81             This document describes C<Crypt::SSLeay> version 0.53, released
82             2006-12-26.
83            
84             This perl module provides support for the https protocol under LWP,
85             to allow an C<LWP::UserAgent> object to perform GET, HEAD and POST
86             requests. Please see LWP for more information on POST requests.
87            
88             The C<Crypt::SSLeay> package provides C<Net::SSL>, which is loaded
89             by C<LWP::Protocol::https> for https requests and provides the
90             necessary SSL glue.
91            
92             This distribution also makes following deprecated modules available:
93            
94             Crypt::SSLeay::CTX
95             Crypt::SSLeay::Conn
96             Crypt::SSLeay::X509
97            
98             Work on Crypt::SSLeay has been continued only to
99             provide https support for the LWP (libwww-perl)
100             libraries. People wishing to access the OpenSSL API
101             directly from Perl are advised to look at the
102             C<Net::SSLeay> module.
103            
104             http://search.cpan.org/dist/Net_SSLeay.pm/
105            
106             =head1 INSTALL
107            
108             =head2 OpenSSL
109            
110             You must have OpenSSL or SSLeay installed before compiling
111             this module. You can get the latest OpenSSL package from:
112            
113             http://www.openssl.org/
114            
115             When installing openssl make sure your config looks like:
116            
117             > ./config --openssldir=/usr/local/openssl
118             or
119             > ./config --openssldir=/usr/local/ssl
120            
121             If you are planning on upgrading the default OpenSSL libraries on
122             a system like RedHat, not that I would recommend this, then
123             you might try something like:
124            
125             > ./config --openssldir=/usr --shared
126            
127             The --shared option to config will set up building the .so
128             shared libraries which is important for such systems.
129            
130             then
131             > make
132             > make test
133             > make install
134            
135             This way Crypt::SSLeay will pick up the includes and
136             libraries automatically. If your includes end up
137             going into a separate directory like /usr/local/include,
138             then you may need to symlink /usr/local/openssl/include
139             to /usr/local/include
140            
141             =head2 Crypt::SSLeay
142            
143             The latest Crypt::SSLeay can be found at your nearest CPAN,
144             and also:
145            
146             http://search.cpan.org/dist/Crypt-SSLeay/
147            
148             Once you have downloaded it, Crypt::SSLeay installs easily
149             using the make or nmake commands as shown below.
150            
151             > perl Makefile.PL
152             > make
153             > make test
154             > make install
155            
156             * use nmake for win32
157            
158             !!! NOTE for Win32 users, few people seem to be able to build
159             W Crypt::SSLeay successfully on that platform. You don't need
160             I to because ActiveState has already compiled it for you,
161             N and is available for their perl builds 618 & 522 as a ppm
162             3 install. It may also be available for their latest build.
163             2 For problems with this, please contact ActiveState.
164             !!! Please see http://www.activestate.com/
165            
166             =head1 PROXY SUPPORT
167            
168             LWP::UserAgent and Crypt::SSLeay have their own versions of
169             proxy support. Please read these sections to see which one
170             may be right for you.
171            
172             =head2 LWP::UserAgent Proxy Support
173            
174             LWP::UserAgent has its own methods of proxying which may work for
175             you and is likely to be incompatible with Crypt::SSLeay proxy support.
176             To use LWP::UserAgent proxy support, try something like:
177            
178             my $ua = new LWP::UserAgent;
179             $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port");
180            
181             At the time of this writing, libwww v5.6 seems to proxy https
182             requests fine with an Apache mod_proxy server. It sends a line like:
183            
184             GET https://www.example.com HTTP/1.1
185            
186             to the proxy server, which is not the CONNECT request that
187             some proxies would expect, so this may not work with other
188             proxy servers than mod_proxy. The CONNECT method is used
189             by Crypt::SSLeay's internal proxy support.
190            
191             =head2 Crypt::SSLeay Proxy Support
192            
193             For native Crypt::SSLeay proxy support of https requests,
194             you need to set an environment variable HTTPS_PROXY to your
195             proxy server and port, as in:
196            
197             # proxy support
198             $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
199             $ENV{HTTPS_PROXY} = '127.0.0.1:8080';
200            
201             Use of the C<HTTPS_PROXY> environment variable in this way
202             is similar to LWP::UserAgent->env_proxy() usage, but calling
203             that method will likely override or break the Crypt::SSLeay
204             support, so do not mix the two.
205            
206             Basic auth credentials to the proxy server can be provided
207             this way:
208            
209             # proxy_basic_auth
210             $ENV{HTTPS_PROXY_USERNAME} = 'username';
211             $ENV{HTTPS_PROXY_PASSWORD} = 'password';
212            
213             For an example of LWP scripting with Crypt::SSLeay native proxy
214             support, please look at the F<lwp-ssl-test> script in the
215             Crypt::SSLeay distribution.
216            
217             =head1 CLIENT CERTIFICATE SUPPORT
218            
219             Client certificates are supported. PEM0encoded certificate and
220             private key files may be used like this:
221            
222             $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
223             $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem';
224            
225             You may test your files with the F<net_ssl_test> program,
226             bundled with the distribution, by issuing a command like:
227            
228             ./net_ssl_test -cert=certs/notacacert.pem \
229             -key=certs/notacakeynopass.pem -d GET $HOST_NAME
230            
231             Additionally, if you would like to tell the client where
232             the CA file is, you may set these.
233            
234             $ENV{HTTPS_CA_FILE} = "some_file";
235             $ENV{HTTPS_CA_DIR} = "some_dir";
236            
237             There is no sample CA cert file at this time for testing,
238             but you may configure ./net_ssl_test to use your CA cert
239             with the -CAfile option. (TODO: then what is teh ./certs
240             directory in the distribution??)
241            
242             =head2 Creating a test certificate
243            
244             To create simple test certificates with OpenSSL, you may
245             run the following command:
246            
247             openssl req -config /usr/local/openssl/openssl.cnf \
248             -new -days 365 -newkey rsa:1024 -x509 \
249             -keyout notacakey.pem -out notacacert.pem
250            
251             To remove the pass phrase from the key file, run:
252            
253             openssl rsa -in notacakey.pem -out notacakeynopass.pem
254            
255             =head2 PKCS12 support
256            
257             The directives for enabling use of PKCS12 certificates is:
258            
259             $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12';
260             $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
261            
262             Use of this type of certificate takes precedence over previous
263             certificate settings described. (TODO: unclear? Meaning "the
264             presence of this type of certificate??)
265            
266             =head1 SSL versions
267            
268             Crypt::SSLeay tries very hard to connect to I<any> SSL web server
269             accomodating servers that are buggy, old or simply
270             not standards-compliant. To this effect, this module will
271             try SSL connections in this order:
272            
273             SSL v23 - should allow v2 and v3 servers to pick their best type
274             SSL v3 - best connection type
275             SSL v2 - old connection type
276            
277             Unfortunately, some servers seem not to handle a reconnect
278             to SSL v3 after a failed connect of SSL v23 is tried,
279             so you may set before using LWP or Net::SSL:
280            
281             $ENV{HTTPS_VERSION} = 3;
282            
283             so that a SSL v3 connection is tried first. At this time
284             only a SSL v2 connection will be tried after this, as the
285             connection attempt order remains unchanged by this setting.
286            
287             =head1 BUILD NOTES
288            
289             =head2 Win32, WinNT, Win2000, can't build
290            
291             If you cannot get it to build on your windows box, try
292             ActiveState perl, at least their builds 522 & 618 are
293             known to have a ppm install of Crypt::SSLeay available.
294             Please see http://www.activestate.com for more info.
295            
296             =head2 AIX 4.3.2 - Symbol Error: __umoddi3 : referenced symbol not found
297            
298             The __umoddi3 problem applies here as well when compiling with gcc.
299            
300             Alternative solution:
301             In Makefile.PL, prepend C<-L>/usr/local/<path to your gcc lib>/<version>
302             to the $LIBS value. Add after line 82:
303            
304             $LIBS = '-L' . dirname(`gcc -print-libgcc-file-name`) . ' ' . $LIBS;
305            
306             =head2 Solaris x86 - Symbol Error: __umoddi3 : referenced symbol not found
307            
308             Problem:
309            
310             On Solaris x86, the default PERL configuration, and preferred, is to use
311             the ld linker that comes with the OS, not gcc. Unfortunately during the
312             OpenSSL build process, gcc generates in libcrypto.a, from bn_word.c,
313             the undefined symbol __umoddi3, which is supposed to be later resolved
314             by gcc from libgcc.a
315            
316             The system ld linker does not know about libgcc.a by default, so
317             when building Crypt::SSLeay, there is a linker error for __umoddi3
318            
319             Solution:
320            
321             The fix for this symlink your libgcc.a to some standard directory
322             like /usr/local/lib, so that the system linker, ld, can find
323             it when building Crypt::SSLeay.
324            
325             =head2 FreeBSD 2.x.x / Solaris - ... des.h:96 #error _ is defined ...
326            
327             If you encounter this error: "...des.h:96: #error _ is
328             defined, but some strange definition the DES library cannot handle
329             that...," then you need to edit the des.h file and comment out the
330             "#error" line.
331            
332             Its looks like this error might be common to other operating
333             systems, and that occurs with OpenSSL 0.9.3. Upgrades to
334             0.9.4 seem to fix this problem.
335            
336             =head2 SunOS 4.1.4, Perl 5.004_04 - ld.so: Undefined symbol: _CRYPT_mem_ctrl
337            
338             Problems: (initial build was fine, but execution of Perl scripts had problems)
339            
340             Got a message "ld.so: Undefined symbol: _CRYPT_mem_ctrl"
341             solution: In the Makefile, comment out the line with
342             "-fpic" (also try changing to "-fPIC", and this works
343             also, not sure if one is preferred).
344            
345             =head1 NOTES
346            
347             Many thanks to Gisle Aas for the original writing of
348             this module and many others including libwww for perl.
349             The web will never be the same :)
350            
351             Ben Laurie deserves kudos for his excellent patches
352             for better error handling, SSL information inspection,
353             and random seeding.
354            
355             Thanks to Dongqiang Bai for host name resolution fix when
356             using a proxy.
357            
358             Thanks to Stuart Horner of Core Communications, Inc. who found
359             the need for building --shared OpenSSL libraries.
360            
361             Thanks to Pavel Hlavnicka for a patch for freeing memory when
362             using a pkcs12 file, and for inspiring more robust read() behavior.
363            
364             James Woodyatt is a champ for finding a ridiculous memory
365             leak that has been the bane of many a Crypt::SSLeay user.
366            
367             Thanks to Bryan Hart for his patch adding proxy support,
368             and thanks to Tobias Manthey for submitting another approach.
369            
370             Thanks to Alex Rhomberg for Alpha linux ccc patch.
371            
372             Thanks to Tobias Manthey for his patches for client
373             certificate support.
374            
375             Thanks to Daisuke Kuroda for adding PKCS12 certificate
376             support.
377            
378             Thanks to Gamid Isayev for CA cert support and
379             insights into error messaging.
380            
381             Thanks to Jeff Long for working through a tricky CA
382             cert SSLClientVerify issue.
383            
384             Thanks to Chip Turner for patch to build under perl 5.8.0.
385            
386             Thanks to Joshua Chamas for the time he spent maintaining the
387             module.
388            
389             =head1 SUPPORT
390            
391             For use of Crypt::SSLeay & Net::SSL with perl's LWP, please
392             send email to C<libwww@perl.org>.
393            
394             For OpenSSL or general SSL support please email the
395             openssl user mailing list at C<openssl-users@openssl.org>.
396             This includes issues associated with building and installing
397             OpenSSL on one's system.
398            
399             Please report all bugs at
400             L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>.
401            
402             This module was originally written by Gisle Aas, and was subsequently
403             maintained by Joshua Chamas.
404            
405             This module is currently maintained by David Landgren.
406            
407             =head1 COPYRIGHT
408            
409             Copyright (c) 2006 David Landgren.
410             Copyright (c) 1999-2003 Joshua Chamas.
411             Copyright (c) 1998 Gisle Aas.
412            
413             This program is free software; you can redistribute
414             it and/or modify it under the same terms as Perl itself.
415            
416             =cut
417