1package Crypt::SSLeay; 2 3use strict; 4use vars '$VERSION'; 5$VERSION = '0.57'; 6 7eval { 8 require XSLoader; 9 XSLoader::load('Crypt::SSLeay', $VERSION); 10 1; 11} 12or do { 13 require DynaLoader; 14 use vars '@ISA'; # not really locally scoped, it just looks that way 15 @ISA = qw(DynaLoader); 16 bootstrap Crypt::SSLeay $VERSION; 17}; 18 19use vars qw(%CIPHERS); 20%CIPHERS = ( 21 'NULL-MD5' => "No encryption with a MD5 MAC", 22 'RC4-MD5' => "128 bit RC4 encryption with a MD5 MAC", 23 'EXP-RC4-MD5' => "40 bit RC4 encryption with a MD5 MAC", 24 'RC2-CBC-MD5' => "128 bit RC2 encryption with a MD5 MAC", 25 'EXP-RC2-CBC-MD5' => "40 bit RC2 encryption with a MD5 MAC", 26 'IDEA-CBC-MD5' => "128 bit IDEA encryption with a MD5 MAC", 27 'DES-CBC-MD5' => "56 bit DES encryption with a MD5 MAC", 28 'DES-CBC-SHA' => "56 bit DES encryption with a SHA MAC", 29 'DES-CBC3-MD5' => "192 bit EDE3 DES encryption with a MD5 MAC", 30 'DES-CBC3-SHA' => "192 bit EDE3 DES encryption with a SHA MAC", 31 'DES-CFB-M1' => "56 bit CFB64 DES encryption with a one byte MD5 MAC", 32); 33 34use Crypt::SSLeay::X509; 35 36# A xsupp bug made this nessesary 37sub Crypt::SSLeay::CTX::DESTROY { shift->free; } 38sub Crypt::SSLeay::Conn::DESTROY { shift->free; } 39sub Crypt::SSLeay::X509::DESTROY { shift->free; } 40 411; 42 43__END__ 44 45=head1 NAME 46 47Crypt::SSLeay - OpenSSL support for LWP 48 49=head1 SYNOPSIS 50 51 lwp-request https://www.example.com 52 53 use LWP::UserAgent; 54 my $ua = LWP::UserAgent->new; 55 my $req = HTTP::Request->new('GET', 'https://www.example.com/'); 56 my $res = $ua->request($req); 57 print $res->content, "\n"; 58 59=head1 DESCRIPTION 60 61This document describes C<Crypt::SSLeay> version 0.57, released 622007-09-17. 63 64This perl module provides support for the https protocol under LWP, 65to allow an C<LWP::UserAgent> object to perform GET, HEAD and POST 66requests. Please see LWP for more information on POST requests. 67 68The C<Crypt::SSLeay> package provides C<Net::SSL>, which is loaded 69by C<LWP::Protocol::https> for https requests and provides the 70necessary SSL glue. 71 72This distribution also makes following deprecated modules available: 73 74 Crypt::SSLeay::CTX 75 Crypt::SSLeay::Conn 76 Crypt::SSLeay::X509 77 78Work on Crypt::SSLeay has been continued only to provide https 79support for the LWP (libwww-perl) libraries. 80 81=head1 ENVIRONMENT VARIABLES 82 83The following environment variables change the way 84C<Crypt::SSLeay> and C<Net::SSL> behave. 85 86 # proxy support 87 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port'; 88 89 # proxy_basic_auth 90 $ENV{HTTPS_PROXY_USERNAME} = 'username'; 91 $ENV{HTTPS_PROXY_PASSWORD} = 'password'; 92 93 # debugging (SSL diagnostics) 94 $ENV{HTTPS_DEBUG} = 1; 95 96 # default ssl version 97 $ENV{HTTPS_VERSION} = '3'; 98 99 # client certificate support 100 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem'; 101 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem'; 102 103 # CA cert peer verification 104 $ENV{HTTPS_CA_FILE} = 'certs/ca-bundle.crt'; 105 $ENV{HTTPS_CA_DIR} = 'certs/'; 106 107 # Client PKCS12 cert support 108 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12'; 109 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD'; 110 111=head1 INSTALL 112 113=head2 OpenSSL 114 115You must have OpenSSL or SSLeay installed before compiling 116this module. You can get the latest OpenSSL package from: 117 118 http://www.openssl.org/ 119 120On Debian systems, you will need to install the libssl-dev package, 121at least for the duration of the build (it may be removed afterwards). 122 123Other package-based systems may require something similar. The key 124is that Crypt::SSLeay makes calls to the OpenSSL library, and how 125to do so is specified in the C header files that come with the 126library. Some systems break out the header files into a separate 127package from that of the libraries. Once the program has been built, 128you don't need the headers any more. 129 130When installing openssl make sure your config looks like: 131 132 ./config --openssldir=/usr/local/openssl 133 or 134 ./config --openssldir=/usr/local/ssl 135 136If you are planning on upgrading the default OpenSSL libraries on 137a system like RedHat, (not recommended), then try something like: 138 139 ./config --openssldir=/usr --shared 140 141The --shared option to config will set up building the .so 142shared libraries which is important for such systems. This is 143followed by: 144 145 make 146 make test 147 make install 148 149This way Crypt::SSLeay will pick up the includes and 150libraries automatically. If your includes end up 151going into a separate directory like /usr/local/include, 152then you may need to symlink /usr/local/openssl/include 153to /usr/local/include 154 155=head2 Crypt::SSLeay 156 157The latest Crypt::SSLeay can be found at your nearest CPAN, 158as well as: 159 160 http://search.cpan.org/dist/Crypt-SSLeay/ 161 162Once you have downloaded it, Crypt::SSLeay installs easily 163using the C<make> * commands as shown below. 164 165 perl Makefile.PL 166 make 167 make test 168 make install 169 170 * use nmake or dmake on Win32 171 172For unattended (batch) installations, to be absolutely certain that 173F<Makefile.PL> does not prompt for questions on STDIN, set the 174following environment variable beforehand: 175 176 PERL_MM_USE_DEFAULT=1 177 178(This is true for any CPAN module that uses C<ExtUtils::MakeMaker>). 179 180=head3 Windows 181 182C<Crypt::SSLeay> builds correctly with Strawberry Perl. 183 184For Activestate users, the ActiveState company does not have a 185permit from the Canadian Federal Government to distribute cryptographic 186software. This prevents C<Crypt::SSLeay> from being distributed as 187a PPM package from their repository. See 188L<http://aspn.activestate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-faq2.html#crypto_packages> 189for more information on this issue. 190 191You may download it from Randy Kobes's PPM repository by using 192the following command: 193 194 ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd 195 196An alternative is to add the uwinnipeg.ca PPM repository to your 197local installation. See L<http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html> 198for more details. 199 200=head3 VMS 201 202It is assumed that the OpenSSL installation is located at 203C</ssl$root>. Define this logical to point to the appropriate 204place in the filesystem. 205 206=head1 PROXY SUPPORT 207 208LWP::UserAgent and Crypt::SSLeay have their own versions of 209proxy support. Please read these sections to see which one 210is appropriate. 211 212=head2 LWP::UserAgent proxy support 213 214LWP::UserAgent has its own methods of proxying which may work for 215you and is likely to be incompatible with Crypt::SSLeay proxy support. 216To use LWP::UserAgent proxy support, try something like: 217 218 my $ua = new LWP::UserAgent; 219 $ua->proxy([qw( https http )], "$proxy_ip:$proxy_port"); 220 221At the time of this writing, libwww v5.6 seems to proxy https 222requests fine with an Apache mod_proxy server. It sends a line like: 223 224 GET https://www.example.com HTTP/1.1 225 226to the proxy server, which is not the CONNECT request that 227some proxies would expect, so this may not work with other 228proxy servers than mod_proxy. The CONNECT method is used 229by Crypt::SSLeay's internal proxy support. 230 231=head2 Crypt::SSLeay proxy support 232 233For native Crypt::SSLeay proxy support of https requests, 234you need to set the environment variable C<HTTPS_PROXY> to your 235proxy server and port, as in: 236 237 # proxy support 238 $ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port'; 239 $ENV{HTTPS_PROXY} = '127.0.0.1:8080'; 240 241Use of the C<HTTPS_PROXY> environment variable in this way 242is similar to C<LWP::UserAgent->env_proxy()> usage, but calling 243that method will likely override or break the Crypt::SSLeay 244support, so do not mix the two. 245 246Basic auth credentials to the proxy server can be provided 247this way: 248 249 # proxy_basic_auth 250 $ENV{HTTPS_PROXY_USERNAME} = 'username'; 251 $ENV{HTTPS_PROXY_PASSWORD} = 'password'; 252 253For an example of LWP scripting with C<Crypt::SSLeay> native proxy 254support, please look at the F<eg/lwp-ssl-test> script in the 255C<Crypt::SSLeay> distribution. 256 257=head1 CLIENT CERTIFICATE SUPPORT 258 259Client certificates are supported. PEM0encoded certificate and 260private key files may be used like this: 261 262 $ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem'; 263 $ENV{HTTPS_KEY_FILE} = 'certs/notacakeynopass.pem'; 264 265You may test your files with the F<eg/net-ssl-test> program, 266bundled with the distribution, by issuing a command like: 267 268 perl eg/net-ssl-test -cert=certs/notacacert.pem \ 269 -key=certs/notacakeynopass.pem -d GET $HOST_NAME 270 271Additionally, if you would like to tell the client where 272the CA file is, you may set these. 273 274 $ENV{HTTPS_CA_FILE} = "some_file"; 275 $ENV{HTTPS_CA_DIR} = "some_dir"; 276 277There is no sample CA cert file at this time for testing, 278but you may configure F<eg/net-ssl-test> to use your CA cert 279with the -CAfile option. (TODO: then what is the ./certs 280directory in the distribution?) 281 282=head2 Creating a test certificate 283 284To create simple test certificates with OpenSSL, you may 285run the following command: 286 287 openssl req -config /usr/local/openssl/openssl.cnf \ 288 -new -days 365 -newkey rsa:1024 -x509 \ 289 -keyout notacakey.pem -out notacacert.pem 290 291To remove the pass phrase from the key file, run: 292 293 openssl rsa -in notacakey.pem -out notacakeynopass.pem 294 295=head2 PKCS12 support 296 297The directives for enabling use of PKCS12 certificates is: 298 299 $ENV{HTTPS_PKCS12_FILE} = 'certs/pkcs12.pkcs12'; 300 $ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD'; 301 302Use of this type of certificate takes precedence over previous 303certificate settings described. (TODO: unclear? Meaning "the 304presence of this type of certificate??) 305 306=head1 SSL versions 307 308Crypt::SSLeay tries very hard to connect to I<any> SSL web server 309accomodating servers that are buggy, old or simply 310not standards-compliant. To this effect, this module will 311try SSL connections in this order: 312 313 SSL v23 - should allow v2 and v3 servers to pick their best type 314 SSL v3 - best connection type 315 SSL v2 - old connection type 316 317Unfortunately, some servers seem not to handle a reconnect 318to SSL v3 after a failed connect of SSL v23 is tried, 319so you may set before using LWP or Net::SSL: 320 321 $ENV{HTTPS_VERSION} = 3; 322 323to force a version 3 SSL connection first. At this time only a 324version 2 SSL connection will be tried after this, as the connection 325attempt order remains unchanged by this setting. 326 327=head1 ACKNOWLEDGEMENTS 328 329Many thanks to Gisle Aas for writing this module and many others 330including libwww, for perl. The web will never be the same :) 331 332Ben Laurie deserves kudos for his excellent patches for better error 333handling, SSL information inspection, and random seeding. 334 335Thanks to Dongqiang Bai for host name resolution fix when using a 336proxy. 337 338Thanks to Stuart Horner of Core Communications, Inc. who found the 339need for building --shared OpenSSL libraries. 340 341Thanks to Pavel Hlavnicka for a patch for freeing memory when using 342a pkcs12 file, and for inspiring more robust read() behavior. 343 344James Woodyatt is a champ for finding a ridiculous memory leak that 345has been the bane of many a Crypt::SSLeay user. 346 347Thanks to Bryan Hart for his patch adding proxy support, 348and thanks to Tobias Manthey for submitting another approach. 349 350Thanks to Alex Rhomberg for Alpha linux ccc patch. 351 352Thanks to Tobias Manthey for his patches for client certificate 353support. 354 355Thanks to Daisuke Kuroda for adding PKCS12 certificate support. 356 357Thanks to Gamid Isayev for CA cert support and insights into error 358messaging. 359 360Thanks to Jeff Long for working through a tricky CA cert SSLClientVerify 361issue. 362 363Thanks to Chip Turner for patch to build under perl 5.8.0. 364 365Thanks to Joshua Chamas for the time he spent maintaining the 366module. 367 368Thanks to Jeff Lavallee for help with alarms on read failures (CPAN 369bug #12444). 370 371Thanks to Guenter Knauf for significant improvements in configuring 372things in Win32 and Netware lands and Jan Dubois for various 373suggestions for improvements. 374 375=head1 SEE ALSO 376 377=over 4 378 379=item Net::SSL 380 381If you have downloaded this distribution as of a dependency 382of another distribution, it's probably due to this module 383(which is included in this distribution). 384 385=item Net::SSLeay 386 387A module that offers access to the OpenSSL API directly from Perl. 388 389 http://search.cpan.org/dist/Net_SSLeay.pm/ 390 391=item http://www.openssl.org/related/binaries.html 392 393Pointers on where to find OpenSSL binary packages (Windows). 394 395=back 396 397=head1 SUPPORT 398 399For use of Crypt::SSLeay & Net::SSL with perl's LWP, please 400send email to C<libwww@perl.org>. 401 402For OpenSSL or general SSL support please email the 403openssl user mailing list at C<openssl-users@openssl.org>. 404This includes issues associated with building and installing 405OpenSSL on one's system. 406 407Please report all bugs at 408L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay>. 409 410This module was originally written by Gisle Aas, and was subsequently 411maintained by Joshua Chamas. It is currently maintained by David 412Landgren. 413 414=head1 COPYRIGHT 415 416 Copyright (c) 2006-2007 David Landgren. 417 Copyright (c) 1999-2003 Joshua Chamas. 418 Copyright (c) 1998 Gisle Aas. 419 420This program is free software; you can redistribute 421it and/or modify it under the same terms as Perl itself. 422 423=cut 424