Debian Codegraph @

README

raw
1 Net-SSLeay - Perl bindings for OpenSSL and LibreSSL
2
3 By popular demand...
4 --------------------
5
6 perl -MNet::SSLeay -e '($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p'
7
8
9 for the released versions:
10 https://metacpan.org/release/Net-SSLeay
11
12 for the latest and possibly unstable version from git:
13 https://github.com/radiator-software/p5-net-ssleay
14
15
16 Prerequisites
17 -------------
18
19 Perl 5.8.1 or higher.
20
21 One of the following libssl implementations:
22
23 * Any stable release of OpenSSL (https://www.openssl.org) in the
24 0.9.8 - 3.6 branches, except for OpenSSL 0.9.8 - 0.9.8b.
25 * Any stable release of LibreSSL (https://www.libressl.org) in the
26 2.0 - 4.2 series, except for LibreSSL 3.2.2 and 3.2.3.
27
28 Net-SSLeay may not compile or pass its tests against releases other
29 than the ones listed above due to libssl API incompatibilities, or, in
30 the case of LibreSSL, because of deviations from the libssl API.
31
32 If you are using a version of OpenSSL or LibreSSL distributed by your
33 operating system vendor, you may also need to install a "development"
34 package containing the header files that correspond to the OpenSSL or
35 LibreSSL library package. Examples include:
36
37 * libssl-dev for OpenSSL on Debian and Ubuntu;
38 * openssl-devel for OpenSSL on Red Hat Enterprise Linux and Fedora.
39
40 On Linux, zlib is also required, even when libssl is built without
41 support for TLS compression. zlib is probably also available via your
42 Linux distribution's package manager, e.g.:
43
44 * zlib1g-dev on Debian and Ubuntu;
45 * zlib-devel on Red Hat Enterprise Linux and Fedora.
46
47 A future version of Net-SSLeay will remove this requirement when
48 building against a libssl without support for TLS compression.
49
50 If there are build errors, test failures or run-time malfunctions, try
51 to use the same compiler and options to compile your OpenSSL, Perl,
52 and Net::SSLeay. Mixing compilers and options may lead to build
53 errors, test failures or run-time malfunctions, that are difficult to
54 debug. The situation in 2024 is that, for example, compiling Perl with
55 gcc and Net::SSLeay with clang works on Linux and macOS. With Windows
56 it may be easier to use the same compiler and compiler options.
57
58
59 Installing
60 ----------
61
62 General:
63 Makefile.PL tries to find OpenSSL installation location from a
64 number of pre-defined paths. It will print the version and
65 location of OpenSSL or LibreSSL it finds, or warn if it doesn't
66 find anything usable.
67
68 If your OpenSSL is installed in an unusual place, you can tell
69 Makefile.PL from where to find it with by setting the
70 OPENSSL_PREFIX environment variable.
71
72 On Linux, macOS and other Unix type systems:
73 OPENSSL_PREFIX=/home/mikem/playpen/openssl-1.0.2c perl Makefile.PL
74
75 On Windows:
76 set OPENSSL_PREFIX=C:\playpen\openssl-1.0.2.c
77 perl Makefile.PL
78
79 The logic in Makefile.PL tries to resolve the required
80 libraries and include directories based on the environment
81 variable OPENSSL_PREFIX.
82
83 Unix:
84 Build or install OpenSSL as per instructions in that
85 package. Review section 'General:' above before continuing.
86
87 gunzip <Net-SSLeay.pm-1.35.tar.gz | tar xvf -
88 cd Net-SSLeay.pm-1.35
89 perl Makefile.PL # Build it. Use OPENSSL_PREFIX, if needed.
90 make test # Run the test suite
91 make install # You probably have to su to root to do this
92
93 HPUX:
94 In principle the Unix build should work (Makefile.PL contains
95 special code to detect aCC), but historically there have been
96 some problems. Marko Asplund (aspa@@kronodoc._fi) reports
97 that he has successfully compiled on HP-UX. He used following
98 incantations
99
100 Configuring OpenSSL:
101
102 ./Configure no-asm --prefix=/openssl/path hpux-parisc2-cc
103
104 Configuring Net::SSLeay:
105
106 OPENSSL_PREFIX=/openssl/path perl Makefile.PL CCFLAGS='-D_HPUX_SOURCE \
107 -Aa -I/usr/local/include +e'
108
109 The magic bit seemed to be the `+e' flag. Since version 1.14
110 Makefile.PL tries to figure this out.
111
112 He was using: gcc v2.95.2, OpenSSL v0.9.6c, Net::SSLeay-1.13
113
114 Windows:
115 Supported on 32 and 64 bit platforms
116 See README.Win32 for details
117
118 macOS, also known as OS X:
119 See README.OSX
120 ---------------------------------
121 You should also be able to use CPAN.pm to install this module if you like.
122
123 Problems (read this before filing a bug)
124 ----------------------------------------
125
126 Please, do not send bug report before you have
127
128 - compiled your OpenSSL yourself - don't copy binaries, please
129 - compiled your perl yourself and with substantially same CFLAGS
130 and same C compiler (say `which cc' or `which gcc') as your OpenSSL.
131 This is especially applicable to link errors and shared
132 library loading problems. Please do not even dream of
133 copying a perl binary or installing perl binary from a package.
134 Perl's idea of calling conventions has to match OpenSSL's and
135 unfortunately both are quite advanced pieces of code
136 (guru duel: Larry Wall vs. Eric Young :-) with dynamic loading
137 and who knows what
138 - compiled my module from source against correct perl (say `which perl'
139 and check your path). Generally my module's build process will
140 discover correct compiler and flags from `perl -V'
141 - tried gcc, if your vendor cc fails
142
143 If you post a question or make a bug report, please remember to mention
144
145 - Your platform and OS version (i386 Linux, Sparc Solaris, etc) (uname -a)
146 - On Linux, please report glibc version as well (ls -l /lib/libc*)
147 - Net::SSLeay version (see tar ball)
148 - OpenSSL version (`/usr/local/ssl/bin/openssl version')
149 - ANSI C compiler brand and version (e.g. gcc -v)
150
151 If build fails,
152 - Dop you have OpenSSL headers installed? Perhaps you need the OpenSSL Devel
153 package for your Linux distribution.
154 - three compiler warnings are known to be emitted (due to lack of const
155 in some places), one of them indicates a fatal bug in callback handling,
156 but as I have not yet sorted it out, you'll simply have to ignore it
157 - if you installed OpenSSL from some distribution, try getting a fresh
158 copy from www.openssl.org and recompiling and installing it yourself
159 - if using newer than supported OpenSSL, please downgrade to supported
160 version to see if it makes difference
161 - you must compile the module, perl, and openssl with the same C compiler
162 and the same options. Use perl -V to check what options were used and
163 recompile openssl and Net::SSLeay accordingly
164 - never report bugs related to binary installs. First compile _yourself_
165 perl, openssl and my module, always using the same compiler and
166 compiler flags. Many distros are known to "know better" and thus
167 cause problems for their users. I'm not very sympathetic to having
168 to answer end user questions thus created.
169 - send full output of `make clean; perl Makefile.PL -t'
170
171 If make test fails, please
172 - one warning is known to be emitted between tests 4 and 5 (callback)
173 - edit test.pl and set $trace=2
174 - send full output of `make clean; perl Makefile.PL -t'
175 - send contents of sslecho.log
176
177 If you have problems with a site, please
178 - what site, what server software (including version and platform)
179 - does it reproduce with s_client, try with something like
180
181 echo 'GET /' | /usr/local/ssl/bin/openssl s_client -connect www.bacus.pt:443
182
183 - does it reproduce with popular web browsers
184 - play with Net::SSLeay::ssl_version (see top of SSLeay.pm)
185 - does the site run exotic configuration, e.g. insisting on specific
186 protocol version, limiting available ciphers, using nonstandard
187 ciphers, weird authentication arrangements, etc.)
188 - contact the owner of the server to see what the problem looks like
189 in his end. He should be able to tell you the exact versions used
190 and the error messages he is seeing in his log
191 - if you ask me to check a site out, you are granting me permission
192 to access that site and will pay all legal expenses to defend me
193 in court as well as any remedies that may be granted to the site
194 in case the site decides to sue me. You warrant that you are
195 authorized to give me permission to access the site.
196 - if you ask me to check a site, please send me a working URL and
197 include any authentication credentials if needed. If your site
198 is so confidential that you can not give me an URL, then do
199 not ask me to debug your problems.
200
201 HP-UX is known to give some problems, please mail me or the mailing
202 list so we can get these problems straightened. Hint: it has to do
203 with dynamic loading. One user reports that adding `-lgcc' to EXTRALIBS
204 and LD_LOAD_LIBS in Makefile fixes the problem. I have not received any
205 confirmation whether this fix really works, but its worth a try. Another
206 bag of problems is people installing against binary distributed
207 perl and compiling the package with different cc or different options.
208 Genereally this will never work. Please compile _yourself_ your perl,
209 openssl, and the module, always with the same compiler and compiler flags.
210
211 Solaris 8 does not come standard with /dev/random or /dev/urandom, and the
212 'make test' assumes that some source of randomness is available. 'make test'
213 will fail on Solaris 8 if /dev/urandom is not available. The error message
214 seen with trace enabled will be "SSL_GET_NEW_SESSION:ssl session id callback
215 failed". In order to fix this, you must install Sun patch 112438-03 from
216 http://sunsolve.sun.com
217
218 #: unzip 112438-03.zip
219 #: patchadd ./112438-03
220 You will probably need to reboot your system:
221 #: reboot
222
223 I have a report (schinder@@pobox._com) of make test segfaulting on
224 Linux-PPC. This still needs to be investigated. No recent information
225 has been received.
226
227 "Random number generator not seeded!!!" This warning indicates that
228 randomize() was not able to read /dev/random or /dev/urandom, possibly
229 because your system does not have them or they are differently
230 named. You can still use SSL, but the encryption will not be as
231 strong.
232
233 Did you read the POD documentation (if you don't know what that
234 is, just say `perldoc Net::SSLeay' or `more SSLeay.pm')?
235
236 Are you sure you didn't confuse `Net::SSLeay' with `SSLeay' that
237 comes with OpenSSL?
238
239 Check that perl is finding your OpenSSL.
240
241 If `make test' bombs, add following line to the test script that fails:
242
243 $Net::SSLeay::trace = 2;
244
245 and see what happens. You may also have to edit test.pl to make sure
246 the debugging output gets printed.
247
248 If `make test' prints lots of `connect: Connection refused...' errors,
249 then sslecho.pl test server has died. It is supposed to be launched in
250 the beginning of test.pl, but can fail if, e.g. port 1212 is taken or
251 in TIMEWAIT state. Look also in ssleacho.log file for diagnostics.
252
253 If you are really low on memory and the 1 MB tests fail, edit value of
254 $mb variable in test.pl.
255
256 If you get core dump, build your perl for debugging (add -g to
257 ccflags, see INSTALL in perl distribution), build your SSLeay for
258 debugging as well, add -g flag to Makefile.PL:
259
260 make clean
261 perl Makefile.PL -g
262 make static
263 make test_static
264 gdb perl core # post mortem
265 > bt # show stack trace
266 gdb perl # run live with debugging
267 # set break point in SSLeay.xs or in suspect function of OpenSSL
268 > br XS_Net__SSLeay_connect
269 > run yourscript.pl arg arg
270
271 For gdb'ing make sure gdb finds all the relevant source code. This
272 may mean that you must run perl and OpenSSL from the directories where
273 the respective makefiles build them.
274
275 You can also enable PR and PRN macros in SSLeay.xs and sprinkle
276 even some more around the code to figure out what's happening.
277
278 Some exotic configurations of perl may cause unstability: make sure
279 OpenSSL uses the same malloc as perl. Recompile perl without
280 threads. Try not using the PerlIO abstraction.
281
282 If you need to tweak build for some platform, please let me know
283 so I can fix it. Patches and gdb session dumps are also welcome.
284
285 Copyright
286 ---------
287
288 Copyright (c) 1996-2003 Sampo Kellomäki <[email protected]>
289 Copyright (c) 2005-2010 Florian Ragwitz <[email protected]>
290 Copyright (c) 2005-2018 Mike McCauley <[email protected]>
291 Copyright (c) 2018 Tuure Vartiainen <[email protected]>
292 Copyright (c) 2018- Chris Novakovic <[email protected]>
293 Copyright (c) 2018- Heikki Vatiainen <[email protected]>
294
295 All rights reserved.
296
297 License
298 -------
299
300 Net-SSLeay is released under the terms of the Artistic License 2.0. For
301 details, see the LICENSE file.
302
303 Recommended reading
304 -------------------
305
306 ===> HTTP protocol specification. It applies 100% to HTTPS too and doing
307 password authentication is explained there. <===
308
309 If you are newbie interested in grabbing web pages from https servers,
310 please read HTTP documentation from http://www.w3c.org/ before asking trivial
311 questions. That document also covers the basic-auth FAQ (URLs like
312 http://user:pass@host). Do not ask questions about authentication before
313 consulting the HTTP specification. HTTPS is just HTTP in SSL transport.
314
315 If you are doing advanced stuff, and don't find documentation you need,
316 please try to extrapolate from OpenSSL documentation (which unfortunately
317 is quite sparse) and the source code.
318
319 If you run into build problems, especially regarding shared libraries,
320 check your perl documentation, especially the perlxtut(1) man page,
321 which gives excellent tutorial of the build process of XSUBs.
322
323 perlxtut(1)
324 perlxs(1)
325 perlguts(1)
326 perlcall(1)
327
328 Say `perldoc Net::SSLeay' _NOW_!
329
330 To download OpenSSL, see https://www.openssl.org/
331
332 Bug reports, patch submission, feature requests and git access to the
333 latest source code etc., can be obtained at
334 https://github.com/radiator-software/p5-net-ssleay
335
336