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
|
NAME
IO::Async::SSL - use SSL/TLS with IO::Async
SYNOPSIS
use IO::Async::Loop;
use IO::Async::SSL;
my $loop = IO::Async::Loop->new();
$loop->SSL_connect(
host => "www.example.com",
service => "https",
on_stream => sub {
my ( $stream ) = @_;
$stream->configure(
on_read => sub {
...
},
);
$loop->add( $stream );
...
},
on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
on_connect_error => sub { print STDERR "Cannot connect\n"; },
on_ssl_error => sub { print STDERR "Cannot negotiate SSL - $_[-1]\n"; },
);
DESCRIPTION
This module extends existing IO::Async classes with extra methods to
allow the use of SSL or TLS-based connections using IO::Socket::SSL. It
does not directly provide any methods or functions of its own.
Primarily, it provides SSL_connect and SSL_listen, which yield
IO::Socket::SSL-upgraded socket handles or IO::Async::Stream instances,
and two forms of SSL_upgrade to upgrade an existing TCP connection to
use SSL.
As an additional convenience, if the SSL_verify_mode and SSL_ca_*
options are omitted, the module will attempt to provide them by
querying the result of IO::Socket::SSL's default_ca function.
Otherwise, the module will print a warning and set SSL_VERIFY_NONE
instead.
LOOP METHODS
The following extra methods are added to IO::Async::Loop.
SSL_upgrade
( $stream or $socket ) = $loop->SSL_upgrade( %params )->get;
This method upgrades a given stream filehandle into an SSL-wrapped
stream, returning a future which will yield the given stream object or
socket.
Takes the following parameters:
handle => IO::Async::Stream | IO
The IO::Async::Stream object containing the IO handle of an
already-established connection to act as the transport for SSL; or
the plain IO socket handle itself.
If an IO::Async::Stream is passed it will have the reader and writer
functions set on it suitable for SSL use, and will be returned as the
result from the future.
If a plain socket handle is passed, that will be returned from the
future instead.
SSL_server => BOOL
If true, indicates this is the server side of the connection.
In addition, any parameter whose name starts SSL_ will be passed to the
IO::Socket::SSL constructor.
The following legacy callback arguments are also supported, in case the
returned future is not used:
on_upgraded => CODE
A continuation that is invoked when the socket has been successfully
upgraded to SSL. It will be passed an instance of an IO::Socket::SSL,
which will have appropriate SSL-compatible reader/writer functions
attached.
$on_upgraded->( $sslsocket )
on_error => CODE
A continuation that is invoked if IO::Socket::SSL detects an error
while negotiating the upgrade.
$on_error->( $! )
SSL_connect
$stream = $loop->SSL_connect( %params )->get;
This method performs a non-blocking connection to a given address or
set of addresses, upgrades the socket to SSL, then yields a
IO::Async::Stream object when the SSL handshake is complete.
It takes all the same arguments as IO::Async::Loop::connect(). Any
argument whose name starts SSL_ will be passed on to the
IO::Socket::SSL constructor rather than the Loop's connect method. It
is not required to pass the socktype option, as SSL implies this will
be stream.
This method can also upgrade an existing IO::Async::Stream or subclass
instance given as the handle argument, by setting the reader and writer
functions.
SSL_connect (void)
$loop->SSL_connect( %params,
on_connected => sub { ... },
on_stream => sub { ... },
);
When not returning a future, this method also supports the on_connected
and on_stream continuations.
In addition, the following arguments are then required:
on_ssl_error => CODE
A continuation that is invoked if IO::Socket::SSL detects an
SSL-based error once the actual stream socket is connected.
If the on_connected continuation is used, the socket handle it yields
will be a IO::Socket::SSL, which must be wrapped in
IO::Async::SSLStream to be used by IO::Async. The on_stream
continuation will already yield such an instance.
SSL_listen
$loop->SSL_listen( %params )->get;
This method sets up a listening socket using the addresses given, and
will invoke the callback each time a new connection is accepted on the
socket and the SSL handshake has been completed. This can be either the
on_accept or on_stream continuation; on_socket is not supported.
It takes all the same arguments as IO::Async::Loop::listen(). Any
argument whose name starts SSL_ will be passed on to the
IO::Socket::SSL constructor rather than the Loop's listen method. It is
not required to pass the socktype option, as SSL implies this will be
stream.
In addition, the following arguments are rquired:
on_ssl_error => CODE
A continuation that is invoked if IO::Socket::SSL detects an
SSL-based error once the actual stream socket is connected.
The underlying IO::Socket::SSL socket will also require the server key
and certificate for a server-mode socket. See its documentation for
more details.
If the on_accept continuation is used, the socket handle it yields will
be a IO::Socket::SSL, which must be wrapped in IO::Async::SSLStream to
be used by IO::Async. The on_stream continuation will already yield
such an instance.
STREAM PROTOCOL METHODS
The following extra methods are added to IO::Async::Protocol::Stream.
SSL_upgrade
$protocol->SSL_upgrade( %params )->get;
A shortcut to calling $loop->SSL_upgrade. This method will unconfigure
the transport of the Protocol, upgrade its underlying filehandle to
SSL, then reconfigure it again with SSL reader and writer functions on
it. It takes the same arguments as $loop->SSL_upgrade, except that the
handle argument is not required as it's taken from the Protocol's
transport.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
|
