1# Crypt::SSLeay - OpenSSL support for LWP 2 3## Synopsis 4 5 lwp-request https://www.example.com 6 7 use LWP::UserAgent; 8 my $ua = LWP::UserAgent->new; 9 my $response = $ua->get('https://www.example.com/'); 10 print $response->content, "\n"; 11 12## Description 13 14this Perl module provides support for the HTTPS protocol under LWP, to allow 15an "LWP::UserAgent" object to perform GET, HEAD and POST requests. Please 16see LWP for more information on POST requests. 17 18The "Crypt::SSLeay" package provides "Net::SSL", which is loaded by 19"LWP::Protocol::https" for https requests and provides the necessary SSL 20glue. 21 22This distribution also makes following deprecated modules available: 23 24 Crypt::SSLeay::CTX 25 Crypt::SSLeay::Conn 26 Crypt::SSLeay::X509 27 28Work on Crypt::SSLeay has been continued only to provide https support 29for the LWP (libwww-perl) libraries. 30 31## Environment Variables 32 33the following environment variables change the way "Crypt::SSLeay" and 34"Net::SSL" behave. 35 36### Proxy Support 37 38 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port'; 39 40### Proxy Basic Authentication 41 42 $ENV{HTTPS_PROXY_USERNAME} = 'username'; 43 $ENV{HTTPS_PROXY_PASSWORD} = 'password'; 44 45### SSL Diagnostics and Debugging 46 47 $ENV{HTTPS_DEBUG} = 1; 48 49### Default SSL Version 50 51 $ENV{HTTPS_VERSION} = '3'; 52 53### Client Certificate Support 54 55 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem'; 56 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem'; 57 58### CA cert peer verification 59 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 67## Installation 68 69### OpenSSL 70 71You must have OpenSSL installed before compiling this module. You can 72get the latest OpenSSL package from <http://www.openssl.org/>. We no longer 73support pre-2000 versions of OpenSSL. 74 75If you are building OpenSSL from source, please follow the directions 76included in the package. 77 78If you are going to use an OpenSSL library which you built from source or 79whose header and library files are not in a place searched by your compiler 80by default, make sure you set appropriate environment variables before 81trying to build `Crypt::SSLeay`. 82 83For example, if you are using ActiveState Perl and MinGW installed using 84ppm, and you installed OpenSSL in `C:\opt\openssl-1.0.1c`, then you would 85issue the following commands to build `Crypt::SSLeay`: 86 87 C:\temp\Crypt-SSLeay> set LIBRARY_PATH=C:\opt\openssl-1.0.1c\lib;%LIBRARY_PATH% 88 C:\temp\Crypt-SSLeay> set CPATH=C:\opt\openssl-1.0.1c\include;%CPATH% 89 C:\temp\Crypt-SSLeay> perl Makefile.PL --live-tests 90 C:\temp\Crypt-SSLeay> dmake test 91 92On Linux/BSD/Solaris/GNU etc systems, you would use `make` rather than 93`dmake`, but you would need to set the same variables if your OpenSSL 94library is in a custom location. If everything builds OK, but you get 95failures when during tests, ensure that `LD_LIBRARY_PATH` points to the 96location where the correct shared libraries are located. 97 98If you are using a Microsoft compiler (keep in mind that `perl` and OpenSSL 99need to have been built using the same compiler as well), you would use: 100 101 C:\temp\Crypt-SSLeay> set LIB=C:\opt\openssl-1.0.1c\lib;%LIB% 102 C:\temp\Crypt-SSLeay> set INCLUDE=C:\opt\openssl-1.0.1c\include;%INCLUDE% 103 C:\temp\Crypt-SSLeay> perl Makefile.PL --live-tests 104 C:\temp\Crypt-SSLeay> nmake test 105 106Depending on your OS, pre-built OpenSSL packages may be available. You may 107need to install a development version of your operating system's OpenSSL 108library package. The key is that Crypt::SSLeay makes calls to the OpenSSL 109library, and how to do so is specified in the C header files that come 110with the library. Some systems break out the header files into a separate 111package from that of the libraries. Once the program has been built, you 112don't need the headers any more. 113 114### `Crypt::SSLeay` 115 116The latest `Crypt::SSLeay` can be found at your nearest CPAN, as well as 117<http://search.cpan.org/dist/Crypt-SSLeay/>. 118 119Once you have downloaded it, `Crypt::SSLeay` installs easily using the 120standard build process: 121 122 perl Makefile.PL 123 make 124 make test 125 make install 126 127On Windows systems, both Strawberry Perl and ActiveState (as a separate 128download via ppm) projects include a MingW based compiler distribution and 129dmake which can be used to build both OpenSSL and `Crypt::SSLeay`. If you have 130such a set up, use dmake above. 131 132Makefile.PL takes two optional arguments: 133 134* `--live-tests` : Boolean. Specifies whether we should try to connect to 135 an HTTPS URL during testing. Default is false. 136 137 To skip live tests, you can use 138 139 perl Makefile.PL --no-live-tests 140 141 and to force live tests, you can use 142 143 perl Makefile.PL --live-tests 144 145* `--static` : Boolean. Default is false. (TODO: Does it work?) 146 147For unattended (batch) installations, to be absolutely certain that 148`Makefile.PL` does not prompt for questions on `STDIN`, set the environment 149variable `PERL_MM_USE_DEFAULT=1` as with any CPAN module built using 150`ExtUtils::MakeMaker`. 151 152### Windows 153 154`Crypt::SSLeay` builds correctly with Strawberry Perl and ActiveState Perl 155using the bundled MinGW. 156 157For ActiveState Perl users, the ActiveState company does not have a 158permit from the Canadian Federal Government to distribute cryptographic 159software. This prevents `Crypt::SSLeay` from being distributed as a PPM 160package from their repository. See <http://docs.activestate.com/activeperl/5.16/faq/ActivePerl-faq2.html#crypto_packages> 161for more information on this issue. You may be able to download a PPM for 162`Crypt::SSLeay` from an alternative repository (see `PPM::Repositories`). 163 164### VMS 165 166I do not have any experience with VMS. If OpenSSL headers and libraries are 167not in standard locations searched by your build system by default, please 168set things up so that they are. If you have generic instructions on how to 169do it, please open a ticket on RT with the information so I can add it to 170this document. 171 172## Proxy Support 173 174`LWP::UserAgent` and `Crypt::SSLeay` have their own versions of proxy 175support. Please read these sections to see which one is appropriate. 176 177### `LWP::UserAgent` proxy support 178 179`LWP::UserAgent` has its own methods of proxying which may work for you and 180is likely to be incompatible with `Crypt::SSLeay` proxy support. To use 181`LWP::UserAgent` proxy support, try something like: 182 183 my $ua = LWP::UserAgent->new; 184 $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port"); 185 186At the time of this writing, libwww v5.6 seems to proxy https requests fine 187with an Apache mod_proxy server. It sends a line like: 188 189 GET https://www.example.com HTTP/1.1 190 191to the proxy server, which is not the `CONNECT` request that some proxies 192would expect, so this may not work with other proxy servers than mod_proxy. 193The `CONNECT` method is used by `Crypt::SSLeay`'s internal proxy support. 194 195### `Crypt::SSLeay` proxy support 196 197For native `Crypt::SSLeay` proxy support of https requests, you need to set 198the environment variable `HTTPS_PROXY` to your proxy server and port, as 199in: 200 201 # proxy support 202 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port'; 203 $ENV{HTTPS_PROXY} = '127.0.0.1:8080'; 204 205Use of the `HTTPS_PROXY` environment variable in this way is similar to 206`LWP::UserAgent->env_proxy()` usage, but calling that method will likely 207override or break the `Crypt::SSLeay` support, so do not mix the two. 208 209Basic authentication credentials to the proxy server can be provided this 210way: 211 212 # proxy_basic_auth 213 $ENV{HTTPS_PROXY_USERNAME} = 'username'; 214 $ENV{HTTPS_PROXY_PASSWORD} = 'password'; 215 216For an example of LWP scripting with `Crypt::SSLeay` native proxy support, 217please look at the `eg/lwp-ssl-test` script in the `Crypt::SSLeay` 218distribution. 219 220## Client Certificate Support 221 222Client certificates are supported. PEM encoded certificate and private key 223files may be used like this: 224 225 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem'; 226 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem'; 227 228You may test your files with the `eg/net-ssl-test` program, bundled with the 229distribution, by issuing a command like: 230 231 perl eg/net-ssl-test -cert=certs/notacacert.pem \ 232 -key=certs/notacakeynopass.pem -d GET $HOST_NAME 233 234Additionally, if you would like to tell the client where the CA file is, you 235may set these. 236 237 $ENV{HTTPS_CA_FILE} = "some_file"; 238 $ENV{HTTPS_CA_DIR} = "some_dir"; 239 240Note that, if specified, `$ENV{HTTPS_CA_FILE}` must point to the actual 241certificate file. That is, `$ENV{HTTPS_CA_DIR}` is *not* the path where 242`$ENV{HTTPS_CA_FILE}` is located. 243 244For certificates in `$ENV{HTTPS_CA_DIR}` to be picked up, follow the 245instructions on <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>. 246 247There is no sample CA cert file at this time for testing, but you may 248configure `eg/net-ssl-test` to use your CA cert with the -CAfile option. 249(TODO: then what is the ./certs directory in the distribution?) 250 251### Creating a test certificate 252 253To create simple test certificates with OpenSSL, you may run the following 254command: 255 256 openssl req -config /usr/local/openssl/openssl.cnf \ 257 -new -days 365 -newkey rsa:1024 -x509 \ 258 -keyout notacakey.pem -out notacacert.pem 259 260To remove the pass phrase from the key file, run: 261 262 openssl rsa -in notacakey.pem -out notacakeynopass.pem 263 264### PKCS12 support 265 266The directives for enabling use of PKCS12 certificates is: 267 268 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12'; 269 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD'; 270 271Use of this type of certificate takes precedence over previous certificate 272settings described. (TODO: unclear? Meaning "the presence of this type of 273certificate"?) 274 275## SSL versions 276 277`Crypt::SSLeay` tries very hard to connect to *any* SSL web server 278accomodating servers that are buggy, old or simply not standards-compliant. 279To this effect, this module will try SSL connections in this order: 280 281* SSL v23 : should allow v2 and v3 servers to pick their best type 282 283* SSL v3 : best connection type 284 285* SSL v2 : old connection type 286 287Unfortunately, some servers seem not to handle a reconnect to SSL v3 after a 288failed connect of SSL v23 is tried, so you may set before using LWP or 289`Net::SSL`: 290 291 $ENV{HTTPS_VERSION} = 3; 292 293to force a version 3 SSL connection first. At this time, only a version 2 SSL 294connection will be tried after this, as the connection attempt order remains 295unchanged by this setting. 296 297## Acknowledgements 298 299many thanks to the following individuals who helped improve Crypt-SSLeay: 300 301* _Gisle Aas_ for writing this module and many others including libwww, 302for perl. The web will never be the same :) 303 304* _Ben Laurie_ deserves kudos for his excellent patches for better error 305handling, SSL information inspection, and random seeding. 306 307* _Dongqiang Bai_ for host name resolution fix when using a proxy. 308 309* _Stuart Horner_ of Core Communications, Inc. who found the need for 310building `--shared` OpenSSL libraries. 311 312* _Pavel Hlavnicka_ for a patch for freeing memory when using a pkcs12 313file, and for inspiring more robust `read()` behavior. 314 315* _James Woodyatt_ is a champ for finding a ridiculous memory leak that 316has been the bane of many a `Crypt::SSLeay` user. 317 318* _Bryan Hart_ for his patch adding proxy support, and thanks to _Tobias 319Manthey_ for submitting another approach. 320 321* _Alex Rhomberg_ for Alpha linux ccc patch. 322 323* _Tobias Manthey_ for his patches for client certificate support. 324 325* _Daisuke Kuroda_ for adding PKCS12 certificate support. 326 327* _Gamid Isayev_ for CA cert support and insights into error messaging. 328 329* _Jeff Long_ for working through a tricky CA cert SSLClientVerify issue. 330 331* _Chip Turner_ for a patch to build under perl 5.8.0. 332 333* _Joshua Chamas_ for the time he spent maintaining the module. 334 335* _Jeff Lavallee_ for help with alarms on read failures (CPAN bug #12444). 336 337* _Guenter Knauf_ for significant improvements in configuring things in 338Win32 and Netware lands and Jan Dubois for various suggestions for 339improvements. 340 341and _many others_ who provided bug reports, suggestions, fixes and 342patches. 343 344### TODO: Update acknowledgements list. 345 346## See Also 347 348* `Net::SSL` 349 350 If you have downloaded this distribution as of a dependency of 351 another distribution, it's probably due to this module (which is 352 included in this distribution). 353 354* `Net::SSLeay` 355 356 Net::SSLeay provides access to the OpenSSL API directly from Perl. 357 See <http://search.cpan.org/dist/Net-SSLeay/>. 358 359* OpenSSL binary packages for Windows, see 360 <http://www.openssl.org/related/binaries.html>. 361 362## Support 363 364* For use of `Crypt::SSLeay` & `Net::SSL` with Perl's LWP, please send email 365 to libwww@perl.org <mailto:libwww@perl.org>. 366 367* For OpenSSL or general SSL support, including issues associated with 368 building and installing OpenSSL on your system, please email the OpenSSL 369 users mailing list at openssl-users@openssl.org 370 <mailto:openssl-users@openssl.org>. See 371 <http://www.openssl.org/support/community.html> for other mailing lists 372 and archives. 373 374* Please report all bugs at 375 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>. 376 377## Authors 378 379This module was originally written by Gisle Aas, and was subsequently 380maintained by Joshua Chamas, David Landgren, brian d foy, and A. Sinan 381Unur. 382 383## Copyright 384 385Copyright © 2010-2012 A. Sinan Unur 386 387Copyright © 2006-2007 David Landgren 388 389Copyright © 1999-2003 Joshua Chamas 390 391Copyright © 1998 Gisle Aas 392 393## License 394 395this program is free software; you can redistribute it and/or modify it 396under the terms of Artistic License 2.0. See <http://www.perlfoundation.org/artistic_license_2_0>. 397 398