README - Net::SSLeay Perl module for using OpenSSL

31.7.1999, Sampo Kellomaki <[email protected]>
Version: 1.05

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 -e 'use Net::SSLeay; \
         ($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p'

Prerequisites
-------------

perl5.005       though anything starting from perl5.002 probably works.
OpenSSL-0.9.3a  (try http://www.openssl.org/) - nothing
               earlier works and I do not guarantee that anything
               later works either (but chances are good, if OpenSSL C API
               stabilizes at this version). If the newest version does
               not work, downgrade to OpenSSL-0.9.3a before asking questions.
               Or check if there is a newer version of this module available.

Note: SSLeay is no loger 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.

Installing
----------

Unix:
       # build OpenSSL as per instructions in that package

       gunzip <Net_SSLeay.pm-1.04.tar.gz | tar xvf -
       cd Net_SSLeay.pm-1.04
       ./Makefile.PL -t     # builds and tests it (3 compile warnings)
       make install         # You probably have to be root to do this
       perldoc Net::SSLeay  # optional, but highly recommended

Windows:
       *** 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 [email protected]

       Windows build was greatly helped by Anton Roeckseisen <[email protected]>

       read README.Win32

You should also be able to use CPAN.pm to install this module if you like.

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.


Problems (read this before sending mail)
----------------------------------------

If you send me a question or make a bug report, please remeber

 - Your platform and OS version (i386 Linux, Sparc Solaris, etc) (uname -a)
 - On Linux, please report glibc version as well)
 - Net::SSLeay version
 - OpenSSL version (/usr/local/ssl/bin/openssl version)
 - ANSI C compiler make and version (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 bogus old headers
 - if using newer than supported OpenSSL, please downgrade to supported
   version
 - 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
 - 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

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.

I have a report ([email protected]) of make test segfaulting on
Linux-PPC. This still needs to be investigated.

It seems perl5.004 (at least some versions) has bad xsub compiler which
can make builds sometimes fail. Try upgrading to perl5.005 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 are

 i686, Linux-2.0.37, gcc-2.7.2.1, perl5.005_03
 i586, Linux-2.0.36, gcc-2.7.2.3, perl5.005_02

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.bacus.pt/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.


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 <a
href="http://www.w3c.org">http://www.w3c.org</a> 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 dont find documentation you need,
please try to extrapolate from OpenSSL documentation (which unfortunately
is quite sparse) and 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

Newer versions of this module can be found from CPAN/authors/id/SAMPO/,
the home page is http://www.bacus.pt/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 [email protected] or using web interface at
http://www.openssl.org/support/).

--Sampo

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.