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

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

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

    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.

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

