README - Net::SSLeay Perl module for using OpenSSL 7.4.2001, Sampo Kellomaki Version: 1.06 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 -e 'use Net::SSLeay; \ ($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p' Prerequisites ------------- perl5.005 or perl-5.6.0 though anything starting from perl5.002 probably works. OpenSSL-0.9.3a or OpenSSL-0.9.6a (try http://www.openssl.org/) - nothing earlier works. This release has been tested with 0.9.6a 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. Installing ---------- Unix: # build OpenSSL as per instructions in that package gunzip 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 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 compiler and the same options. Use perl -V to check what options were used and recompile openssl and my module 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 - 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. One user reports that adding `-lgcc' to EXTRALIBS and LD_LOAD_LIBS in Makefile fixes the problem. We 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 receivced. It seems perl5.004 (at least some versions) has bad xsub compiler which can make builds sometimes fail. Try upgrading to perl-5.6.0 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.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.0 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. License and Copying ------------------- Copyright (c) 1996-2001 Sampo Kellomaki , 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 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.bacus.pt/Net_SSLeay/smime.html' 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 openssl-users-request@openssl.org or using web interface at http://www.openssl.org/support/). --Sampo