--- /dev/null
+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.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:
+
+ 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 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>
+Copyright (c) 2005 Florian Ragwitz <rafl@debian.org>
+Copyright (c) 2005 Mike McCauley <mikem@open.com.au>
+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'
+
+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
+
projects / dh-make-perl / blobdiff