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 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 .
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
or
./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
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 Perl 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
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 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. PEM encoded 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
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 a 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 *many others* who provided bug reports, suggestions, fixes and
patches.
SEE ALSO
Net::SSL
If you have downloaded this distribution as of a dependency of
another distribution, it's probably due to this module (which is
included in this distribution).
Net::SSLeay
Net::SSLeay provides access to the OpenSSL API directly from Perl.
See .
OpenSSL binary packages for Windows
See .
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
for other mailing lists
and archives.
Please report all bugs at
"/rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay"" in "http:.
AUTHORS
This module was originally written by Gisle Aas, and was subsequently
maintained by Joshua Chamas, David Landgren, brian d foy and Sinan Unur.
COPYRIGHT
Copyright (c) 2010 A. Sinan Unur
Copyright (c) 2006-2007 David Landgren
Copyright (c) 1999-2003 Joshua Chamas
Copyright (c) 1998 Gisle Aas
LICENSE
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.