1 README - Net::SSLeay Perl module for using OpenSSL
3 13.6.2003, Sampo Kellomaki <sampo@symlabs.com>
7 1.23: tested against openssl-0.9.6j and openssl-0.9.7b
9 1.16: tested against openssl-0.9.6d, added more callback stuff
10 1.14: added perr certificate return, HPUX aCC flags fix
11 1.09: added many utlility functions of OpenSSL API, better old perl support
12 1.08: 64 bit fixes, windows fixes, fixed extra newline with auth bug
13 1.07: added rudimentary TLSv1 support by Stephen C. Koehler
14 1.06: fixed ssl_read_all() bug where input '0' would cause loop to exit
15 1.05: fixed certificate gen at make test
16 1.04: overhaul for OpenSSL-0.9.3b (try http://www.openssl.org/)
21 perl -MNet::SSLeay -e '($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p'
27 though anything starting from perl5.003 probably works.
28 OpenSSL-0.9.6j or OpenSSL-0.9.7b
29 (try http://www.openssl.org/) -
30 This release has been tested with 0.9.6d and
31 in historical light it seems likely that future versions
32 will work as well (if major version number changes all bets
35 Note: SSLeay is no longer supported. If you want to use Net::SSLeay with
36 SSLeay or early versions of OpenSSL, use version 1.03. The support
37 for SSLeay was dropped due to nobody maintaining it (all active
38 work goes on with OpenSSL) and due to incompatible API changes
39 in OpenSSL-0.9.2b. OpenSSL-0.9.1c support has also been dropped,
40 version 1.03 was the last one to support that.
42 You should use the same C compiler and options to compile OpenSSL,
43 perl, and Net::SSLeay. This is the only supported configuration.
44 If you insist on using different compilers (perhaps because you
45 obtained either OpenSSL or perl as binaries from a vendor and they
46 used a compiler that you do not have) then all requests for support
47 will be ignored. If the only way for you to use the same compiler
48 for all three components is to recompile your openssl or perl, then
49 that is exactly what I expect you to do before asking for support.
55 # build OpenSSL as per instructions in that package
57 gunzip <Net_SSLeay.pm-1.06.tar.gz | tar xvf -
59 ./Makefile.PL -t # builds and tests it
60 make install # You probably have to su to root to do this
61 perldoc Net::SSLeay # optional, but highly recommended
62 perldoc Net::SSLeay::Handle
65 In principle the Unix build should work (Makefile.PL contains
66 special code to detect aCC), but historically there have been
67 some problems. Marko Asplund (aspa@@kronodoc._fi) reports
68 that he has successfully compiled on HP-UX. He used following
73 ./Configure no-asm --prefix=/openssl/path hpux-parisc2-cc
75 Configuring Net::SSLeay:
77 OPENSSL_PREFIX=/openssl/path perl Makefile.PL CCFLAGS='-D_HPUX_SOURCE \
78 -Aa -I/usr/local/include +e'
80 The magic bit seemed to be the `+e' flag. Since version 1.14
81 Makefile.PL tries to figure this out.
83 He was using: gcc v2.95.2, OpenSSL v0.9.6c, Net::SSLeay-1.13
86 You need to get MS VC++ 6.0 Enterprise Edition. Nobody has
87 reported building using CygWin, although I suspect the
88 Unix instructions are pretty close.
95 d:\openssl\include\openssl
97 to system's environment PATH, assuming you installed your openssl
100 OPENSSL_PREFIX=D:\OpenSSL perl Makefile.PL
102 On windows, Makefile.PL will automatically set up library and include
103 paths for windows compile and will automatcially find OpenSSL if it
104 exists in c:\OpenSSL. If your OPenSSL libraries and includes are
105 elsewhere, use the OPENSSL_PREFIX environment variable.
106 If it does not work, please tweak
107 Makefile.PL and submit a patch.
112 *** windows details are still being worked out. If you manage
113 to compile this with different development environments under
114 Win32, please post the diffs/success reports to http://alioth.debian.org/projects/net-ssleay
116 The current incarnation of Windows tweaks was contributed by
117 Eric A Selber <eselber@briefcase.com>
119 You should also be able to use CPAN.pm to install this module if you like.
121 Linking with RSAref is no longer supported (the patent issue is moot
122 doe to patent expiring). If you want to try it, you are on your own,
123 but here's how it used to work...
125 For linking against RSAref the the OPENSSL_RSAREF environment variable like this:
127 OPENSSL_RSAREF=1 ./Makefile.PL -t # builds and tests it, link against RSAref
129 You must previously have built OpenSSL with RSAref support (which
130 implies first building rsaref itself), I use the RSAglue method. File
131 librsaref.a must be found in one of the locations searched by linker
132 (-L switches). Usually this means that you have to rename rsaref.a to
133 librsaref.a and copy it to suitable directory, e.g. /usr/local/ssl/lib.
135 N.B. AFAIK the patent that made using RSAref necessary has expired, so
136 this should be nonissue by now.
139 Problems (read this before sending mail)
140 ----------------------------------------
142 Please, do not send bug report before you have
144 - compiled your OpenSSL yourself - don't copy binaries, please
145 - compiled your perl yourself and with substantially same CFLAGS
146 and same C compiler (say `which cc' or `which gcc') as your OpenSSL.
147 This is especially applicable to link errors and shared
148 library loading problems. Please do not even dream of
149 copying a perl binary or installing perl binary from a package.
150 Perl's idea of calling conventions has to match OpenSSL's and
151 unfortunately both are quite advanced pieces of code
152 (guru duel: Larry Wall vs. Eric Young :-) with dynamic loading
154 - compiled my module from source against correct perl (say `which perl'
155 and check your path). Generally my module's build process will
156 discover correct compiler and flags from `perl -V'
157 - tried gcc, if your vendor cc fails
159 If you post a question or make a bug report, please remeber to mention
161 - Your platform and OS version (i386 Linux, Sparc Solaris, etc) (uname -a)
162 - On Linux, please report glibc version as well (ls -l /lib/libc*)
163 - Net::SSLeay version (see tar ball)
164 - OpenSSL version (`/usr/local/ssl/bin/openssl version')
165 - ANSI C compiler brand and version (e.g. gcc -v)
168 - three compiler warnings are known to be emitted (due to lack of const
169 in some places), one of them indicates a fatal bug in callback handling,
170 but as I have not yet sorted it out, you'll simply have to ignore it
171 - if you installed OpenSSL from some distribution, try getting a fresh
172 copy from www.openssl.org and recompiling and installing it yourself
173 - make sure you are not being confused by the fact that OpenSSL-0.9.3
174 changed the location of include files to /usr/local/ssl/include/openssl/*
175 Consider deleting all old bogus headers
176 - if using newer than supported OpenSSL, please downgrade to supported
177 version to see if it makes difference
178 - you must compile the module, perl, and openssl with the same C compiler
179 and the same options. Use perl -V to check what options were used and
180 recompile openssl and Net::SSLeay accordingly
181 - never report bugs related to binary installs. First compile _yourself_
182 perl, openssl and my module, always using the same compiler and
183 compiler flags. Many distros are known to "know better" and thus
184 cause problems for their users. I'm not very sympathetic to having
185 to answer end user questions thus created.
186 - send full output of `make clean; perl Makefile.PL -t'
188 If make test fails, please
189 - one warning is known to be emitted between tests 4 and 5 (callback)
190 - edit test.pl and set $trace=2
191 - send full output of `make clean; perl Makefile.PL -t'
192 - send contents of sslecho.log
194 If you have problems with a site, please
195 - what site, what server software (including version and platform)
196 - does it reproduce with s_client, try with something like
198 echo 'GET /' | /usr/local/ssl/bin/openssl s_client -connect www.bacus.pt:443
200 - does it reproduce with popular web browsers
201 - play with Net::SSLeay::ssl_version (see top of SSLeay.pm)
202 - does the site run exotic configuration, e.g. insisting on specific
203 protocol version, limiting available ciphers, using nonstandard
204 ciphers, weird authentication arrangements, etc.)
205 - contact the owner of the server to see what the problem looks like
206 in his end. He should be able to tell you the exact versions used
207 and the error messages he is seeing in his log
208 - if you ask me to check a site out, you are granting me permission
209 to access that site and will pay all legal expenses to defend me
210 in court as well as any remedies that may be granted to the site
211 in case the site decides to sue me. You warrant that you are
212 authorized to give me permission to access the site.
213 - if you ask me to check a site, please send me a working URL and
214 include any authentication credentials if needed. If your site
215 is so confidential that you can not give me an URL, then do
216 not ask me to debug your problems.
218 HP-UX is known to give some problems, please mail me or the mailing
219 list so we can get these problems straightened. Hint: it has to do
220 with dynamic loading. One user reports that adding `-lgcc' to EXTRALIBS
221 and LD_LOAD_LIBS in Makefile fixes the problem. I have not received any
222 confirmation whether this fix really works, but its worth a try. Another
223 bag of problems is people installing against binary distributed
224 perl and compiling the package with different cc or different options.
225 Genereally this will never work. Please compile _yourself_ your perl,
226 openssl, and the module, always with the same compiler and compiler flags.
228 Solaris 8 does not come standard with /dev/random or /dev/urandom, and the
229 'make test' assumes that some source of randomness is available. 'make test'
230 will fail on Solaris 8 if /dev/urandom is not available. The error message
231 seen with trace enabled will be "SSL_GET_NEW_SESSION:ssl session id callback
232 failed". In order to fix this, you must install Sun patch 112438-03 from
233 http://sunsolve.sun.com
235 #: unzip 112438-03.zip
236 #: patchadd ./112438-03
237 You will probably need to reboot your system:
240 I have a report (schinder@@pobox._com) of make test segfaulting on
241 Linux-PPC. This still needs to be investigated. No recent information
244 It seems perl5.004 (at least some versions) has bad xsub compiler which
245 can make builds sometimes fail. Try upgrading to perl-5.6.1 first.
247 "Random number generator not seeded!!!" This warning indicates that
248 randomize() was not able to read /dev/random or /dev/urandom, possibly
249 because your system does not have them or they are differently
250 named. You can still use SSL, but the encryption will not be as
253 Did you read the POD documentation (if you don't know what that
254 is, just say `perldoc Net::SSLeay' or `more SSLeay.pm')?
256 Are you sure you didn't confuse `Net::SSLeay' with `SSLeay' that
259 My development environments used to be
261 i686, Linux-2.4.3, gcc-2.92.2, glibc-2.2, perl-5.6.0, openssl-0.9.6a
262 i686, Linux-2.4.3, gcc-2.92.2, glibc-2.2, perl5.005_02, openssl-0.9.6a
263 i686, Linux-2.0.35, gcc-2.7.2.3, glibc-2.0.6, perl5.005_02, openssl-0.9.5a
264 i586, Linux-2.4.3, gcc-2.92.2.1, glibc-2.2.2, perl-5.6.0, openssl-0.9.6a
265 i586, Linux-2.4.3, gcc-2.92.2.1, glibc-2.2.2, perl5.005_03, openssl-0.9.6
266 i586, Linux-2.4.3, gcc-2.92.2.1, glibc-2.2.2, perl5.005_03, openssl-0.9.6a
267 Sun-U1, SunOS-5.6, gcc-2.92.2, libc2 perl-5.6.1, openssl-0.9.6c
269 Unfortunately I do not have access to other systems so you are
270 somewhat on your own. Everything compiles without a warning (except
271 those mentioned above) on my systems.
273 Check if there are any post release building hints in
275 http://www.symlabs.com/Net_SSLeay/index.html
277 Check that perl is finding your OpenSSL.
279 If `make test' bombs, add following line to the test script that fails:
281 $Net::SSLeay::trace = 2;
283 and see what happens. You may also have to edit test.pl to make sure
284 the debugging output gets printed.
286 If `make test' prints lots of `connect: Connection refused...' errors,
287 then sslecho.pl test server has died. It is supposed to be launched in
288 the beginning of test.pl, but can fail if, e.g. port 1212 is taken or
289 in TIMEWAIT state. Look also in ssleacho.log file for diagnostics.
291 If you are really low on memory and the 1 MB tests fail, edit value of
292 $mb variable in test.pl.
294 If you get core dump, build your perl for debugging (add -g to
295 ccflags, see INSTALL in perl distribution), build your SSLeay for
296 debugging as well, add -g flag to Makefile.PL:
302 gdb perl core # post mortem
303 > bt # show stack trace
304 gdb perl # run live with debugging
305 # set break point in SSLeay.xs or in suspect function of OpenSSL
306 > br XS_Net__SSLeay_connect
307 > run yourscript.pl arg arg
309 For gdb'ing make sure gdb finds all the relevant source code. This
310 may mean that you must run perl and OpenSSL from the directories where
311 the respective makefiles build them.
313 You can also enable PR and PRN macros in SSLeay.xs and sprinkle
314 even some more around the code to figure out what's happening.
316 Some exotic configurations of perl may cause unstability: make sure
317 OpenSSL uses the same malloc as perl. Recompile perl without
318 threads. Try not using the PerlIO abstraction.
320 If you need to tweak build for some platform, please let me know
321 so I can fix it. Patches and gdb session dumps are also welcome.
326 Copyright (c) 1996-2002 Sampo Kellomaki <sampo@symlabs.com>
327 Copyright (c) 2005 Florian Ragwitz <rafl@debian.org>
328 Copyright (c) 2005 Mike McCauley <mikem@open.com.au>
331 Distribution and use of this module is under the same terms as the
332 OpenSSL package itself (i.e. free, but mandatory attribution; NO
333 WARRANTY). Please consult LICENSE file in the root of the OpenSSL
336 While the source distribution of this perl module does not contain
337 Eric's or OpenSSL's code, if you use this module you will use OpenSSL
338 library. Please give Eric and OpenSSL team credit (as required by
341 And remember, you, and nobody else but you, are responsible for
342 auditing this module and OpenSSL library for security problems,
343 backdoors, and general suitability for your application.
348 ===> HTTP protocol specification. It applies 100% to HTTPS too and doing
349 password authentication is explained there. <===
351 If you are newbie interested in grabbing web pages from https servers,
352 please read HTTP documentation from http://www.w3c.org/ before asking trivial
353 questions. That document also covers the basic-auth FAQ (URLs like
354 http://user:pass@host). Do not ask questions about authentication before
355 consulting the HTTP specification. HTTPS is just HTTP in SSL transport.
357 If you are doing advanced stuff, and don't find documentation you need,
358 please try to extrapolate from OpenSSL documentation (which unfortunately
359 is quite sparse) and the source code.
361 If you run into build problems, especially regarding shared libraries,
362 check your perl documentation, especially the perlxtut(1) man page,
363 which gives excellent tutorial of the build process of XSUBs.
370 Say `perldoc Net::SSLeay' _NOW_!
372 To download OpenSSL, try URL http://www.openssl.org/
374 Of related interest may be `http://www.symlabs.com/Net_SSLeay/smime.html'
376 Bug reports, patch submission, feature requests, subversion access to the latest
377 source code etc can be obtained at
378 http://alioth.debian.org/projects/net-ssleay
380 The developer mailing list (for people interested in contributin to the source code)
382 http://lists.alioth.debian.org/mailman/listinfo/net-ssleay-devel