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 $response = $ua->get('https://www.example.com/');
14           print $response->content, "\n";
15

DESCRIPTION

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

ENVIRONMENT VARIABLES

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 Authentication
42           $ENV{HTTPS_PROXY_USERNAME} = 'username';
43           $ENV{HTTPS_PROXY_PASSWORD} = 'password';
44
45   SSL diagnostics and Debugging
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

INSTALL

64   OpenSSL
65       You must have OpenSSL installed before compiling this module. You can
66       get the latest OpenSSL package from <http://www.openssl.org/>. We no
67       longer support pre-2000 versions of OpenSSL.
68
69       If you are building OpenSSL from source, please follow the directions
70       included in the package.
71
72       If you are going to use an OpenSSL library which you built from source
73       or whose header and library files are not in a place searched by your
74       compiler by default, make sure you set appropriate environment
75       variables before trying to build "Crypt::SSLeay".
76
77       For example, if you are using ActiveState Perl and MinGW installed
78       using ppm, and you installed OpenSSL in "C:\opt\openssl-1.0.1c", then
79       you would issue the following commands to build "Crypt::SSLeay":
80
81           C:\...\> set LIBRARY_PATH=C:\opt\openssl-1.0.1c\lib;%LIBRARY_PATH%
82           C:\...\> set CPATH=C:\opt\openssl-1.0.1c\include;%CPATH%
83           C:\...\> perl Makefile.PL --live-tests
84           C:\...\> dmake test
85
86       On Linux/BSD/Solaris/GNU etc systems, you would use make rather than
87       dmake, but you would need to set the same variables if your OpenSSL
88       library is in a custom location. If everything builds OK, but you get
89       failures when during tests, ensure that "LD_LIBRARY_PATH" points to the
90       location where the correct shared libraries are located.
91
92       If you are using a Microsoft compiler (keep in mind that perl and
93       OpenSSL need to have been built using the same compiler as well), you
94       would use:
95
96           C:\...\> set LIB=C:\opt\openssl-1.0.1c\lib;%LIB%
97           C:\...\> set INCLUDE=C:\opt\openssl-1.0.1c\include;%INCLUDE%
98           C:\...\> perl Makefile.PL --live-tests
99           C:\...\> nmake test
100
101       Depending on your OS, pre-built OpenSSL packages may be available. You
102       may need to install a development version of your operating system's
103       OpenSSL library package. The key is that "Crypt::SSLeay" makes calls to
104       the OpenSSL library, and how to do so is specified in the C header
105       files that come with the library. Some systems break out the header
106       files into a separate package from that of the libraries. Once the
107       program has been built, you don't need the headers any more.
108
109   Crypt::SSLeay
110       The latest Crypt::SSLeay can be found at your nearest CPAN, as well as
111       <http://search.cpan.org/dist/Crypt-SSLeay/>.
112
113       Once you have downloaded it, "Crypt::SSLeay" installs easily using the
114       standard build process:
115
116           perl Makefile.PL
117           make
118           make test
119           make install
120
121       On Windows systems, both Strawberry Perl and ActiveState (as a separate
122       download via ppm) projects include a MingW based compiler distribution
123       and dmake which can be used to build both OpenSSL and "Crypt::SSLeay".
124       If you have such a set up, use dmake above.
125
126       Makefile.PL takes two optional arguments:
127
128       "--live-tests"
129           Boolean. Specifies whether we should try to connect to an HTTPS URL
130           during testing. Default is false.
131
132           To skip live tests, you can use
133
134               perl Makefile.PL --no-live-tests
135
136           and to force live tests, you can use
137
138               perl Makefile.PL --live-tests
139
140       "--static"
141           Boolean. Default is false. (TODO: Does it work?)
142
143       For unattended (batch) installations, to be absolutely certain that
144       Makefile.PL does not prompt for questions on STDIN, set the environment
145       variable "PERL_MM_USE_DEFAULT=1" as with any CPAN module built using
146       ExtUtils::MakeMaker.
147
148       Windows
149
150       "Crypt::SSLeay" builds correctly with Strawberry Perl and ActiveState
151       Perl using the bundled MinGW.
152
153       For ActiveState Perl users, the ActiveState company does not have a
154       permit from the Canadian Federal Government to distribute cryptographic
155       software.  This prevents "Crypt::SSLeay" from being distributed as a
156       PPM package from their repository.
157
158       See
159       <http://docs.activestate.com/activeperl/5.16/faq/ActivePerl-faq2.html#crypto_packages>
160       for more information on this issue. You may be able to download a PPM
161       for "Crypt::SSLeay" from an alternative repository (see
162       PPM::Repositories).
163
164       VMS
165
166       I do not have any experience with VMS. If OpenSSL headers and libraries
167       are not in standard locations searched by your build system by default,
168       please set things up so that they are. If you have generic instructions
169       on how to do it, please open a ticket on RT with the information so I
170       can add it to this document.
171

PROXY SUPPORT

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

CLIENT CERTIFICATE SUPPORT

219       Client certificates are supported. PEM encoded certificate and private
220       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 eg/net-ssl-test program, bundled with
226       the distribution, by issuing a command like:
227
228           perl eg/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 the CA file
232       is, you may set these.
233
234           $ENV{HTTPS_CA_FILE} = "some_file";
235           $ENV{HTTPS_CA_DIR}  = "some_dir";
236
237       Note that, if specified, $ENV{HTTPS_CA_FILE} must point to the actual
238       certificate file. That is, $ENV{HTTPS_CA_DIR} is *not* the path were
239       $ENV{HTTPS_CA_FILE} is located.
240
241       For certificates in $ENV{HTTPS_CA_DIR} to be picked up, follow the
242       instructions on
243       <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
244
245       There is no sample CA cert file at this time for testing, but you may
246       configure eg/net-ssl-test to use your CA cert with the -CAfile option.
247
248       (TODO: then what is the ./certs directory in the distribution?)
249
250   Creating a test certificate
251       To create simple test certificates with OpenSSL, you may run the
252       following command:
253
254           openssl req -config /usr/local/openssl/openssl.cnf \
255               -new -days 365 -newkey rsa:1024 -x509 \
256               -keyout notacakey.pem -out notacacert.pem
257
258       To remove the pass phrase from the key file, run:
259
260           openssl rsa -in notacakey.pem -out notacakeynopass.pem
261
262   PKCS12 support
263       The directives for enabling use of PKCS12 certificates is:
264
265           $ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
266           $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
267
268       Use of this type of certificate takes precedence over previous
269       certificate settings described.
270
271       (TODO: unclear? Meaning "the presence of this type of certificate"?)
272

SSL versions

274       "Crypt::SSLeay" tries very hard to connect to any SSL web server
275       accomodating servers that are buggy, old or simply not standards-
276       compliant. To this effect, this module will try SSL connections in this
277       order:
278
279       SSL v23
280           should allow v2 and v3 servers to pick their best type
281
282       SSL v3
283           best connection type
284
285       SSL v2
286           old connection type
287
288       Unfortunately, some servers seem not to handle a reconnect to SSL v3
289       after a failed connect of SSL v23 is tried, so you may set before using
290       LWP or Net::SSL:
291
292           $ENV{HTTPS_VERSION} = 3;
293
294       to force a version 3 SSL connection first. At this time only a version
295       2 SSL connection will be tried after this, as the connection attempt
296       order remains unchanged by this setting.
297

ACKNOWLEDGEMENTS

299       Many thanks to the following individuals who helped improve
300       "Crypt-SSLeay":
301
302       Gisle Aas for writing this module and many others including libwww, for
303       perl. The web will never be the same :)
304
305       Ben Laurie deserves kudos for his excellent patches for better error
306       handling, SSL information inspection, and random seeding.
307
308       Dongqiang Bai for host name resolution fix when using a proxy.
309
310       Stuart Horner of Core Communications, Inc. who found the need for
311       building "--shared" OpenSSL libraries.
312
313       Pavel Hlavnicka for a patch for freeing memory when using a pkcs12
314       file, and for inspiring more robust "read()" behavior.
315
316       James Woodyatt is a champ for finding a ridiculous memory leak that has
317       been the bane of many a Crypt::SSLeay user.
318
319       Bryan Hart for his patch adding proxy support, and thanks to Tobias
320       Manthey for submitting another approach.
321
322       Alex Rhomberg for Alpha linux ccc patch.
323
324       Tobias Manthey for his patches for client certificate support.
325
326       Daisuke Kuroda for adding PKCS12 certificate support.
327
328       Gamid Isayev for CA cert support and insights into error messaging.
329
330       Jeff Long for working through a tricky CA cert SSLClientVerify issue.
331
332       Chip Turner for a patch to build under perl 5.8.0.
333
334       Joshua Chamas for the time he spent maintaining the module.
335
336       Jeff Lavallee for help with alarms on read failures (CPAN bug #12444).
337
338       Guenter Knauf for significant improvements in configuring things in
339       Win32 and Netware lands and Jan Dubois for various suggestions for
340       improvements.
341
342       and many others who provided bug reports, suggestions, fixes and
343       patches.
344

SUPPORT

359       For use of "Crypt::SSLeay" & "Net::SSL" with Perl's LWP, please send
360       email to "libwww@perl.org".
361
362       For OpenSSL or general SSL support, including issues associated with
363       building and installing OpenSSL on your system, please email the
364       OpenSSL users mailing list at "openssl-users@openssl.org". See
365       <http://www.openssl.org/support/community.html> for other mailing lists
366       and archives.
367
368       Please report all bugs using rt.cpan.org
369       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>.
370

AUTHORS

372       This module was originally written by Gisle Aas, and was subsequently
373       maintained by Joshua Chamas, David Landgren, brian d foy and Sinan
374       Unur.
375

COPYRIGHT

377       Copyright (c) 2010-2012 A. Sinan Unur
378
379       Copyright (c) 2006-2007 David Landgren
380
381       Copyright (c) 1999-2003 Joshua Chamas
382
383       Copyright (c) 1998 Gisle Aas
384

LICENSE

386       This program is free software; you can redistribute it and/or modify it
387       under the terms of Artistic License 2.0 (see
388       <http://www.perlfoundation.org/artistic_license_2_0>).
389
390
391
392perl v5.16.3                      2012-08-06                         SSLeay(3)