forked from radiator-software/p5-net-ssleay
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
334 lines (255 loc) · 13.5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
README - Net::SSLeay Perl module for using OpenSSL
By popular demand...
--------------------
perl -MNet::SSLeay -e '($p)=Net::SSLeay::get_https("www.openssl.org", 443, "/"); print $p'
for the released versions:
https://metacpan.org/release/Net-SSLeay
for the latest and possibly unstable version from git:
https://github.com/radiator-software/p5-net-ssleay
Prerequisites
-------------
Perl 5.8.1 or higher.
OpenSSL-0.9.6j through to at least OpenSSL-1.1 and probably later
http://www.openssl.org/ - On Linux, you can either build and
install OpenSSL from scratch (its very portable) or you can
install the appropriate OpenSSL 'devel' package for your Linux
distribution: (rpm openssl-devel, deb libssl-dev).
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.
LibreSSL is also supported.
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 or install OpenSSL as per instructions in that package
gunzip <Net-SSLeay.pm-1.35.tar.gz | tar xvf -
cd Net-SSLeay.pm-1.35
perl Makefile.PL # builds and tests it
make test # Run the test suite
make install # You probably have to su to root to do this
If your OpenSSL is installed in an unusual place, you can tell
Net-SSLeay where to find it with the OPENSSL_PREFIX environment
variable:
OPENSSL_PREFIX=/home/mikem/playpen/openssl-1.0.2c perl Makefile.PL
....
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:
Supported on 32 and 64 bit platforms
See README.Win32 for details
OS X:
See README.OSX
---------------------------------
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
due 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 remember 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,
- Dop you have OpenSSL headers installed? Perhaps you need the OpenSSL Devel
package for your Linux distribution.
- 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.
"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?
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-2003 Sampo Kellomäki <[email protected]>
Copyright (c) 2005-2010 Florian Ragwitz <[email protected]>
Copyright (c) 2005-2018 Mike McCauley <[email protected]>
Copyright (c) 2018- Chris Novakovic <[email protected]>
Copyright (c) 2018- Tuure Vartiainen <[email protected]>
Copyright (c) 2018- Heikki Vatiainen <[email protected]>
All Rights Reserved.
From version
1.66 onwards, this Net-SSLeay package is issued under the "Perl Artistic
License 2.0", the same license as Perl itself.
The Authors credit Eric Young and the OpenSSL team with the development of the
excellent OpenSSL library, which this Perl package uses.
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, see https://www.openssl.org/
Bug reports, patch submission, feature requests and git access to the
latest source code etc., can be obtained at
https://github.com/radiator-software/p5-net-ssleay