NAME

Crypt::SSLeay - OpenSSL support for LWP

SYNOPSIS

lwp-request https://www.example.com

use LWP::UserAgent;
my $ua  = LWP::UserAgent->new;
my $response = $ua->get('https://www.example.com/');
print $response->content, "\n";

DESCRIPTION

This document describes Crypt::SSLeay version 0.57_05, released 2010-08-15.

This Perl module provides support for the HTTPS protocol under LWP, to allow an LWP::UserAgent object to perform GET, HEAD and POST requests. Please see LWP for more information on POST requests.

The Crypt::SSLeay package provides Net::SSL, which is loaded by LWP::Protocol::https for https requests and provides the necessary SSL glue.

This distribution also makes following deprecated modules available:

Crypt::SSLeay::CTX
Crypt::SSLeay::Conn
Crypt::SSLeay::X509

Work on Crypt::SSLeay has been continued only to provide https support for the LWP (libwww-perl) libraries.

ENVIRONMENT VARIABLES

The following environment variables change the way Crypt::SSLeay and Net::SSL behave.

# proxy support
$ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';

# proxy_basic_auth
$ENV{HTTPS_PROXY_USERNAME} = 'username';
$ENV{HTTPS_PROXY_PASSWORD} = 'password';

# debugging (SSL diagnostics)
$ENV{HTTPS_DEBUG} = 1;

# default ssl version
$ENV{HTTPS_VERSION} = '3';

# client certificate support
$ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
$ENV{HTTPS_KEY_FILE}  = 'certs/notacakeynopass.pem';

# CA cert peer verification
$ENV{HTTPS_CA_FILE}   = 'certs/ca-bundle.crt';
$ENV{HTTPS_CA_DIR}    = 'certs/';

# Client PKCS12 cert support
$ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
$ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';

INSTALL

OpenSSL

You must have OpenSSL or SSLeay installed before compiling this module. You can get the latest OpenSSL package from http://www.openssl.org/.

On Debian systems, you will need to install the libssl-dev package, at least for the duration of the build (it may be removed afterwards).

Other package-based systems may require something similar. The key is that Crypt::SSLeay makes calls to the OpenSSL library, and how to do so is specified in the C header files that come with the library. Some systems break out the header files into a separate package from that of the libraries. Once the program has been built, you don't need the headers any more.

When installing openssl make sure your config looks like:

./config --openssldir=/usr/local/openssl

./config --openssldir=/usr/local/ssl

If you are planning on upgrading the default OpenSSL libraries on a system like RedHat, (not recommended), then try something like:

./config --openssldir=/usr --shared

The --shared option to config will set up building the .so shared libraries which is important for such systems. This is followed by:

make
make test
make install

This way Crypt::SSLeay will pick up the includes and libraries automatically. If your includes end up going into a separate directory like /usr/local/include, then you may need to symlink /usr/local/openssl/include to /usr/local/include

Crypt::SSLeay

The latest Crypt::SSLeay can be found at your nearest CPAN, as well as http://search.cpan.org/dist/Crypt-SSLeay/

Once you have downloaded it, Crypt::SSLeay installs easily using the make * commands as shown below.

perl Makefile.PL
make
make test
make install

On Windows systems, both Strawberry Perl and ActiveState (as a separate download via ppm) projects include a MingW based compiler distribution and dmake which can be used to build both OpenSSL and Crypt-SSLeay. If you have such a set up, use dmake above.

For unattended (batch) installations, to be absolutely certain that Makefile.PL does not prompt for questions on STDIN, set the following environment variable beforehand:

PERL_MM_USE_DEFAULT=1

(This is true for any CPAN module that uses ExtUtils::MakeMaker).

To skip live tests, you can use

perl Makefile.PL --no-live-tests

and to force live tests, you can use

perl Makefile.PL --live-tests

Windows

Crypt::SSLeay builds correctly with Strawberry Perl.

For Activestate users, the ActiveState company does not have a permit from the Canadian Federal Government to distribute cryptographic software. This prevents Crypt::SSLeay from being distributed as a PPM package from their repository. See http://aspn.activestate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-faq2.html#crypto_packages for more information on this issue.

You may download it from Randy Kobes's PPM repository by using the following command:

ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd

An alternative is to add the uwinnipeg.ca PPM repository to your local installation. See http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html for more details.

VMS

It is assumed that the OpenSSL installation is located at /ssl$root. Define this logical to point to the appropriate place in the filesystem.

PROXY SUPPORT

LWP::UserAgent and Crypt::SSLeay have their own versions of proxy support. Please read these sections to see which one is appropriate.

LWP::UserAgent proxy support

LWP::UserAgent has its own methods of proxying which may work for you and is likely to be incompatible with Crypt::SSLeay proxy support. To use LWP::UserAgent proxy support, try something like:

my $ua = LWP::UserAgent->new;
$ua->proxy([qw( https http )], "$proxy_ip:$proxy_port");

At the time of this writing, libwww v5.6 seems to proxy https requests fine with an Apache mod_proxy server. It sends a line like:

GET https://www.example.com HTTP/1.1

to the proxy server, which is not the CONNECT request that some proxies would expect, so this may not work with other proxy servers than mod_proxy. The CONNECT method is used by Crypt::SSLeay's internal proxy support.

Crypt::SSLeay proxy support

For native Crypt::SSLeay proxy support of https requests, you need to set the environment variable HTTPS_PROXY to your proxy server and port, as in:

# proxy support
$ENV{HTTPS_PROXY} = 'http://proxy_hostname_or_ip:port';
$ENV{HTTPS_PROXY} = '127.0.0.1:8080';

Use of the HTTPS_PROXY environment variable in this way is similar to LWP::UserAgent-env_proxy()> usage, but calling that method will likely override or break the Crypt::SSLeay support, so do not mix the two.

Basic auth credentials to the proxy server can be provided this way:

# proxy_basic_auth
$ENV{HTTPS_PROXY_USERNAME} = 'username';
$ENV{HTTPS_PROXY_PASSWORD} = 'password';

For an example of LWP scripting with Crypt::SSLeay native proxy support, please look at the eg/lwp-ssl-test script in the Crypt::SSLeay distribution.

CLIENT CERTIFICATE SUPPORT

Client certificates are supported. PEM0encoded certificate and private key files may be used like this:

$ENV{HTTPS_CERT_FILE} = 'certs/notacacert.pem';
$ENV{HTTPS_KEY_FILE}  = 'certs/notacakeynopass.pem';

You may test your files with the eg/net-ssl-test program, bundled with the distribution, by issuing a command like:

perl eg/net-ssl-test -cert=certs/notacacert.pem \
    -key=certs/notacakeynopass.pem -d GET $HOST_NAME

Additionally, if you would like to tell the client where the CA file is, you may set these.

$ENV{HTTPS_CA_FILE} = "some_file";
$ENV{HTTPS_CA_DIR}  = "some_dir";

Note that, if specified, $ENV{HTTPS_CA_FILE} must point to the actual certificate file. That is, $ENV{HTTPS_CA_DIR} is *not* the path were $ENV{HTTPS_CA_FILE} is located.

For certificates in $ENV{HTTPS_CA_DIR} to be picked up, follow the instructions on http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html

There is no sample CA cert file at this time for testing, but you may configure eg/net-ssl-test to use your CA cert with the -CAfile option. (TODO: then what is the ./certs directory in the distribution?)

Creating a test certificate

To create simple test certificates with OpenSSL, you may run the following command:

openssl req -config /usr/local/openssl/openssl.cnf \
    -new -days 365 -newkey rsa:1024 -x509 \
    -keyout notacakey.pem -out notacacert.pem

To remove the pass phrase from the key file, run:

openssl rsa -in notacakey.pem -out notacakeynopass.pem

PKCS12 support

The directives for enabling use of PKCS12 certificates is:

$ENV{HTTPS_PKCS12_FILE}     = 'certs/pkcs12.pkcs12';
$ENV{HTTPS_PKCS12_PASSWORD} = 'PKCS12_PASSWORD';

Use of this type of certificate takes precedence over previous certificate settings described. (TODO: unclear? Meaning "the presence of this type of certificate??)

SSL versions

Crypt::SSLeay tries very hard to connect to any SSL web server accomodating servers that are buggy, old or simply not standards-compliant. To this effect, this module will try SSL connections in this order:

SSL v23: should allow v2 and v3 servers to pick their best type
SSL v3: best connection type
SSL v2: old connection type

Unfortunately, some servers seem not to handle a reconnect to SSL v3 after a failed connect of SSL v23 is tried, so you may set before using LWP or Net::SSL:

$ENV{HTTPS_VERSION} = 3;

to force a version 3 SSL connection first. At this time only a version 2 SSL connection will be tried after this, as the connection attempt order remains unchanged by this setting.

ACKNOWLEDGEMENTS

Many thanks to the following individuals who helped improve Crypt-SSLeay:

Gisle Aas: for writing this module and many others including libwww, for perl. The web will never be the same :)
Ben Laurie: deserves kudos for his excellent patches for better error handling, SSL information inspection, and random seeding.
Dongqiang Bai: for host name resolution fix when using a proxy.
Stuart Horner of Core Communications, Inc.: who found the need for building --shared OpenSSL libraries.
Pavel Hlavnicka: for a patch for freeing memory when using a pkcs12 file, and for inspiring more robust read() behavior.
James Woodyatt: is a champ for finding a ridiculous memory leak that has been the bane of many a Crypt::SSLeay user.
Bryan Hart: for his patch adding proxy support, and thanks to Tobias Manthey for submitting another approach.
Alex Rhomberg: for Alpha linux ccc patch.
Tobias Manthey: for his patches for client certificate support.
Daisuke Kuroda: for adding PKCS12 certificate support.
Gamid Isayev: for CA cert support and insights into error messaging.
Jeff Long: for working through a tricky CA cert SSLClientVerify issue.
Chip Turner: for patch to build under perl 5.8.0.
Joshua Chamas: for the time he spent maintaining the module.
Jeff Lavallee: for help with alarms on read failures (CPAN bug #12444).
Guenter Knauf: for significant improvements in configuring things in Win32 and Netware lands and Jan Dubois for various suggestions for improvements.
and others: who provided bug reports, suggestions, fixes and patches.

SUPPORT

For use of Crypt::SSLeay & Net::SSL with Perl's LWP, please send email to libwww@perl.org.

For OpenSSL or general SSL support, including issues associated with building and installing OpenSSL on your system, please email the OpenSSL users mailing list at openssl-users@openssl.org. See http://www.openssl.org/support/community.html for other mailing lists and archives.

Please report all bugs at "/rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay"" in "http:.

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

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Crypt::SSLeay, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Crypt::SSLeay

CPAN shell

perl -MCPAN -e shell
install Crypt::SSLeay

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)