| 1 |
Net-SSLeay - Perl bindings for OpenSSL and LibreSSL |
| 2 |
|
| 3 |
By popular demand... |
| 4 |
-------------------- |
| 5 |
|
| 6 |
perl -MNet::SSLeay -e '($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p' |
| 7 |
|
| 8 |
|
| 9 |
for the released versions: |
| 10 |
https://metacpan.org/release/Net-SSLeay |
| 11 |
|
| 12 |
for the latest and possibly unstable version from git: |
| 13 |
https://github.com/radiator-software/p5-net-ssleay |
| 14 |
|
| 15 |
|
| 16 |
Prerequisites |
| 17 |
------------- |
| 18 |
|
| 19 |
Perl 5.8.1 or higher. |
| 20 |
|
| 21 |
One of the following libssl implementations: |
| 22 |
|
| 23 |
* Any stable release of OpenSSL (https://www.openssl.org) in the |
| 24 |
0.9.8 - 3.6 branches, except for OpenSSL 0.9.8 - 0.9.8b. |
| 25 |
* Any stable release of LibreSSL (https://www.libressl.org) in the |
| 26 |
2.0 - 4.2 series, except for LibreSSL 3.2.2 and 3.2.3. |
| 27 |
|
| 28 |
Net-SSLeay may not compile or pass its tests against releases other |
| 29 |
than the ones listed above due to libssl API incompatibilities, or, in |
| 30 |
the case of LibreSSL, because of deviations from the libssl API. |
| 31 |
|
| 32 |
If you are using a version of OpenSSL or LibreSSL distributed by your |
| 33 |
operating system vendor, you may also need to install a "development" |
| 34 |
package containing the header files that correspond to the OpenSSL or |
| 35 |
LibreSSL library package. Examples include: |
| 36 |
|
| 37 |
* libssl-dev for OpenSSL on Debian and Ubuntu; |
| 38 |
* openssl-devel for OpenSSL on Red Hat Enterprise Linux and Fedora. |
| 39 |
|
| 40 |
On Linux, zlib is also required, even when libssl is built without |
| 41 |
support for TLS compression. zlib is probably also available via your |
| 42 |
Linux distribution's package manager, e.g.: |
| 43 |
|
| 44 |
* zlib1g-dev on Debian and Ubuntu; |
| 45 |
* zlib-devel on Red Hat Enterprise Linux and Fedora. |
| 46 |
|
| 47 |
A future version of Net-SSLeay will remove this requirement when |
| 48 |
building against a libssl without support for TLS compression. |
| 49 |
|
| 50 |
If there are build errors, test failures or run-time malfunctions, try |
| 51 |
to use the same compiler and options to compile your OpenSSL, Perl, |
| 52 |
and Net::SSLeay. Mixing compilers and options may lead to build |
| 53 |
errors, test failures or run-time malfunctions, that are difficult to |
| 54 |
debug. The situation in 2024 is that, for example, compiling Perl with |
| 55 |
gcc and Net::SSLeay with clang works on Linux and macOS. With Windows |
| 56 |
it may be easier to use the same compiler and compiler options. |
| 57 |
|
| 58 |
|
| 59 |
Installing |
| 60 |
---------- |
| 61 |
|
| 62 |
General: |
| 63 |
Makefile.PL tries to find OpenSSL installation location from a |
| 64 |
number of pre-defined paths. It will print the version and |
| 65 |
location of OpenSSL or LibreSSL it finds, or warn if it doesn't |
| 66 |
find anything usable. |
| 67 |
|
| 68 |
If your OpenSSL is installed in an unusual place, you can tell |
| 69 |
Makefile.PL from where to find it with by setting the |
| 70 |
OPENSSL_PREFIX environment variable. |
| 71 |
|
| 72 |
On Linux, macOS and other Unix type systems: |
| 73 |
OPENSSL_PREFIX=/home/mikem/playpen/openssl-1.0.2c perl Makefile.PL |
| 74 |
|
| 75 |
On Windows: |
| 76 |
set OPENSSL_PREFIX=C:\playpen\openssl-1.0.2.c |
| 77 |
perl Makefile.PL |
| 78 |
|
| 79 |
The logic in Makefile.PL tries to resolve the required |
| 80 |
libraries and include directories based on the environment |
| 81 |
variable OPENSSL_PREFIX. |
| 82 |
|
| 83 |
Unix: |
| 84 |
Build or install OpenSSL as per instructions in that |
| 85 |
package. Review section 'General:' above before continuing. |
| 86 |
|
| 87 |
gunzip <Net-SSLeay.pm-1.35.tar.gz | tar xvf - |
| 88 |
cd Net-SSLeay.pm-1.35 |
| 89 |
perl Makefile.PL # Build it. Use OPENSSL_PREFIX, if needed. |
| 90 |
make test # Run the test suite |
| 91 |
make install # You probably have to su to root to do this |
| 92 |
|
| 93 |
HPUX: |
| 94 |
In principle the Unix build should work (Makefile.PL contains |
| 95 |
special code to detect aCC), but historically there have been |
| 96 |
some problems. Marko Asplund (aspa@@kronodoc._fi) reports |
| 97 |
that he has successfully compiled on HP-UX. He used following |
| 98 |
incantations |
| 99 |
|
| 100 |
Configuring OpenSSL: |
| 101 |
|
| 102 |
./Configure no-asm --prefix=/openssl/path hpux-parisc2-cc |
| 103 |
|
| 104 |
Configuring Net::SSLeay: |
| 105 |
|
| 106 |
OPENSSL_PREFIX=/openssl/path perl Makefile.PL CCFLAGS='-D_HPUX_SOURCE \ |
| 107 |
-Aa -I/usr/local/include +e' |
| 108 |
|
| 109 |
The magic bit seemed to be the `+e' flag. Since version 1.14 |
| 110 |
Makefile.PL tries to figure this out. |
| 111 |
|
| 112 |
He was using: gcc v2.95.2, OpenSSL v0.9.6c, Net::SSLeay-1.13 |
| 113 |
|
| 114 |
Windows: |
| 115 |
Supported on 32 and 64 bit platforms |
| 116 |
See README.Win32 for details |
| 117 |
|
| 118 |
macOS, also known as OS X: |
| 119 |
See README.OSX |
| 120 |
--------------------------------- |
| 121 |
You should also be able to use CPAN.pm to install this module if you like. |
| 122 |
|
| 123 |
Problems (read this before filing a bug) |
| 124 |
---------------------------------------- |
| 125 |
|
| 126 |
Please, do not send bug report before you have |
| 127 |
|
| 128 |
- compiled your OpenSSL yourself - don't copy binaries, please |
| 129 |
- compiled your perl yourself and with substantially same CFLAGS |
| 130 |
and same C compiler (say `which cc' or `which gcc') as your OpenSSL. |
| 131 |
This is especially applicable to link errors and shared |
| 132 |
library loading problems. Please do not even dream of |
| 133 |
copying a perl binary or installing perl binary from a package. |
| 134 |
Perl's idea of calling conventions has to match OpenSSL's and |
| 135 |
unfortunately both are quite advanced pieces of code |
| 136 |
(guru duel: Larry Wall vs. Eric Young :-) with dynamic loading |
| 137 |
and who knows what |
| 138 |
- compiled my module from source against correct perl (say `which perl' |
| 139 |
and check your path). Generally my module's build process will |
| 140 |
discover correct compiler and flags from `perl -V' |
| 141 |
- tried gcc, if your vendor cc fails |
| 142 |
|
| 143 |
If you post a question or make a bug report, please remember to mention |
| 144 |
|
| 145 |
- Your platform and OS version (i386 Linux, Sparc Solaris, etc) (uname -a) |
| 146 |
- On Linux, please report glibc version as well (ls -l /lib/libc*) |
| 147 |
- Net::SSLeay version (see tar ball) |
| 148 |
- OpenSSL version (`/usr/local/ssl/bin/openssl version') |
| 149 |
- ANSI C compiler brand and version (e.g. gcc -v) |
| 150 |
|
| 151 |
If build fails, |
| 152 |
- Dop you have OpenSSL headers installed? Perhaps you need the OpenSSL Devel |
| 153 |
package for your Linux distribution. |
| 154 |
- three compiler warnings are known to be emitted (due to lack of const |
| 155 |
in some places), one of them indicates a fatal bug in callback handling, |
| 156 |
but as I have not yet sorted it out, you'll simply have to ignore it |
| 157 |
- if you installed OpenSSL from some distribution, try getting a fresh |
| 158 |
copy from www.openssl.org and recompiling and installing it yourself |
| 159 |
- if using newer than supported OpenSSL, please downgrade to supported |
| 160 |
version to see if it makes difference |
| 161 |
- you must compile the module, perl, and openssl with the same C compiler |
| 162 |
and the same options. Use perl -V to check what options were used and |
| 163 |
recompile openssl and Net::SSLeay accordingly |
| 164 |
- never report bugs related to binary installs. First compile _yourself_ |
| 165 |
perl, openssl and my module, always using the same compiler and |
| 166 |
compiler flags. Many distros are known to "know better" and thus |
| 167 |
cause problems for their users. I'm not very sympathetic to having |
| 168 |
to answer end user questions thus created. |
| 169 |
- send full output of `make clean; perl Makefile.PL -t' |
| 170 |
|
| 171 |
If make test fails, please |
| 172 |
- one warning is known to be emitted between tests 4 and 5 (callback) |
| 173 |
- edit test.pl and set $trace=2 |
| 174 |
- send full output of `make clean; perl Makefile.PL -t' |
| 175 |
- send contents of sslecho.log |
| 176 |
|
| 177 |
If you have problems with a site, please |
| 178 |
- what site, what server software (including version and platform) |
| 179 |
- does it reproduce with s_client, try with something like |
| 180 |
|
| 181 |
echo 'GET /' | /usr/local/ssl/bin/openssl s_client -connect www.bacus.pt:443 |
| 182 |
|
| 183 |
- does it reproduce with popular web browsers |
| 184 |
- play with Net::SSLeay::ssl_version (see top of SSLeay.pm) |
| 185 |
- does the site run exotic configuration, e.g. insisting on specific |
| 186 |
protocol version, limiting available ciphers, using nonstandard |
| 187 |
ciphers, weird authentication arrangements, etc.) |
| 188 |
- contact the owner of the server to see what the problem looks like |
| 189 |
in his end. He should be able to tell you the exact versions used |
| 190 |
and the error messages he is seeing in his log |
| 191 |
- if you ask me to check a site out, you are granting me permission |
| 192 |
to access that site and will pay all legal expenses to defend me |
| 193 |
in court as well as any remedies that may be granted to the site |
| 194 |
in case the site decides to sue me. You warrant that you are |
| 195 |
authorized to give me permission to access the site. |
| 196 |
- if you ask me to check a site, please send me a working URL and |
| 197 |
include any authentication credentials if needed. If your site |
| 198 |
is so confidential that you can not give me an URL, then do |
| 199 |
not ask me to debug your problems. |
| 200 |
|
| 201 |
HP-UX is known to give some problems, please mail me or the mailing |
| 202 |
list so we can get these problems straightened. Hint: it has to do |
| 203 |
with dynamic loading. One user reports that adding `-lgcc' to EXTRALIBS |
| 204 |
and LD_LOAD_LIBS in Makefile fixes the problem. I have not received any |
| 205 |
confirmation whether this fix really works, but its worth a try. Another |
| 206 |
bag of problems is people installing against binary distributed |
| 207 |
perl and compiling the package with different cc or different options. |
| 208 |
Genereally this will never work. Please compile _yourself_ your perl, |
| 209 |
openssl, and the module, always with the same compiler and compiler flags. |
| 210 |
|
| 211 |
Solaris 8 does not come standard with /dev/random or /dev/urandom, and the |
| 212 |
'make test' assumes that some source of randomness is available. 'make test' |
| 213 |
will fail on Solaris 8 if /dev/urandom is not available. The error message |
| 214 |
seen with trace enabled will be "SSL_GET_NEW_SESSION:ssl session id callback |
| 215 |
failed". In order to fix this, you must install Sun patch 112438-03 from |
| 216 |
http://sunsolve.sun.com |
| 217 |
|
| 218 |
#: unzip 112438-03.zip |
| 219 |
#: patchadd ./112438-03 |
| 220 |
You will probably need to reboot your system: |
| 221 |
#: reboot |
| 222 |
|
| 223 |
I have a report (schinder@@pobox._com) of make test segfaulting on |
| 224 |
Linux-PPC. This still needs to be investigated. No recent information |
| 225 |
has been received. |
| 226 |
|
| 227 |
"Random number generator not seeded!!!" This warning indicates that |
| 228 |
randomize() was not able to read /dev/random or /dev/urandom, possibly |
| 229 |
because your system does not have them or they are differently |
| 230 |
named. You can still use SSL, but the encryption will not be as |
| 231 |
strong. |
| 232 |
|
| 233 |
Did you read the POD documentation (if you don't know what that |
| 234 |
is, just say `perldoc Net::SSLeay' or `more SSLeay.pm')? |
| 235 |
|
| 236 |
Are you sure you didn't confuse `Net::SSLeay' with `SSLeay' that |
| 237 |
comes with OpenSSL? |
| 238 |
|
| 239 |
Check that perl is finding your OpenSSL. |
| 240 |
|
| 241 |
If `make test' bombs, add following line to the test script that fails: |
| 242 |
|
| 243 |
$Net::SSLeay::trace = 2; |
| 244 |
|
| 245 |
and see what happens. You may also have to edit test.pl to make sure |
| 246 |
the debugging output gets printed. |
| 247 |
|
| 248 |
If `make test' prints lots of `connect: Connection refused...' errors, |
| 249 |
then sslecho.pl test server has died. It is supposed to be launched in |
| 250 |
the beginning of test.pl, but can fail if, e.g. port 1212 is taken or |
| 251 |
in TIMEWAIT state. Look also in ssleacho.log file for diagnostics. |
| 252 |
|
| 253 |
If you are really low on memory and the 1 MB tests fail, edit value of |
| 254 |
$mb variable in test.pl. |
| 255 |
|
| 256 |
If you get core dump, build your perl for debugging (add -g to |
| 257 |
ccflags, see INSTALL in perl distribution), build your SSLeay for |
| 258 |
debugging as well, add -g flag to Makefile.PL: |
| 259 |
|
| 260 |
make clean |
| 261 |
perl Makefile.PL -g |
| 262 |
make static |
| 263 |
make test_static |
| 264 |
gdb perl core # post mortem |
| 265 |
> bt # show stack trace |
| 266 |
gdb perl # run live with debugging |
| 267 |
# set break point in SSLeay.xs or in suspect function of OpenSSL |
| 268 |
> br XS_Net__SSLeay_connect |
| 269 |
> run yourscript.pl arg arg |
| 270 |
|
| 271 |
For gdb'ing make sure gdb finds all the relevant source code. This |
| 272 |
may mean that you must run perl and OpenSSL from the directories where |
| 273 |
the respective makefiles build them. |
| 274 |
|
| 275 |
You can also enable PR and PRN macros in SSLeay.xs and sprinkle |
| 276 |
even some more around the code to figure out what's happening. |
| 277 |
|
| 278 |
Some exotic configurations of perl may cause unstability: make sure |
| 279 |
OpenSSL uses the same malloc as perl. Recompile perl without |
| 280 |
threads. Try not using the PerlIO abstraction. |
| 281 |
|
| 282 |
If you need to tweak build for some platform, please let me know |
| 283 |
so I can fix it. Patches and gdb session dumps are also welcome. |
| 284 |
|
| 285 |
Copyright |
| 286 |
--------- |
| 287 |
|
| 288 |
Copyright (c) 1996-2003 Sampo Kellomäki <[email protected]> |
| 289 |
Copyright (c) 2005-2010 Florian Ragwitz <[email protected]> |
| 290 |
Copyright (c) 2005-2018 Mike McCauley <[email protected]> |
| 291 |
Copyright (c) 2018 Tuure Vartiainen <[email protected]> |
| 292 |
Copyright (c) 2018- Chris Novakovic <[email protected]> |
| 293 |
Copyright (c) 2018- Heikki Vatiainen <[email protected]> |
| 294 |
|
| 295 |
All rights reserved. |
| 296 |
|
| 297 |
License |
| 298 |
------- |
| 299 |
|
| 300 |
Net-SSLeay is released under the terms of the Artistic License 2.0. For |
| 301 |
details, see the LICENSE file. |
| 302 |
|
| 303 |
Recommended reading |
| 304 |
------------------- |
| 305 |
|
| 306 |
===> HTTP protocol specification. It applies 100% to HTTPS too and doing |
| 307 |
password authentication is explained there. <=== |
| 308 |
|
| 309 |
If you are newbie interested in grabbing web pages from https servers, |
| 310 |
please read HTTP documentation from http://www.w3c.org/ before asking trivial |
| 311 |
questions. That document also covers the basic-auth FAQ (URLs like |
| 312 |
http://user:pass@host). Do not ask questions about authentication before |
| 313 |
consulting the HTTP specification. HTTPS is just HTTP in SSL transport. |
| 314 |
|
| 315 |
If you are doing advanced stuff, and don't find documentation you need, |
| 316 |
please try to extrapolate from OpenSSL documentation (which unfortunately |
| 317 |
is quite sparse) and the source code. |
| 318 |
|
| 319 |
If you run into build problems, especially regarding shared libraries, |
| 320 |
check your perl documentation, especially the perlxtut(1) man page, |
| 321 |
which gives excellent tutorial of the build process of XSUBs. |
| 322 |
|
| 323 |
perlxtut(1) |
| 324 |
perlxs(1) |
| 325 |
perlguts(1) |
| 326 |
perlcall(1) |
| 327 |
|
| 328 |
Say `perldoc Net::SSLeay' _NOW_! |
| 329 |
|
| 330 |
To download OpenSSL, see https://www.openssl.org/ |
| 331 |
|
| 332 |
Bug reports, patch submission, feature requests and git access to the |
| 333 |
latest source code etc., can be obtained at |
| 334 |
https://github.com/radiator-software/p5-net-ssleay |
| 335 |
|
| 336 |
|