Net::SSLeay::Handle(3pm)

1Handle(3)             User Contributed Perl Documentation            Handle(3)
2
3
4

NAME

6       Net::SSLeay::Handle - Perl module that lets SSL (HTTPS) sockets be han‐
7       dled as standard file handles.
8

SYNOPSIS

10         use Net::SSLeay::Handle qw/shutdown/;
11         my ($host, $port) = ("localhost", 443);
12
13         tie(*SSL, "Net::SSLeay::Handle", $host, $port);
14
15         print SSL "GET / HTTP/1.0\r\n";
16         shutdown(\*SSL, 1);
17         print while (<SSL>);
18         close SSL;
19

DESCRIPTION

21       Net::SSLeay::Handle allows you to request and receive HTTPS web pages
22       using "old-fashion" file handles as in:
23
24           print SSL "GET / HTTP/1.0\r\n";
25
26       and
27
28           print while (<SSL>);
29
30       If you export the shutdown routine, then the only extra code that you
31       need to add to your program is the tie function as in:
32
33           my $socket;
34           if ($scheme eq "https") {
35               tie(*S2, "Net::SSLeay::Handle", host, $port);
36               $socket = \*S2;
37           else {
38               $socket = Net::SSLeay::Handle->make_socket(host, $port);
39           }
40           print $socket $request_headers;
41           ...
42
43       USING EXISTING SOCKETS
44
45       One of the motivations for writing this module was to avoid duplicating
46       socket creation code (which is mostly error handling).  The calls to
47       tie() above where it is passed a $host and $port is provided for conve‐
48       nience testing.  If you already have a socket connected to the right
49       host and port, S1, then you can do something like:
50
51           my $socket \*S1;
52           if ($scheme eq "https") {
53               tie(*S2, "Net::SSLeay::Handle", $socket);
54               $socket = \*S2;
55           }
56           my $last_sel = select($socket); $⎪ = 1; select($last_sel);
57           print $socket $request_headers;
58           ...
59
60       Note: As far as I know you must be careful with the globs in the tie()
61       function.  The first parameter must be a glob (*SOMETHING) and the last
62       parameter must be a reference to a glob (\*SOMETHING_ELSE) or a scaler
63       that was assigned to a reference to a glob (as in the example above)
64
65       Also, the two globs must be different.  When I tried to use the same
66       glob, I got a core dump.
67
68       EXPORT
69
70       None by default.
71
72       You can export the shutdown() function.
73
74       It is suggested that you do export shutdown() or use the fully quali‐
75       fied Net::SSLeay::Handle::shutdown() function to shutdown SSL sockets.
76       It should be smart enough to distinguish between SSL and non-SSL sock‐
77       ets and do the right thing.
78

EXAMPLES

80         use Net::SSLeay::Handle qw/shutdown/;
81         my ($host, $port) = ("localhost", 443);
82
83         tie(*SSL, "Net::SSLeay::Handle", $host, $port);
84
85         print SSL "GET / HTTP/1.0\r\n";
86         shutdown(\*SSL, 1);
87         print while (<SSL>);
88         close SSL;
89

TODO

91       Better error handling.  Callback routine?
92

CAVEATS

94       Tying to a file handle is a little tricky (for me at least).
95
96       The first parameter to tie() must be a glob (*SOMETHING) and the last
97       parameter must be a reference to a glob (\*SOMETHING_ELSE) or a scaler
98       that was assigned to a reference to a glob ($s = \*SOMETHING_ELSE).
99       Also, the two globs must be different.  When I tried to use the same
100       glob, I got a core dump.
101
102       I was able to associate attributes to globs created by this module
103       (like *SSL above) by making a hash of hashes keyed by the file head1.
104
105       Support for old perls may not be 100%. If in trouble try 5.6.0 or
106       newer.
107

CHANGES

109       Please see Net-SSLeay-Handle-0.50/Changes file.
110

KNOWN BUGS

112       If you let this module construct sockets for you with Perl versions
113       below v.5.6 then there is a slight memory leak.  Other upgrade your
114       Perl, or create the sockets yourself.  The leak was created to let
115       these older versions of Perl access more than one Handle at a time.
116

AUTHOR

118       Jim Bowlin jbowlin@linklint.org
119