|
Packit |
b893dc |
README - Net::SSLeay Perl module for using OpenSSL
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
By popular demand...
|
|
Packit |
b893dc |
--------------------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
perl -MNet::SSLeay -e '($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p'
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
for the released versions:
|
|
Packit |
b893dc |
https://metacpan.org/release/Net-SSLeay
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
for the latest and possibly unstable version from git:
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
https://github.com/radiator-software/p5-net-ssleay
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Prerequisites
|
|
Packit |
b893dc |
-------------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Perl 5.8.1 or higher.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
OpenSSL-0.9.6j through to at least OpenSSL-1.1 and probably later
|
|
Packit |
b893dc |
http://www.openssl.org/ - On Linux, you can either build and
|
|
Packit |
b893dc |
install OpenSSL from scratch (its very portable) or you can
|
|
Packit |
b893dc |
install the appropriate OpenSSL 'devel' package for your Linux
|
|
Packit |
b893dc |
distribution: (rpm openssl-devel, deb libssl-dev).
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Note: SSLeay is no longer supported. If you want to use Net::SSLeay with
|
|
Packit |
b893dc |
SSLeay or early versions of OpenSSL, use version 1.03. The support
|
|
Packit |
b893dc |
for SSLeay was dropped due to nobody maintaining it (all active
|
|
Packit |
b893dc |
work goes on with OpenSSL) and due to incompatible API changes
|
|
Packit |
b893dc |
in OpenSSL-0.9.2b. OpenSSL-0.9.1c support has also been dropped,
|
|
Packit |
b893dc |
version 1.03 was the last one to support that.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
LibreSSL is also supported.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
You should use the same C compiler and options to compile OpenSSL,
|
|
Packit |
b893dc |
perl, and Net::SSLeay. This is the only supported configuration.
|
|
Packit |
b893dc |
If you insist on using different compilers (perhaps because you
|
|
Packit |
b893dc |
obtained either OpenSSL or perl as binaries from a vendor and they
|
|
Packit |
b893dc |
used a compiler that you do not have) then all requests for support
|
|
Packit |
b893dc |
will be ignored. If the only way for you to use the same compiler
|
|
Packit |
b893dc |
for all three components is to recompile your openssl or perl, then
|
|
Packit |
b893dc |
that is exactly what I expect you to do before asking for support.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Installing
|
|
Packit |
b893dc |
----------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Unix:
|
|
Packit |
b893dc |
# build or install OpenSSL as per instructions in that package
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
gunzip
|
|
Packit |
b893dc |
cd Net-SSLeay.pm-1.35
|
|
Packit |
b893dc |
perl Makefile.PL # builds and tests it
|
|
Packit |
b893dc |
make test # Run the test suite
|
|
Packit |
b893dc |
make install # You probably have to su to root to do this
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If your OpenSSL is installed in an unusual place, you can tell
|
|
Packit |
b893dc |
Net-SSLeay where to find it with the OPENSSL_PREFIX environment
|
|
Packit |
b893dc |
variable:
|
|
Packit |
b893dc |
OPENSSL_PREFIX=/home/mikem/playpen/openssl-1.0.2c perl Makefile.PL
|
|
Packit |
b893dc |
....
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
HPUX:
|
|
Packit |
b893dc |
In principle the Unix build should work (Makefile.PL contains
|
|
Packit |
b893dc |
special code to detect aCC), but historically there have been
|
|
Packit |
b893dc |
some problems. Marko Asplund (aspa@@kronodoc._fi) reports
|
|
Packit |
b893dc |
that he has successfully compiled on HP-UX. He used following
|
|
Packit |
b893dc |
incantations
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Configuring OpenSSL:
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
./Configure no-asm --prefix=/openssl/path hpux-parisc2-cc
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Configuring Net::SSLeay:
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
OPENSSL_PREFIX=/openssl/path perl Makefile.PL CCFLAGS='-D_HPUX_SOURCE \
|
|
Packit |
b893dc |
-Aa -I/usr/local/include +e'
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
The magic bit seemed to be the `+e' flag. Since version 1.14
|
|
Packit |
b893dc |
Makefile.PL tries to figure this out.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
He was using: gcc v2.95.2, OpenSSL v0.9.6c, Net::SSLeay-1.13
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Windows:
|
|
Packit |
b893dc |
Supported on 32 and 64 bit platforms
|
|
Packit |
b893dc |
See README.Win32 for details
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
OS X:
|
|
Packit |
b893dc |
See README.OSX
|
|
Packit |
b893dc |
---------------------------------
|
|
Packit |
b893dc |
You should also be able to use CPAN.pm to install this module if you like.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Linking with RSAref is no longer supported (the patent issue is moot
|
|
Packit |
b893dc |
due to patent expiring). If you want to try it, you are on your own,
|
|
Packit |
b893dc |
but here's how it used to work...
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
For linking against RSAref the the OPENSSL_RSAREF environment variable like this:
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
OPENSSL_RSAREF=1 ./Makefile.PL -t # builds and tests it, link against RSAref
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
You must previously have built OpenSSL with RSAref support (which
|
|
Packit |
b893dc |
implies first building rsaref itself), I use the RSAglue method. File
|
|
Packit |
b893dc |
librsaref.a must be found in one of the locations searched by linker
|
|
Packit |
b893dc |
(-L switches). Usually this means that you have to rename rsaref.a to
|
|
Packit |
b893dc |
librsaref.a and copy it to suitable directory, e.g. /usr/local/ssl/lib.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
N.B. AFAIK the patent that made using RSAref necessary has expired, so
|
|
Packit |
b893dc |
this should be nonissue by now.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Problems (read this before sending mail)
|
|
Packit |
b893dc |
----------------------------------------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Please, do not send bug report before you have
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
- compiled your OpenSSL yourself - don't copy binaries, please
|
|
Packit |
b893dc |
- compiled your perl yourself and with substantially same CFLAGS
|
|
Packit |
b893dc |
and same C compiler (say `which cc' or `which gcc') as your OpenSSL.
|
|
Packit |
b893dc |
This is especially applicable to link errors and shared
|
|
Packit |
b893dc |
library loading problems. Please do not even dream of
|
|
Packit |
b893dc |
copying a perl binary or installing perl binary from a package.
|
|
Packit |
b893dc |
Perl's idea of calling conventions has to match OpenSSL's and
|
|
Packit |
b893dc |
unfortunately both are quite advanced pieces of code
|
|
Packit |
b893dc |
(guru duel: Larry Wall vs. Eric Young :-) with dynamic loading
|
|
Packit |
b893dc |
and who knows what
|
|
Packit |
b893dc |
- compiled my module from source against correct perl (say `which perl'
|
|
Packit |
b893dc |
and check your path). Generally my module's build process will
|
|
Packit |
b893dc |
discover correct compiler and flags from `perl -V'
|
|
Packit |
b893dc |
- tried gcc, if your vendor cc fails
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you post a question or make a bug report, please remember to mention
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
- Your platform and OS version (i386 Linux, Sparc Solaris, etc) (uname -a)
|
|
Packit |
b893dc |
- On Linux, please report glibc version as well (ls -l /lib/libc*)
|
|
Packit |
b893dc |
- Net::SSLeay version (see tar ball)
|
|
Packit |
b893dc |
- OpenSSL version (`/usr/local/ssl/bin/openssl version')
|
|
Packit |
b893dc |
- ANSI C compiler brand and version (e.g. gcc -v)
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If build fails,
|
|
Packit |
b893dc |
- Dop you have OpenSSL headers installed? Perhaps you need the OpenSSL Devel
|
|
Packit |
b893dc |
package for your Linux distribution.
|
|
Packit |
b893dc |
- three compiler warnings are known to be emitted (due to lack of const
|
|
Packit |
b893dc |
in some places), one of them indicates a fatal bug in callback handling,
|
|
Packit |
b893dc |
but as I have not yet sorted it out, you'll simply have to ignore it
|
|
Packit |
b893dc |
- if you installed OpenSSL from some distribution, try getting a fresh
|
|
Packit |
b893dc |
copy from www.openssl.org and recompiling and installing it yourself
|
|
Packit |
b893dc |
- make sure you are not being confused by the fact that OpenSSL-0.9.3
|
|
Packit |
b893dc |
changed the location of include files to /usr/local/ssl/include/openssl/*
|
|
Packit |
b893dc |
Consider deleting all old bogus headers
|
|
Packit |
b893dc |
- if using newer than supported OpenSSL, please downgrade to supported
|
|
Packit |
b893dc |
version to see if it makes difference
|
|
Packit |
b893dc |
- you must compile the module, perl, and openssl with the same C compiler
|
|
Packit |
b893dc |
and the same options. Use perl -V to check what options were used and
|
|
Packit |
b893dc |
recompile openssl and Net::SSLeay accordingly
|
|
Packit |
b893dc |
- never report bugs related to binary installs. First compile _yourself_
|
|
Packit |
b893dc |
perl, openssl and my module, always using the same compiler and
|
|
Packit |
b893dc |
compiler flags. Many distros are known to "know better" and thus
|
|
Packit |
b893dc |
cause problems for their users. I'm not very sympathetic to having
|
|
Packit |
b893dc |
to answer end user questions thus created.
|
|
Packit |
b893dc |
- send full output of `make clean; perl Makefile.PL -t'
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If make test fails, please
|
|
Packit |
b893dc |
- one warning is known to be emitted between tests 4 and 5 (callback)
|
|
Packit |
b893dc |
- edit test.pl and set $trace=2
|
|
Packit |
b893dc |
- send full output of `make clean; perl Makefile.PL -t'
|
|
Packit |
b893dc |
- send contents of sslecho.log
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you have problems with a site, please
|
|
Packit |
b893dc |
- what site, what server software (including version and platform)
|
|
Packit |
b893dc |
- does it reproduce with s_client, try with something like
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
echo 'GET /' | /usr/local/ssl/bin/openssl s_client -connect www.bacus.pt:443
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
- does it reproduce with popular web browsers
|
|
Packit |
b893dc |
- play with Net::SSLeay::ssl_version (see top of SSLeay.pm)
|
|
Packit |
b893dc |
- does the site run exotic configuration, e.g. insisting on specific
|
|
Packit |
b893dc |
protocol version, limiting available ciphers, using nonstandard
|
|
Packit |
b893dc |
ciphers, weird authentication arrangements, etc.)
|
|
Packit |
b893dc |
- contact the owner of the server to see what the problem looks like
|
|
Packit |
b893dc |
in his end. He should be able to tell you the exact versions used
|
|
Packit |
b893dc |
and the error messages he is seeing in his log
|
|
Packit |
b893dc |
- if you ask me to check a site out, you are granting me permission
|
|
Packit |
b893dc |
to access that site and will pay all legal expenses to defend me
|
|
Packit |
b893dc |
in court as well as any remedies that may be granted to the site
|
|
Packit |
b893dc |
in case the site decides to sue me. You warrant that you are
|
|
Packit |
b893dc |
authorized to give me permission to access the site.
|
|
Packit |
b893dc |
- if you ask me to check a site, please send me a working URL and
|
|
Packit |
b893dc |
include any authentication credentials if needed. If your site
|
|
Packit |
b893dc |
is so confidential that you can not give me an URL, then do
|
|
Packit |
b893dc |
not ask me to debug your problems.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
HP-UX is known to give some problems, please mail me or the mailing
|
|
Packit |
b893dc |
list so we can get these problems straightened. Hint: it has to do
|
|
Packit |
b893dc |
with dynamic loading. One user reports that adding `-lgcc' to EXTRALIBS
|
|
Packit |
b893dc |
and LD_LOAD_LIBS in Makefile fixes the problem. I have not received any
|
|
Packit |
b893dc |
confirmation whether this fix really works, but its worth a try. Another
|
|
Packit |
b893dc |
bag of problems is people installing against binary distributed
|
|
Packit |
b893dc |
perl and compiling the package with different cc or different options.
|
|
Packit |
b893dc |
Genereally this will never work. Please compile _yourself_ your perl,
|
|
Packit |
b893dc |
openssl, and the module, always with the same compiler and compiler flags.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Solaris 8 does not come standard with /dev/random or /dev/urandom, and the
|
|
Packit |
b893dc |
'make test' assumes that some source of randomness is available. 'make test'
|
|
Packit |
b893dc |
will fail on Solaris 8 if /dev/urandom is not available. The error message
|
|
Packit |
b893dc |
seen with trace enabled will be "SSL_GET_NEW_SESSION:ssl session id callback
|
|
Packit |
b893dc |
failed". In order to fix this, you must install Sun patch 112438-03 from
|
|
Packit |
b893dc |
http://sunsolve.sun.com
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
#: unzip 112438-03.zip
|
|
Packit |
b893dc |
#: patchadd ./112438-03
|
|
Packit |
b893dc |
You will probably need to reboot your system:
|
|
Packit |
b893dc |
#: reboot
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
I have a report (schinder@@pobox._com) of make test segfaulting on
|
|
Packit |
b893dc |
Linux-PPC. This still needs to be investigated. No recent information
|
|
Packit |
b893dc |
has been received.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
"Random number generator not seeded!!!" This warning indicates that
|
|
Packit |
b893dc |
randomize() was not able to read /dev/random or /dev/urandom, possibly
|
|
Packit |
b893dc |
because your system does not have them or they are differently
|
|
Packit |
b893dc |
named. You can still use SSL, but the encryption will not be as
|
|
Packit |
b893dc |
strong.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Did you read the POD documentation (if you don't know what that
|
|
Packit |
b893dc |
is, just say `perldoc Net::SSLeay' or `more SSLeay.pm')?
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Are you sure you didn't confuse `Net::SSLeay' with `SSLeay' that
|
|
Packit |
b893dc |
comes with OpenSSL?
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Check that perl is finding your OpenSSL.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If `make test' bombs, add following line to the test script that fails:
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
$Net::SSLeay::trace = 2;
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
and see what happens. You may also have to edit test.pl to make sure
|
|
Packit |
b893dc |
the debugging output gets printed.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If `make test' prints lots of `connect: Connection refused...' errors,
|
|
Packit |
b893dc |
then sslecho.pl test server has died. It is supposed to be launched in
|
|
Packit |
b893dc |
the beginning of test.pl, but can fail if, e.g. port 1212 is taken or
|
|
Packit |
b893dc |
in TIMEWAIT state. Look also in ssleacho.log file for diagnostics.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you are really low on memory and the 1 MB tests fail, edit value of
|
|
Packit |
b893dc |
$mb variable in test.pl.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you get core dump, build your perl for debugging (add -g to
|
|
Packit |
b893dc |
ccflags, see INSTALL in perl distribution), build your SSLeay for
|
|
Packit |
b893dc |
debugging as well, add -g flag to Makefile.PL:
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
make clean
|
|
Packit |
b893dc |
perl Makefile.PL -g
|
|
Packit |
b893dc |
make static
|
|
Packit |
b893dc |
make test_static
|
|
Packit |
b893dc |
gdb perl core # post mortem
|
|
Packit |
b893dc |
> bt # show stack trace
|
|
Packit |
b893dc |
gdb perl # run live with debugging
|
|
Packit |
b893dc |
# set break point in SSLeay.xs or in suspect function of OpenSSL
|
|
Packit |
b893dc |
> br XS_Net__SSLeay_connect
|
|
Packit |
b893dc |
> run yourscript.pl arg arg
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
For gdb'ing make sure gdb finds all the relevant source code. This
|
|
Packit |
b893dc |
may mean that you must run perl and OpenSSL from the directories where
|
|
Packit |
b893dc |
the respective makefiles build them.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
You can also enable PR and PRN macros in SSLeay.xs and sprinkle
|
|
Packit |
b893dc |
even some more around the code to figure out what's happening.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Some exotic configurations of perl may cause unstability: make sure
|
|
Packit |
b893dc |
OpenSSL uses the same malloc as perl. Recompile perl without
|
|
Packit |
b893dc |
threads. Try not using the PerlIO abstraction.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you need to tweak build for some platform, please let me know
|
|
Packit |
b893dc |
so I can fix it. Patches and gdb session dumps are also welcome.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Copyright
|
|
Packit |
b893dc |
---------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Copyright (c) 1996-2003 Sampo Kellomäki <sampo@iki.fi>
|
|
Packit |
b893dc |
Copyright (c) 2005-2010 Florian Ragwitz <rafl@debian.org>
|
|
Packit |
b893dc |
Copyright (c) 2005-2018 Mike McCauley <mikem@airspayce.com>
|
|
Packit |
b893dc |
Copyright (c) 2018- Chris Novakovic <chris@chrisn.me.uk>
|
|
Packit |
b893dc |
Copyright (c) 2018- Tuure Vartiainen <vartiait@radiatorsoftware.com>
|
|
Packit |
b893dc |
Copyright (c) 2018- Heikki Vatiainen <hvn@radiatorsoftware.com>
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
All rights reserved.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
License
|
|
Packit |
b893dc |
-------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Net-SSLeay is released under the terms of the Artistic License 2.0. For
|
|
Packit |
b893dc |
details, see the LICENSE file.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Recommended reading
|
|
Packit |
b893dc |
-------------------
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
===> HTTP protocol specification. It applies 100% to HTTPS too and doing
|
|
Packit |
b893dc |
password authentication is explained there. <===
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you are newbie interested in grabbing web pages from https servers,
|
|
Packit |
b893dc |
please read HTTP documentation from http://www.w3c.org/ before asking trivial
|
|
Packit |
b893dc |
questions. That document also covers the basic-auth FAQ (URLs like
|
|
Packit |
b893dc |
http://user:pass@host). Do not ask questions about authentication before
|
|
Packit |
b893dc |
consulting the HTTP specification. HTTPS is just HTTP in SSL transport.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you are doing advanced stuff, and don't find documentation you need,
|
|
Packit |
b893dc |
please try to extrapolate from OpenSSL documentation (which unfortunately
|
|
Packit |
b893dc |
is quite sparse) and the source code.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
If you run into build problems, especially regarding shared libraries,
|
|
Packit |
b893dc |
check your perl documentation, especially the perlxtut(1) man page,
|
|
Packit |
b893dc |
which gives excellent tutorial of the build process of XSUBs.
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
perlxtut(1)
|
|
Packit |
b893dc |
perlxs(1)
|
|
Packit |
b893dc |
perlguts(1)
|
|
Packit |
b893dc |
perlcall(1)
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Say `perldoc Net::SSLeay' _NOW_!
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
To download OpenSSL, see https://www.openssl.org/
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
Bug reports, patch submission, feature requests and git access to the
|
|
Packit |
b893dc |
latest source code etc., can be obtained at
|
|
Packit |
b893dc |
https://github.com/radiator-software/p5-net-ssleay
|
|
Packit |
b893dc |
|
|
Packit |
b893dc |
|