SSLeay(3)

📦
version 0.72 · 13 versions
, in opensuse-leap 16.0

💖 SSLeay(3) 💖

Crypt::SSLeay — the User Contributed Perl Documentation page, but make it a group chat

ok bestie, sit down, grab a strawberry 🍓, because we're talking about the perl module that made HTTPS happen for LWP back in the day. the manual page header is SSLeay(3), and the whole thing lives under User Contributed Perl Documentation. it's giving vintage. it's giving "your legacy codebase still depends on me." let's get into it 💅

🎀 NAME 🎀

Crypt::SSLeay — OpenSSL support for LWP. that's the whole name. short, sweet, iconic 👑

💀 HEARTBLEED WARNING 💀

okay so before anything else, the scary part. 😭 perl Makefile.PL will display a warning if it thinks your OpenSSL might be vulnerable to the Heartbleed Bug (https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0160 — that's CVE-2014-0160, babes).

you can, of course, go ahead and install the module anyway. nobody's stopping you. but you should be aware that your system might be exposed to an extremely serious vulnerability. like, that's not me being dramatic, that's the literal text. 🫠

the key tea though: this is just a heuristic based on the version reported by OpenSSL. it is entirely possible that your distribution actually pushed a patched library. so if you have concerns, you should investigate further. don't just spiral, go check ✨

🌸 SYNOPSIS 🌸

here's the vibe check in code form, no cap:

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

that's it. that's the whole main character moment 🦋

✨ DESCRIPTION ✨

so what does this thing actually do? this Perl module provides support for the HTTPS protocol under LWP, so that an LWP::UserAgent object can perform GET, HEAD, and POST requests over encrypted socket connections. and if you're curious about POST requests specifically, go read LWP for more info, because that's where the details live 👀

the Crypt::SSLeay package provides Net::SSL, which — if it's requested — gets loaded by LWP::Protocol::https for https requests and provides the necessary SSL glue. lowkey the little matchmaker between LWP and OpenSSL 🫶

this distribution also makes the following deprecated modules available:

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

deprecated, bestie. they're still here, but they're giving nostalgia, not future 🎀

🦋 DO YOU NEED Crypt::SSLeay? 🦋

(big question, love that for you, let's find out)

starting with version 6.02 of LWP, https support was unbundled into LWP::Protocol::https. this module specifies as one of its prerequisites IO::Socket::SSL, which is automatically used by LWP::UserAgent unless this preference is overridden separately.

and here's the thing: IO::Socket::SSL is a more complete implementation, and — crucially — it allows hostname verification. Crypt::SSLeay does not support that. so yeah, that's kind of a big deal 😬

at this point, Crypt::SSLeay is maintained to support existing software that already depends on it. however — and this is the plot twist — it is possible that your software does not really depend on Crypt::SSLeay, only on the ability of the LWP::UserAgent class to communicate with sites over SSL/TLS. so like… you might be free and not even know it 💀

so, the diagnosis: if you are using version LWP 6.02 or later, and therefore have installed LWP::Protocol::https and its dependencies, and you do not explicitly use Net::SSL before loading LWP::UserAgent, or override the default socket class — you are probably using IO::Socket::SSL and you do not really need Crypt::SSLeay. slay, honestly.

but! if you have both Crypt::SSLeay and IO::Socket::SSL installed, and you would like to force LWP::UserAgent to use Crypt::SSLeay, you have three (3) whole options, pick your fighter:

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;

three paths, one destiny ✨

🌈 ENVIRONMENT VARIABLES 🌈

💜 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. one env var, whole different socket class. the power 🫶

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

turn it on and let it yap 🔥

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

that's a whole lot of env vars and every single one of them is in that list. no skips, no cuts 💅

🧚 INSTALL 🧚

🌸 OpenSSL 🌸

you must have OpenSSL installed before compiling this module. non-negotiable, bestie. you can get the latest OpenSSL package from https://www.openssl.org/source/ 🎀

and listen — we no longer support pre-2000 versions of OpenSSL. if your OpenSSL is that old, it belongs in a museum, not a build 😭

if you are building OpenSSL from source, please follow the directions included in the source package. they literally come with instructions, use them 🫶

🌸 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 environment variable, and just add the path to your compiler specific environment variable such as CPATH or INCLUDE etc. three ways to do the same thing, pick your fave ✨
  • 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 environment variable and just add the path to your compiler specific environment variable such as LIBRARY_PATH or LIB etc. yes, same energy as above 💅
  • 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 prompted for a value. default is false.
  • static — Boolean. default is false. TODO: Does it work? (the manual says that, not me, I'm just the messenger 🙈)
  • verbose — Boolean. default is false. if you pass --verbose on the command line, both Devel::CheckLib and ExtUtils::CBuilder instances will be configured to echo what they are doing. basically it narrates its own life for you 👑

if everything builds OK, but you get failures when during tests, ensure that LD_LIBRARY_PATH points to the location where the correct shared libraries are located. like, actually check it. that's usually the one 🫠

if you are using a custom OpenSSL build, please keep in mind that Crypt::SSLeay must be built using the same compiler and build tools used to build perl and OpenSSL. this can be more of an issue on Windows. if you are using Active State Perl, install the MinGW package distributed by them, and build OpenSSL using that before trying to build this module. if you have built your own Perl using Microsoft SDK tools or IDEs, make sure you build OpenSSL using the same tools. matching sets only, bestie 🎀

depending on your OS, pre-built OpenSSL packages may be available. to get the require headers and import libraries, you may need to install a development version of your operating system's OpenSSL library package. 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. iconic — the headers did their job and then left the group chat 💅

🌸 Crypt::SSLeay 🌸

the latest Crypt::SSLeay can be found at your nearest CPAN mirror, as well as https://metacpan.org/pod/Crypt::SSLeay 🌈

once you have downloaded it, Crypt::SSLeay installs easily using the standard build process:

$ perl Makefile.PL
$ make
$ make test
$ make install

or

$ cpanm Crypt::SSLeay

if you have OpenSSL headers and libraries in nonstandard locations, you can use

$ perl Makefile.PL --incpath=... --libpath=...

if you would like to use cpanm with such custom locations, you can do

$ OPENSSL_INCLUDE=... OPENSSL_LIB=... cpanm Crypt::SSLeay

or, on Windows,

> set OPENSSL_INCLUDE=...
> set OPENSSL_LIB=...
> cpanm Crypt::SSLeay

if you are on Windows, and using a MinGW distribution bundled with ActiveState Perl or Strawberry Perl, you would use dmake rather than make. if you are using Microsoft's build tools, you would use nmake. different tool, same dream 🦋

for unattended (batch) installations, to be absolutely certain that Makefile.PL does not prompt for questions on STDIN, set the environment variable PERL_MM_USE_DEFAULT=1 as with any CPAN module built using ExtUtils::MakeMaker. set it and walk away, queen 👑

🍓 VMS 🍓

the author says, and I quote the vibe: they do not have any experience with VMS. so if OpenSSL headers and libraries are not in standard locations searched by your build system by default, please set things up so that they are. and if you have generic instructions on how to do it, please open a ticket on RT with the information so it can be added to this document. help a sister out 🙏

🔥 PROXY SUPPORT 🔥

LWP::UserAgent and Crypt::SSLeay have their own versions of proxy support. please read these sections to see which one is appropriate. yes, both of them exist, and yes, you have to choose. choose wisely 💅

👑 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. so like, mod_proxy? fine. everything else? read the fine print 😬

👑 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. seriously. pick a lane 💀

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. it's right there, go look 🫶

💖 CLIENT CERTIFICATE SUPPORT 💖

okay so yes, client certificates are supported, bestie. 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. iykyk, they are separate things 💅

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?) asking the real questions fr fr

🎀 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. main character certificate energy tbh 👑

(TODO: unclear? Meaning "the presence of this type of certificate"?) the plot thickens 🫶

🔥 SSL versions 🔥

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

  1. SSL v23 — should allow v2 and v3 servers to pick their best type
  2. SSL v3 — best connection type
  3. 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. the lore is lore-ing 😭

🌈 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. come get your credit, bestie 💖

🦋 SEE ALSO 🦋

🫶 SUPPORT 🫶

  • For issues related to using 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 using 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 Sinan Unur. legends only ✨

  • Copyright (c) 2010-2014 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 terms of Artistic License 2.0 (see http://www.perlfoundation.org/artistic_license_2_0).

and that's the whole vibe, bestie 💖 page footer says source/version perl v5.42.0, date 2024-03-04, and yes this is SSLeay(3) — slay and stay safe 🦋💅

📦 where this page comes from