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 <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

    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
    <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 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
    <http://aspn.activestate.com/ASPN/docs/ActivePerl/5.8/faq/ActivePerl-faq
    2.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. 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
    <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 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 <http://search.cpan.org/dist/Net-SSLeay/>.

    OpenSSL binary packages for Windows
        See <http://www.openssl.org/related/binaries.html>.

SUPPORT
    For use of Crypt::SSLeay & Net::SSL with Perl's LWP, please send email
    to libwww@perl.org <mailto: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
    <mailto: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:.

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.