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

PROXY SUPPORT

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

CLIENT CERTIFICATE SUPPORT

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

SSL versions

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

ACKNOWLEDGEMENTS

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

SUPPORT

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

COPYRIGHT

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