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