README - Net::SSLeay Perl module for using OpenSSL

13.6.2003, Sampo Kellomaki <sampo@symlabs.com> Version: 1.16
$Id$

1.23: tested against openssl-0.9.6j and openssl-0.9.7b

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.003 probably works. OpenSSL-0.9.6j or OpenSSL-0.9.7b

                (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.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

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

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

                OPENSSL_PREFIX=D:\OpenSSL perl Makefile.PL

        On windows, Makefile.PL will automatically set up library and include
        paths for windows compile and will automatcially find OpenSSL if it
        exists in c:\OpenSSL. If your OPenSSL libraries and includes are
        elsewhere, use the OPENSSL_PREFIX environment variable. 
        If it does not work, please tweak
        Makefile.PL and submit 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 post the diffs/success reports to http://alioth.debian.org/projects/net-ssleay
        
        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 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 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.

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

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).