Crypt::SSLeay(3pm)

1SSLeay(3)             User Contributed Perl Documentation            SSLeay(3)
2
3
4

NAME

6       Crypt::SSLeay - OpenSSL support for LWP
7

SYNOPSIS

9         lwp-request https://www.example.com
10
11         use LWP::UserAgent;
12         my $ua  = LWP::UserAgent->new;
13         my $req = HTTP::Request->new('GET', 'https://www.example.com/');
14         my $res = $ua->request($req);
15         print $res->content, "\n";
16

DESCRIPTION

18       This document describes "Crypt::SSLeay" version 0.56, released
19       2007-07-10.
20
21       This perl module provides support for the https protocol under LWP, to
22       allow an "LWP::UserAgent" object to perform GET, HEAD and POST
23       requests. Please see LWP for more information on POST requests.
24
25       The "Crypt::SSLeay" package provides "Net::SSL", which is loaded by
26       "LWP::Protocol::https" for https requests and provides the necessary
27       SSL glue.
28
29       This distribution also makes following deprecated modules available:
30
31         Crypt::SSLeay::CTX
32         Crypt::SSLeay::Conn
33         Crypt::SSLeay::X509
34
35       Work on Crypt::SSLeay has been continued only to provide https support
36       for the LWP (libwww-perl) libraries.
37

ENVIRONMENT VARIABLES

39       The following environment variables change the way "Crypt::SSLeay" and
40       "Net::SSL" behave.
41
42         # proxy support
43         $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
44
45         # proxy_basic_auth
46         $ENV{HTTPS_PROXY_USERNAME} = 'username';
47         $ENV{HTTPS_PROXY_PASSWORD} = 'password';
48
49         # debugging (SSL diagnostics)
50         $ENV{HTTPS_DEBUG} = 1;
51
52         # default ssl version
53         $ENV{HTTPS_VERSION} = '3';
54
55         # client certificate support
56         $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
57         $ENV{HTTPS_KEY_FILE}  = 'certs/notacakeynopass.pem';
58
59         # CA cert peer verification
60         $ENV{HTTPS_CA_FILE}   = 'certs/ca-bundle.crt';
61         $ENV{HTTPS_CA_DIR}    = 'certs/';
62
63         # Client PKCS12 cert support
64         $ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
65         $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
66

INSTALL

68       OpenSSL
69
70       You must have OpenSSL or SSLeay installed before compiling this module.
71       You can get the latest OpenSSL package from:
72
73         http://www.openssl.org/
74
75       On Debian systems, you will need to install the libssl-dev package, at
76       least for the duration of the build (it may be removed afterwards).
77
78       Other package-based systems may require something similar. The key is
79       that Crypt::SSLeay makes calls to the OpenSSL library, and how to do so
80       is specified in the C header files that come with the library.  Some
81       systems break out the header files into a separate package from that of
82       the libraries. Once the program has been built, you don't need the
83       headers any more.
84
85       When installing openssl make sure your config looks like:
86
87         ./config --openssldir=/usr/local/openssl
88        or
89         ./config --openssldir=/usr/local/ssl
90
91       If you are planning on upgrading the default OpenSSL libraries on a
92       system like RedHat, (not recommended), then try something like:
93
94         ./config --openssldir=/usr --shared
95
96       The --shared option to config will set up building the .so shared
97       libraries which is important for such systems. This is followed by:
98
99         make
100         make test
101         make install
102
103       This way Crypt::SSLeay will pick up the includes and libraries automat‐
104       ically. If your includes end up going into a separate directory like
105       /usr/local/include, then you may need to symlink
106       /usr/local/openssl/include to /usr/local/include
107
108       Crypt::SSLeay
109
110       The latest Crypt::SSLeay can be found at your nearest CPAN, as well as:
111
112         http://search.cpan.org/dist/Crypt-SSLeay/
113
114       Once you have downloaded it, Crypt::SSLeay installs easily using the
115       "make" * commands as shown below.
116
117         perl Makefile.PL
118         make
119         make test
120         make install
121
122         * use nmake or dmake on Win32
123
124       For unattended (batch) installations, to be absolutely certain that
125       Makefile.PL does not prompt for questions on STDIN, set the following
126       environment variable beforehand:
127
128         PERL_MM_USE_DEFAULT=1
129
130       (This is true for any CPAN module that uses "ExtUtils::MakeMaker").
131
132       Windows
133
134       "Crypt::SSLeay" builds correctly with Strawberry Perl.
135
136       For Activestate users, the ActiveState company does not have a permit
137       from the Canadian Federal Government to distribute cryptographic soft‐
138       ware. This prevents "Crypt::SSLeay" from being distributed as a PPM
139       package from their repository. See <http://aspn.actives‐
140       tate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-faq2.html#crypto_pack‐
141       ages> for more information on this issue.
142
143       You may download it from Randy Kobes's PPM repository by using the fol‐
144       lowing command:
145
146         ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd
147
148       An alternative is to add the uwinnipeg.ca PPM repository to your local
149       installation. See <http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html> for
150       more details.
151
152       VMS
153
154       It is assumed that the OpenSSL installation is located at "/ssl$root".
155       Define this logical to point to the appropriate place in the filesys‐
156       tem.
157

PROXY SUPPORT

159       LWP::UserAgent and Crypt::SSLeay have their own versions of proxy sup‐
160       port. Please read these sections to see which one is appropriate.
161
162       LWP::UserAgent proxy support
163
164       LWP::UserAgent has its own methods of proxying which may work for you
165       and is likely to be incompatible with Crypt::SSLeay proxy support.  To
166       use LWP::UserAgent proxy support, try something like:
167
168         my $ua = new LWP::UserAgent;
169         $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port");
170
171       At the time of this writing, libwww v5.6 seems to proxy https requests
172       fine with an Apache mod_proxy server.  It sends a line like:
173
174         GET https://www.example.com HTTP/1.1
175
176       to the proxy server, which is not the CONNECT request that some proxies
177       would expect, so this may not work with other proxy servers than
178       mod_proxy. The CONNECT method is used by Crypt::SSLeay's internal proxy
179       support.
180
181       Crypt::SSLeay proxy support
182
183       For native Crypt::SSLeay proxy support of https requests, you need to
184       set the environment variable "HTTPS_PROXY" to your proxy server and
185       port, as in:
186
187         # proxy support
188         $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
189         $ENV{HTTPS_PROXY} = '127.0.0.1:8080';
190
191       Use of the "HTTPS_PROXY" environment variable in this way is similar to
192       "LWP::UserAgent-"env_proxy()> usage, but calling that method will
193       likely override or break the Crypt::SSLeay support, so do not mix the
194       two.
195
196       Basic auth credentials to the proxy server can be provided this way:
197
198         # proxy_basic_auth
199         $ENV{HTTPS_PROXY_USERNAME} = 'username';
200         $ENV{HTTPS_PROXY_PASSWORD} = 'password';
201
202       For an example of LWP scripting with "Crypt::SSLeay" native proxy sup‐
203       port, please look at the eg/lwp-ssl-test script in the "Crypt::SSLeay"
204       distribution.
205

CLIENT CERTIFICATE SUPPORT

207       Client certificates are supported. PEM0encoded certificate and private
208       key files may be used like this:
209
210         $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
211         $ENV{HTTPS_KEY_FILE}  = 'certs/notacakeynopass.pem';
212
213       You may test your files with the eg/net-ssl-test program, bundled with
214       the distribution, by issuing a command like:
215
216         perl eg/net-ssl-test -cert=certs/notacacert.pem \
217           -key=certs/notacakeynopass.pem -d GET $HOST_NAME
218
219       Additionally, if you would like to tell the client where the CA file
220       is, you may set these.
221
222         $ENV{HTTPS_CA_FILE} = "some_file";
223         $ENV{HTTPS_CA_DIR}  = "some_dir";
224
225       There is no sample CA cert file at this time for testing, but you may
226       configure eg/net-ssl-test to use your CA cert with the -CAfile option.
227       (TODO: then what is the ./certs directory in the distribution?)
228
229       Creating a test certificate
230
231       To create simple test certificates with OpenSSL, you may run the fol‐
232       lowing command:
233
234         openssl req -config /usr/local/openssl/openssl.cnf \
235           -new -days 365 -newkey rsa:1024 -x509 \
236           -keyout notacakey.pem -out notacacert.pem
237
238       To remove the pass phrase from the key file, run:
239
240         openssl rsa -in notacakey.pem -out notacakeynopass.pem
241
242       PKCS12 support
243
244       The directives for enabling use of PKCS12 certificates is:
245
246         $ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
247         $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
248
249       Use of this type of certificate takes precedence over previous certifi‐
250       cate settings described. (TODO: unclear? Meaning "the presence of this
251       type of certificate??)
252

SSL versions

254       Crypt::SSLeay tries very hard to connect to any SSL web server accomo‐
255       dating servers that are buggy, old or simply not standards-compliant.
256       To this effect, this module will try SSL connections in this order:
257
258         SSL v23 - should allow v2 and v3 servers to pick their best type
259         SSL v3  - best connection type
260         SSL v2  - old connection type
261
262       Unfortunately, some servers seem not to handle a reconnect to SSL v3
263       after a failed connect of SSL v23 is tried, so you may set before using
264       LWP or Net::SSL:
265
266         $ENV{HTTPS_VERSION} = 3;
267
268       to force a version 3 SSL connection first. At this time only a version
269       2 SSL connection will be tried after this, as the connection attempt
270       order remains unchanged by this setting.
271

ACKNOWLEDGEMENTS

273       Many thanks to Gisle Aas for writing this module and many others
274       including libwww, for perl. The web will never be the same :)
275
276       Ben Laurie deserves kudos for his excellent patches for better error
277       handling, SSL information inspection, and random seeding.
278
279       Thanks to Dongqiang Bai for host name resolution fix when using a
280       proxy.
281
282       Thanks to Stuart Horner of Core Communications, Inc. who found the need
283       for building --shared OpenSSL libraries.
284
285       Thanks to Pavel Hlavnicka for a patch for freeing memory when using a
286       pkcs12 file, and for inspiring more robust read() behavior.
287
288       James Woodyatt is a champ for finding a ridiculous memory leak that has
289       been the bane of many a Crypt::SSLeay user.
290
291       Thanks to Bryan Hart for his patch adding proxy support, and thanks to
292       Tobias Manthey for submitting another approach.
293
294       Thanks to Alex Rhomberg for Alpha linux ccc patch.
295
296       Thanks to Tobias Manthey for his patches for client certificate sup‐
297       port.
298
299       Thanks to Daisuke Kuroda for adding PKCS12 certificate support.
300
301       Thanks to Gamid Isayev for CA cert support and insights into error mes‐
302       saging.
303
304       Thanks to Jeff Long for working through a tricky CA cert SSLClientVer‐
305       ify issue.
306
307       Thanks to Chip Turner for patch to build under perl 5.8.0.
308
309       Thanks to Joshua Chamas for the time he spent maintaining the module.
310
311       Thanks to Jeff Lavallee for help with alarms on read failures (CPAN bug
312       #12444).
313

SUPPORT

329       For use of Crypt::SSLeay & Net::SSL with perl's LWP, please send email
330       to "libwww@perl.org".
331
332       For OpenSSL or general SSL support please email the openssl user mail‐
333       ing list at "openssl-users@openssl.org".  This includes issues associ‐
334       ated with building and installing OpenSSL on one's system.
335
336       Please report all bugs at
337       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>.
338
339       This module was originally written by Gisle Aas, and was subsequently
340       maintained by Joshua Chamas. It is currently maintained by David Land‐
341       gren.
342

COPYRIGHT

344        Copyright (c) 2006-2007 David Landgren.
345        Copyright (c) 1999-2003 Joshua Chamas.
346        Copyright (c) 1998 Gisle Aas.
347
348       This program is free software; you can redistribute it and/or modify it
349       under the same terms as Perl itself.
350
351
352
353perl v5.8.8                       2007-05-19                         SSLeay(3)