378 lines
15 KiB
Plaintext
378 lines
15 KiB
Plaintext
README - Net::SSLeay Perl module for using OpenSSL
|
|
|
|
5.6.2002, Sampo Kellomaki <sampo@symlabs.com>
|
|
Version: 1.16
|
|
$Id: README,v 1.6 2002/06/05 18:25:45 sampo Exp $
|
|
|
|
1.16: tested against openssl-0.9.6d, added more callback stuff
|
|
1.14: added perr certificate return, HPUX aCC flags fix
|
|
1.09: added many utlility functions of OpenSSL API, better old perl support
|
|
1.08: 64 bit fixes, windows fixes, fixed extra newline with auth bug
|
|
1.07: added rudimentary TLSv1 support by Stephen C. Koehler
|
|
1.06: fixed ssl_read_all() bug where input '0' would cause loop to exit
|
|
1.05: fixed certificate gen at make test
|
|
1.04: overhaul for OpenSSL-0.9.3b (try http://www.openssl.org/)
|
|
|
|
By popular demand...
|
|
--------------------
|
|
|
|
perl -MNet::SSLeay -e '($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p'
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
perl-5.6.1
|
|
though anything starting from perl5.002 probably works.
|
|
OpenSSL-0.9.6d
|
|
(try http://www.openssl.org/) -
|
|
This release has been tested with 0.9.6d and
|
|
in historical light it seems likely that future versions
|
|
will work as well (if major version number changes all bets
|
|
are off, though)
|
|
|
|
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.
|
|
|
|
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 OpenSSL as per instructions in that package
|
|
|
|
gunzip <Net_SSLeay.pm-1.06.tar.gz | tar xvf -
|
|
cd Net_SSLeay.pm-1.14
|
|
./Makefile.PL -t # builds and tests it
|
|
make install # You probably have to su to root to do this
|
|
perldoc Net::SSLeay # optional, but highly recommended
|
|
perldoc Net::SSLeay::Handle
|
|
|
|
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:
|
|
|
|
perl Makefile.PL /openssl/path 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:
|
|
You need to get MS VC++ 6.0 Enterprise Edition. Nobody has
|
|
reported building using CygWin, although I suspect the
|
|
Unix instructions are pretty close.
|
|
|
|
Add:
|
|
d:\openssl
|
|
d:\openssl\bin
|
|
d:\openssl\lib
|
|
d:\openssl\include
|
|
d:\openssl\include\openssl
|
|
|
|
to system's environment PATH, assuming you installed your openssl
|
|
in d:\openssl. YMMV
|
|
|
|
perl Makefile.PL -windows D:\OpenSSL
|
|
|
|
where the last argument specifies where you installed your openssl.
|
|
The -windows flag tries to set up libraries correctly. If it
|
|
does not work, please tweak Makefile.PL and submit me a patch.
|
|
|
|
nmake
|
|
nmake install
|
|
|
|
*** windows details are still being worked out. If you manage
|
|
to compile this with different development environments under
|
|
Win32, please mail the diffs/success reports to me at sampo@iki.fi
|
|
|
|
The current incarnation of Windows tweaks was contributed by
|
|
Eric A Selber <eselber@briefcase.com>
|
|
|
|
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
|
|
doe 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 add -rsaref flag like this:
|
|
|
|
./Makefile.PL -rsaref -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.
|
|
|
|
Commercial Support
|
|
------------------
|
|
|
|
Commercial support for this module can be obtained from
|
|
|
|
Symlabs (netssleay@symlabs.com)
|
|
Tel: +351-214.222.630
|
|
Fax: +351-214.222.637
|
|
|
|
Noncommercial support can be obtained via email from the author, but
|
|
you are expected to do your home work well. Mails that do not full
|
|
fill the criteria below may be silently ignored.
|
|
|
|
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 send me a question or make a bug report, please remeber 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,
|
|
- 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.
|
|
|
|
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 if there are any post release building hints in
|
|
|
|
http://www.symlabs.com/Net_SSLeay/index.html
|
|
|
|
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>
|
|
All Rights Reserved.
|
|
|
|
Distribution and use of this module is under the same terms as the
|
|
OpenSSL package itself (i.e. free, but mandatory attribution; NO
|
|
WARRANTY). Please consult LICENSE file in the root of the OpenSSL
|
|
distribution.
|
|
|
|
While the source distribution of this perl module does not contain
|
|
Eric's or OpenSSL's code, if you use this module you will use OpenSSL
|
|
library. Please give Eric and OpenSSL team credit (as required by
|
|
their licenses).
|
|
|
|
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'
|
|
|
|
Newer versions of this module can be found from CPAN/authors/id/SAMPO/,
|
|
the home page is http://www.symlabs.com/Net_SSLeay/index.html
|
|
|
|
Please send bug reports to the above address. General questions should be
|
|
sent either to me or to the mailing list (subscribe by sending mail
|
|
to openssl-users-request@openssl.org or using web interface at
|
|
http://www.openssl.org/support/).
|
|
|
|
--Sampo
|