view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# Crypt::SSLeay - OpenSSL support for LWP

## Do you need Crypt::SSLeay?

Since version 6.02, [LWP](https://metacpan.org/pod/LWP) depends on [LWP::Protocol::https](https://metacpan.org/pod/LWP::Protocol::https) which pulls in [IO::Socket::SSL](https://metacpan.org/pod/IO::Socket::SSL) which is then automatically used by [L...

At this point, `Crypt::SSLeay` is maintained to support existing software that already depends on it. However, it is possible that your software does not really depend on `Crypt::SSLeay`, only on the ability of `LWP::UserAgent` to communicate with si...

If you have both `Crypt::SSLeay` and `IO::Socket::SSL` installed, and would like to force `LWP::UserAgent` to use `Crypt::SSLeay`, you can use:

    use Net::HTTPS;
    $Net::HTTPS::SSL_SOCKET_CLASS = 'Net::SSL';
    use LWP::UserAgent;

or

    local $ENV{PERL_NET_HTTPS_SSL_SOCKET_CLASS} = 'Net::SSL';
    use LWP::UserAgent;

or

    use Net::SSL;
    use LWP::UserAgent;

## OpenSSL Heartbleed Bug

`perl Makefile.PL` will show a warning if the version of OpenSSL against which you are building `Crypt::SSLeay` seems vulnerable to the [Heartbleed Bug](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0160). See my blog post [Is a strong caut...

## Synopsis

    use Net::SSL;
    use LWP::UserAgent;

    my $ua  = LWP::UserAgent->new(
        ssl_opts => { verify_hostname => 0 },
    );

    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](https://metacpan.org/pod/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.

### Specify SSL Socket Class

    $ENV{PERL_NET_HTTPS_SSL_SOCKET_CLASS}

can be used to instruct `LWP::UserAgent` to use `Net::SSL` for HTTPS support rather than `IO::Socket::SSL`.

### Proxy Support

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

### Proxy Basic Authentication

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

### SSL Diagnostics and Debugging

    $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';

## Installation

### OpenSSL

You must have OpenSSL installed before compiling this module. You can get the latest OpenSSL package from [OpenSSL.org](https://www.openssl.org/source/). We no longer support pre-2000 versions of OpenSSL.

If you are building OpenSSL from source, please follow the directions included in the source package.

### Crypt::SSLeay via Makefile.PL

`Makefile.PL` accepts the following command line arguments:


#### incpath

Path to OpenSSL headers. Can also be specified via `$ENV{OPENSSL_INCLUDE}`. If the command line argument is provided, it overrides any value specified via the environment variable. Of course, you can ignore both the command line argument and the envi...

#### libpath

Path to OpenSSL libraries. Can also be specified via `$ENV{OPENSSL_LIB}`. If the command line argument is provided, it overrides any value specified by the environment variable. Of course, you can ignore both the command line argument and the environ...

#### live-tests

Use `--live-tests` to request tests that try to connect to an external web site, and "--no-live_tests" to prevent such tests from running. If you run `Makefile.PL` interactively, and this argument is not specified on the command line, you will be pro...

Default is false.

README.md  view on Meta::CPAN

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

If you have reported a bug or provided feedback, and you would like to be mentioned by name in this section, please file request on [rt.cpan.org](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay).

###	TODO: Update acknowledgements list.

## 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](https://metacpan.org/pod/Net::SSLeay) provides access to the OpenSSL API directly from Perl.

*   [OpenSSL binary packages for Windows](http://www.openssl.org/related/binaries.html)

*   [IO::Socket::SSL](https://metacpan.org/pod/IO::Socket::SSL)

*   [Building OpenSSL on 64-bit Windows 8.1 Pro using SDK tools](http://blog.nu42.com/2014/04/building-openssl-101g-on-64-bit-windows).

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

*   Please report all bugs on [rt.cpan.org](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-SSLeay).

## Authors

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

## Copyright

Copyright © 2010-2014 A. Sinan Unur

Copyright © 2006-2007 David Landgren

Copyright © 1999-2003 Joshua Chamas

Copyright © 1998 Gisle Aas

## License

This program is free software; you can redistribute it and/or modify it under the terms of [Artistic License 2.0](http://www.perlfoundation.org/artistic_license_2_0).