README - Net::SSLeay Perl module for using Eric Young's implementation of SSL

4.1.1999, Sampo Kellomaki <sampo@iki.fi>
Version: 1.03
New: version upgrade for OpenSSL-0.9.1c (try http://www.openssl.org/)

Note: This module is _the_ `Net::SSLeay' namespace. Eric Young is
working on another module, which comes in the perl sub directory of
SSLeay-0.9.0, called `SSLeay'. These two modules are not related and
perl scripts written for one will not work with the other (though,
both modules can be simultaneously installed and your scripts are free
to mix and match :-)

By popular demand...
--------------------

   perl -e 'use Net::SSLeay; \
          ($p)=Net::SSLeay::get_https("www.cryptsoft.com", 443, "/"); print $p'

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

perl5.004     - though anything starting from perl5.002 probably works.
SSLeay-0.9.0 or OpenSSL-0.9.1c (try http://www.openssl.org/) - nothing
                earlier works and I do not guarantee that anything
                later works either (but chances are good, if SSLeay API
                stabilizes at this version). If the newest version does
                not work, downgrade to OpenSSL-0.9.1c before asking questions.

Installing
----------

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

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

Problems
--------

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'?

My development environment is
  
  i586, Linux-2.0.36, gcc-2.7.2.2, perl5.005_02

Unfortunately I do not have access to other systems so you are
somewhat on your own. Everything compiles without a warning on my
systems.

Check if there are any post release building hints in

	http://www.neuronio.pt/SSLeay.pm.html

Check that perl is finding your SSLeay.

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 5 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, uncomment the "OPTIMIZE => '-g'" line in
Makefile.PL and then say

	make clean
	perl Makefile.PL
	make static
	make test_static
	gdb perl core
	gdb perl core       # post mortem
	gdb perl
	  # set break point in SSLeay.xs or in suspect function
	  # in Eric's SSLeay
	  > 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 SSLeay 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.

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

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)

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.

To download OpenSSL, try URL http://www.openssl.org

--Sampo