Crypt::SSLeay(3pm)

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

NAME

6       Crypt::SSLeay - OpenSSL support for LWP
7

HEARTBLEED WARNING

9       "perl Makefile.PL" will display a warning if it thinks your OpenSSL
10       might be vulnerable to the  Heartbleed Bug <https://cve.mitre.org/cgi-
11       bin/cvename.cgi?name=CVE-2014-0160>. You can, of course, go ahead and
12       install the module, but you should be aware that your system might be
13       exposed to an extremely serious vulnerability. This is just a heuristic
14       based on the version reported by OpenSSL. It is entirely possible that
15       your distrbution actually pushed a patched library, so if you have
16       concerns, you should investigate further.
17

SYNOPSIS

19           use Net::SSL;
20           use LWP::UserAgent;
21
22           my $ua  = LWP::UserAgent->new(
23               ssl_opts => { verify_hostname => 0 },
24           );
25
26           my $response = $ua->get('https://www.example.com/');
27           print $response->content, "\n";
28

DESCRIPTION

30       This Perl module provides support for the HTTPS protocol under LWP, to
31       allow an LWP::UserAgent object to perform GET, HEAD, and POST requests
32       over encrypted socket connections. Please see LWP for more information
33       on POST requests.
34
35       The "Crypt::SSLeay" package provides "Net::SSL", which, if requested,
36       is loaded by "LWP::Protocol::https" for https requests and provides the
37       necessary SSL glue.
38
39       This distribution also makes following deprecated modules available:
40
41           Crypt::SSLeay::CTX
42           Crypt::SSLeay::Conn
43           Crypt::SSLeay::X509
44

DO YOU NEED Crypt::SSLeay?

46       Starting with version 6.02 of LWP, "https" support was unbundled into
47       LWP::Protocol::https. This module specifies as one of its prerequisites
48       IO::Socket::SSL which is automatically used by LWP::UserAgent unless
49       this preference is overridden separately. "IO::Socket::SSL" is a more
50       complete implementation, and, crucially, it allows hostname
51       verification.  "Crypt::SSLeay" does not support this. At this point,
52       "Crypt::SSLeay" is maintained to support existing software that already
53       depends on it.  However, it is possible that your software does not
54       really depend on "Crypt::SSLeay", only on the ability of
55       "LWP::UserAgent" class to communicate with sites over SSL/TLS.
56
57       If are using version "LWP" 6.02 or later, and therefore have installed
58       "LWP::Protocol::https" and its dependencies, and do not explicitly
59       "use" "Net::SSL" before loading "LWP::UserAgent", or override the
60       default socket class, you are probably using "IO::Socket::SSL" and do
61       not really need "Crypt::SSLeay".
62
63       If you have both "Crypt::SSLeay" and "IO::Socket::SSL" installed, and
64       would like to force "LWP::UserAgent" to use "Crypt::SSLeay", you can
65       use:
66
67           use Net::HTTPS;
68           $Net::HTTPS::SSL_SOCKET_CLASS = 'Net::SSL';
69           use LWP::UserAgent;
70
71       or
72
73           local $ENV{PERL_NET_HTTPS_SSL_SOCKET_CLASS} = 'Net::SSL';
74           use LWP::UserAgent;
75
76       or
77
78           use Net::SSL;
79           use LWP::UserAgent;
80

ENVIRONMENT VARIABLES

82       Specify SSL Socket Class
83           $ENV{PERL_NET_HTTPS_SSL_SOCKET_CLASS} can be used to instruct
84           "LWP::UserAgent" to use "Net::SSL" for HTTPS support rather than
85           "IO::Socket::SSL".
86
87       Proxy Support
88               $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
89
90       Proxy Basic Authentication
91               $ENV{HTTPS_PROXY_USERNAME} = 'username';
92               $ENV{HTTPS_PROXY_PASSWORD} = 'password';
93
94       SSL diagnostics and Debugging
95               $ENV{HTTPS_DEBUG} = 1;
96
97       Default SSL Version
98               $ENV{HTTPS_VERSION} = '3';
99
100       Client Certificate Support
101               $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
102               $ENV{HTTPS_KEY_FILE}  = 'certs/notacakeynopass.pem';
103
104       CA cert Peer Verification
105               $ENV{HTTPS_CA_FILE}   = 'certs/ca-bundle.crt';
106               $ENV{HTTPS_CA_DIR}    = 'certs/';
107
108       Client PKCS12 cert support
109               $ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
110               $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
111

INSTALL

113   OpenSSL
114       You must have OpenSSL installed before compiling this module. You can
115       get the latest OpenSSL package from <https://www.openssl.org/source/>.
116       We no longer support pre-2000 versions of OpenSSL.
117
118       If you are building OpenSSL from source, please follow the directions
119       included in the source package.
120
121   Crypt::SSLeay via Makefile.PL
122       "Makefile.PL" accepts the following command line arguments:
123
124       "incpath"
125           Path to OpenSSL headers. Can also be specified via
126           $ENV{OPENSSL_INCLUDE}.  If the command line argument is provided,
127           it overrides any value specified via the environment variable. Of
128           course, you can ignore both the command line argument and the
129           environment variable, and just add the path to your compiler
130           specific environment variable such as "CPATH" or "INCLUDE" etc.
131
132       "libpath"
133           Path to OpenSSL libraries. Can also be specified via
134           $ENV{OPENSSL_LIB}.  If the command line argument is provided, it
135           overrides any value specified by the environment variable. Of
136           course, you can ignore both the command line argument and the
137           environment variable and just add the path to your compiler
138           specific environment variable such as "LIBRARY_PATH" or "LIB" etc.
139
140       "live-tests"
141           Use "--live-tests" to request tests that try to connect to an
142           external web site, and "--no-live_tests" to prevent such tests from
143           running. If you run "Makefile.PL" interactively, and this argument
144           is not specified on the command line, you will be prompted for a
145           value.
146
147           Default is false.
148
149       "static"
150           Boolean. Default is false. TODO: Does it work?
151
152       "verbose"
153           Boolean. Default is false. If you pass "--verbose" on the command
154           line, both "Devel::CheckLib" and "ExtUtils::CBuilder" instances
155           will be configured to echo what they are doing.
156
157       If everything builds OK, but you get failures when during tests, ensure
158       that "LD_LIBRARY_PATH" points to the location where the correct shared
159       libraries are located.
160
161       If you are using a custom OpenSSL build, please keep in mind that
162       "Crypt::SSLeay" must be built using the same compiler and build tools
163       used to build "perl" and OpenSSL. This can be more of an issue on
164       Windows. If you are using Active State Perl, install the MinGW package
165       distributed by them, and build OpenSSL using that before trying to
166       build this module. If you have built your own Perl using Microsoft SDK
167       tools or IDEs, make sure you build OpenSSL using the same tools.
168
169       Depending on your OS, pre-built OpenSSL packages may be available. To
170       get the require headers and import libraries, you may need to install a
171       development version of your operating system's OpenSSL library package.
172       The key is that "Crypt::SSLeay" makes calls to the OpenSSL library, and
173       how to do so is specified in the C header files that come with the
174       library. Some systems break out the header files into a separate
175       package from that of the libraries. Once the program has been built,
176       you don't need the headers any more.
177
178   Crypt::SSLeay
179       The latest Crypt::SSLeay can be found at your nearest CPAN mirror, as
180       well as <https://metacpan.org/pod/Crypt::SSLeay>.
181
182       Once you have downloaded it, "Crypt::SSLeay" installs easily using the
183       standard build process:
184
185           $ perl Makefile.PL
186           $ make
187           $ make test
188           $ make install
189
190       or
191
192           $ cpanm Crypt::SSLeay
193
194       If you have OpenSSL headers and libraries in nonstandard locations, you
195       can use
196
197           $ perl Makefile.PL --incpath=... --libpath=...
198
199       If you would like to use "cpanm" with such custom locations, you can do
200
201           $ OPENSSL_INCLUDE=... OPENSSL_LIB=... cpanm Crypt::SSLeay
202
203       or, on Windows,
204
205           > set OPENSSL_INCLUDE=...
206           > set OPENSSL_LIB=...
207           > cpanm Crypt::SSLeay
208
209       If you are on Windows, and using a MinGW distribution bundled with
210       ActiveState Perl or Strawberry Perl, you would use "dmake" rather than
211       "make". If you are using Microsoft's build tools, you would use
212       "nmake".
213
214       For unattended (batch) installations, to be absolutely certain that
215       Makefile.PL does not prompt for questions on STDIN, set the environment
216       variable "PERL_MM_USE_DEFAULT=1" as with any CPAN module built using
217       ExtUtils::MakeMaker.
218
219       VMS
220
221       I do not have any experience with VMS. If OpenSSL headers and libraries
222       are not in standard locations searched by your build system by default,
223       please set things up so that they are. If you have generic instructions
224       on how to do it, please open a ticket on RT with the information so I
225       can add it to this document.
226

PROXY SUPPORT

228       LWP::UserAgent and Crypt::SSLeay have their own versions of proxy
229       support. Please read these sections to see which one is appropriate.
230
231   LWP::UserAgent proxy support
232       "LWP::UserAgent" has its own methods of proxying which may work for you
233       and is likely to be incompatible with "Crypt::SSLeay" proxy support.
234       To use "LWP::UserAgent" proxy support, try something like:
235
236           my $ua = LWP::UserAgent->new;
237           $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port");
238
239       At the time of this writing, libwww v5.6 seems to proxy https requests
240       fine with an Apache mod_proxy server.  It sends a line like:
241
242           GET https://www.example.com HTTP/1.1
243
244       to the proxy server, which is not the "CONNECT" request that some
245       proxies would expect, so this may not work with other proxy servers
246       than mod_proxy. The "CONNECT" method is used by "Crypt::SSLeay"'s
247       internal proxy support.
248
249   Crypt::SSLeay proxy support
250       For native "Crypt::SSLeay" proxy support of https requests, you need to
251       set the environment variable "HTTPS_PROXY" to your proxy server and
252       port, as in:
253
254           # proxy support
255           $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
256           $ENV{HTTPS_PROXY} = '127.0.0.1:8080';
257
258       Use of the "HTTPS_PROXY" environment variable in this way is similar to
259       "LWP::UserAgent-"env_proxy()> usage, but calling that method will
260       likely override or break the "Crypt::SSLeay" support, so do not mix the
261       two.
262
263       Basic auth credentials to the proxy server can be provided this way:
264
265           # proxy_basic_auth
266           $ENV{HTTPS_PROXY_USERNAME} = 'username';
267           $ENV{HTTPS_PROXY_PASSWORD} = 'password';
268
269       For an example of LWP scripting with "Crypt::SSLeay" native proxy
270       support, please look at the eg/lwp-ssl-test script in the
271       "Crypt::SSLeay" distribution.
272

CLIENT CERTIFICATE SUPPORT

274       Client certificates are supported. PEM encoded certificate and private
275       key files may be used like this:
276
277           $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
278           $ENV{HTTPS_KEY_FILE}  = 'certs/notacakeynopass.pem';
279
280       You may test your files with the eg/net-ssl-test program, bundled with
281       the distribution, by issuing a command like:
282
283           perl eg/net-ssl-test -cert=certs/notacacert.pem \
284               -key=certs/notacakeynopass.pem -d GET $HOST_NAME
285
286       Additionally, if you would like to tell the client where the CA file
287       is, you may set these.
288
289           $ENV{HTTPS_CA_FILE} = "some_file";
290           $ENV{HTTPS_CA_DIR}  = "some_dir";
291
292       Note that, if specified, $ENV{HTTPS_CA_FILE} must point to the actual
293       certificate file. That is, $ENV{HTTPS_CA_DIR} is *not* the path were
294       $ENV{HTTPS_CA_FILE} is located.
295
296       For certificates in $ENV{HTTPS_CA_DIR} to be picked up, follow the
297       instructions on
298       <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
299
300       There is no sample CA cert file at this time for testing, but you may
301       configure eg/net-ssl-test to use your CA cert with the -CAfile option.
302
303       (TODO: then what is the ./certs directory in the distribution?)
304
305   Creating a test certificate
306       To create simple test certificates with OpenSSL, you may run the
307       following command:
308
309           openssl req -config /usr/local/openssl/openssl.cnf \
310               -new -days 365 -newkey rsa:1024 -x509 \
311               -keyout notacakey.pem -out notacacert.pem
312
313       To remove the pass phrase from the key file, run:
314
315           openssl rsa -in notacakey.pem -out notacakeynopass.pem
316
317   PKCS12 support
318       The directives for enabling use of PKCS12 certificates is:
319
320           $ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
321           $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';
322
323       Use of this type of certificate takes precedence over previous
324       certificate settings described.
325
326       (TODO: unclear? Meaning "the presence of this type of certificate"?)
327

SSL versions

329       "Crypt::SSLeay" tries very hard to connect to any SSL web server
330       accommodating servers that are buggy, old or simply not standards-
331       compliant.  To this effect, this module will try SSL connections in
332       this order:
333
334       SSL v23
335           should allow v2 and v3 servers to pick their best type
336
337       SSL v3
338           best connection type
339
340       SSL v2
341           old connection type
342
343       Unfortunately, some servers seem not to handle a reconnect to SSL v3
344       after a failed connect of SSL v23 is tried, so you may set before using
345       LWP or Net::SSL:
346
347           $ENV{HTTPS_VERSION} = 3;
348
349       to force a version 3 SSL connection first. At this time only a version
350       2 SSL connection will be tried after this, as the connection attempt
351       order remains unchanged by this setting.
352

ACKNOWLEDGEMENTS

354       Many thanks to the following individuals who helped improve
355       "Crypt-SSLeay":
356
357       Gisle Aas for writing this module and many others including libwww, for
358       perl. The web will never be the same :)
359
360       Ben Laurie deserves kudos for his excellent patches for better error
361       handling, SSL information inspection, and random seeding.
362
363       Dongqiang Bai for host name resolution fix when using a proxy.
364
365       Stuart Horner of Core Communications, Inc. who found the need for
366       building "--shared" OpenSSL libraries.
367
368       Pavel Hlavnicka for a patch for freeing memory when using a pkcs12
369       file, and for inspiring more robust "read()" behavior.
370
371       James Woodyatt is a champ for finding a ridiculous memory leak that has
372       been the bane of many a Crypt::SSLeay user.
373
374       Bryan Hart for his patch adding proxy support, and thanks to Tobias
375       Manthey for submitting another approach.
376
377       Alex Rhomberg for Alpha linux ccc patch.
378
379       Tobias Manthey for his patches for client certificate support.
380
381       Daisuke Kuroda for adding PKCS12 certificate support.
382
383       Gamid Isayev for CA cert support and insights into error messaging.
384
385       Jeff Long for working through a tricky CA cert SSLClientVerify issue.
386
387       Chip Turner for a patch to build under perl 5.8.0.
388
389       Joshua Chamas for the time he spent maintaining the module.
390
391       Jeff Lavallee for help with alarms on read failures (CPAN bug #12444).
392
393       Guenter Knauf for significant improvements in configuring things in
394       Win32 and Netware lands and Jan Dubois for various suggestions for
395       improvements.
396
397       and many others who provided bug reports, suggestions, fixes and
398       patches.
399
400       If you have reported a bug or provided feedback, and you would like to
401       be mentioned by name in this section, please file request on
402       rt.cpan.org <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>.
403

SUPPORT

420       For issues related to using of "Crypt::SSLeay" & "Net::SSL" with Perl's
421       LWP, please send email to "libwww@perl.org".
422
423       For OpenSSL or general SSL support, including issues associated with
424       building and installing OpenSSL on your system, please email the
425       OpenSSL users mailing list at "openssl-users@openssl.org". See
426       <http://www.openssl.org/support/community.html> for other mailing lists
427       and archives.
428
429       Please report all bugs using rt.cpan.org
430       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>.
431

AUTHORS

433       This module was originally written by Gisle Aas, and was subsequently
434       maintained by Joshua Chamas, David Landgren, brian d foy and Sinan
435       Unur.
436

COPYRIGHT

438       Copyright (c) 2010-2014 A. Sinan Unur
439
440       Copyright (c) 2006-2007 David Landgren
441
442       Copyright (c) 1999-2003 Joshua Chamas
443
444       Copyright (c) 1998 Gisle Aas
445

LICENSE

447       This program is free software; you can redistribute it and/or modify it
448       under the terms of Artistic License 2.0 (see
449       <http://www.perlfoundation.org/artistic_license_2_0>).
450
451
452
453perl v5.34.0                      2022-03-22                         SSLeay(3)