README - Net::SSLeay Perl module for using OpenSSL
$Id: README 269 2011-03-22 20:52:40Z mikem-guest $
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 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
Copyright (c) 2005 Florian Ragwitz
Copyright (c) 2005 Mike McCauley
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