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