[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Handle.pm

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.132 by elmex, Thu Jul 2 22:25:13 2009 UTC vs.
Revision 1.146 by root, Wed Jul 8 13:46:46 2009 UTC

…		…
14		14
15	AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent	15	AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16		16
17	=cut	17	=cut
18		18
19	our $VERSION = 4.45;	19	our $VERSION = 4.8;
20		20
21	=head1 SYNOPSIS	21	=head1 SYNOPSIS
22		22
23	use AnyEvent;	23	use AnyEvent;
24	use AnyEvent::Handle;	24	use AnyEvent::Handle;
…		…
95	waiting for data.	95	waiting for data.
96		96
97	If an EOF condition has been detected but no C<on_eof> callback has been	97	If an EOF condition has been detected but no C<on_eof> callback has been
98	set, then a fatal error will be raised with C<$!> set to <0>.	98	set, then a fatal error will be raised with C<$!> set to <0>.
99		99
100	=item on_error => $cb->($handle, $fatal)	100	=item on_error => $cb->($handle, $fatal, $message)
101		101
102	This is the error callback, which is called when, well, some error	102	This is the error callback, which is called when, well, some error
103	occured, such as not being able to resolve the hostname, failure to	103	occured, such as not being able to resolve the hostname, failure to
104	connect or a read error.	104	connect or a read error.
105		105
…		…
107	fatal errors the handle object will be shut down and will not be usable	107	fatal errors the handle object will be shut down and will not be usable
108	(but you are free to look at the current C<< ->rbuf >>). Examples of fatal	108	(but you are free to look at the current C<< ->rbuf >>). Examples of fatal
109	errors are an EOF condition with active (but unsatisifable) read watchers	109	errors are an EOF condition with active (but unsatisifable) read watchers
110	(C<EPIPE>) or I/O errors.	110	(C<EPIPE>) or I/O errors.
111		111
		112	AnyEvent::Handle tries to find an appropriate error code for you to check
		113	against, but in some cases (TLS errors), this does not work well. It is
		114	recommended to always output the C<$message> argument in human-readable
		115	error messages (it's usually the same as C<"$!">).
		116
112	Non-fatal errors can be retried by simply returning, but it is recommended	117	Non-fatal errors can be retried by simply returning, but it is recommended
113	to simply ignore this parameter and instead abondon the handle object	118	to simply ignore this parameter and instead abondon the handle object
114	when this callback is invoked. Examples of non-fatal errors are timeouts	119	when this callback is invoked. Examples of non-fatal errors are timeouts
115	C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).	120	C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
116		121
117	On callback entrance, the value of C<$!> contains the operating system	122	On callback entrance, the value of C<$!> contains the operating system
118	error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>).	123	error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
		124	C<EPROTO>).
119		125
120	While not mandatory, it is I<highly> recommended to set this callback, as	126	While not mandatory, it is I<highly> recommended to set this callback, as
121	you will not be notified of errors otherwise. The default simply calls	127	you will not be notified of errors otherwise. The default simply calls
122	C<croak>.	128	C<croak>.
123		129
…		…
127	and no read request is in the queue (unlike read queue callbacks, this	133	and no read request is in the queue (unlike read queue callbacks, this
128	callback will only be called when at least one octet of data is in the	134	callback will only be called when at least one octet of data is in the
129	read buffer).	135	read buffer).
130		136
131	To access (and remove data from) the read buffer, use the C<< ->rbuf >>	137	To access (and remove data from) the read buffer, use the C<< ->rbuf >>
132	method or access the C<$handle->{rbuf}> member directly. Note that you	138	method or access the C<< $handle->{rbuf} >> member directly. Note that you
133	must not enlarge or modify the read buffer, you can only remove data at	139	must not enlarge or modify the read buffer, you can only remove data at
134	the beginning from it.	140	the beginning from it.
135		141
136	When an EOF condition is detected then AnyEvent::Handle will first try to	142	When an EOF condition is detected then AnyEvent::Handle will first try to
137	feed all the remaining data to the queued callbacks and C<on_read> before	143	feed all the remaining data to the queued callbacks and C<on_read> before
…		…
237		243
238	This will not work for partial TLS data that could not be encoded	244	This will not work for partial TLS data that could not be encoded
239	yet. This data will be lost. Calling the C<stoptls> method in time might	245	yet. This data will be lost. Calling the C<stoptls> method in time might
240	help.	246	help.
241		247
242	=item common_name => $string	248	=item peername => $string
243		249
244	The common name used by some verification methods (most notably SSL/TLS)	250	A string used to identify the remote site - usually the DNS hostname
245	associated with this connection. Usually this is the remote hostname used	251	(I<not> IDN!) used to create the connection, rarely the IP address.
246	to connect, but can be almost anything.	252
		253	Apart from being useful in error messages, this string is also used in TLS
		254	peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
		255	verification will be skipped when C<peername> is not specified or
		256	C<undef>.
247		257
248	=item tls => "accept" \| "connect" \| Net::SSLeay::SSL object	258	=item tls => "accept" \| "connect" \| Net::SSLeay::SSL object
249		259
250	When this parameter is given, it enables TLS (SSL) mode, that means	260	When this parameter is given, it enables TLS (SSL) mode, that means
251	AnyEvent will start a TLS handshake as soon as the conenction has been	261	AnyEvent will start a TLS handshake as soon as the conenction has been
252	established and will transparently encrypt/decrypt data afterwards.	262	established and will transparently encrypt/decrypt data afterwards.
		263
		264	All TLS protocol errors will be signalled as C<EPROTO>, with an
		265	appropriate error message.
253		266
254	TLS mode requires Net::SSLeay to be installed (it will be loaded	267	TLS mode requires Net::SSLeay to be installed (it will be loaded
255	automatically when you try to create a TLS handle): this module doesn't	268	automatically when you try to create a TLS handle): this module doesn't
256	have a dependency on that module, so if your module requires it, you have	269	have a dependency on that module, so if your module requires it, you have
257	to add the dependency yourself.	270	to add the dependency yourself.
…		…
285		298
286	Instead of an object, you can also specify a hash reference with C<< key	299	Instead of an object, you can also specify a hash reference with C<< key
287	=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a	300	=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
288	new TLS context object.	301	new TLS context object.
289		302
		303	=item on_starttls => $cb->($handle, $success[, $error_message])
		304
		305	This callback will be invoked when the TLS/SSL handshake has finished. If
		306	C<$success> is true, then the TLS handshake succeeded, otherwise it failed
		307	(C<on_stoptls> will not be called in this case).
		308
		309	The session in C<< $handle->{tls} >> can still be examined in this
		310	callback, even when the handshake was not successful.
		311
		312	TLS handshake failures will not cause C<on_error> to be invoked when this
		313	callback is in effect, instead, the error message will be passed to C<on_starttls>.
		314
		315	Without this callback, handshake failures lead to C<on_error> being
		316	called, as normal.
		317
		318	Note that you cannot call C<starttls> right again in this callback. If you
		319	need to do that, start an zero-second timer instead whose callback can
		320	then call C<< ->starttls >> again.
		321
		322	=item on_stoptls => $cb->($handle)
		323
		324	When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
		325	set, then it will be invoked after freeing the TLS session. If it is not,
		326	then a TLS shutdown condition will be treated like a normal EOF condition
		327	on the handle.
		328
		329	The session in C<< $handle->{tls} >> can still be examined in this
		330	callback.
		331
		332	This callback will only be called on TLS shutdowns, not when the
		333	underlying handle signals EOF.
		334
290	=item json => JSON or JSON::XS object	335	=item json => JSON or JSON::XS object
291		336
292	This is the json coder object used by the C<json> read and write types.	337	This is the json coder object used by the C<json> read and write types.
293		338
294	If you don't supply it, then AnyEvent::Handle will create and use a	339	If you don't supply it, then AnyEvent::Handle will create and use a
…		…
316	$self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};	361	$self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
317		362
318	$self->starttls (delete $self->{tls}, delete $self->{tls_ctx})	363	$self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
319	if $self->{tls};	364	if $self->{tls};
320		365
321	$self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};	366	$self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
322		367
323	$self->start_read	368	$self->start_read
324	if $self->{on_read};	369	if $self->{on_read};
325		370
326	$self->{fh} && $self	371	$self->{fh} && $self
…		…
334		379
335	&_freetls;	380	&_freetls;
336	}	381	}
337		382
338	sub _error {	383	sub _error {
339	my ($self, $errno, $fatal) = @_;	384	my ($self, $errno, $fatal, $message) = @_;
340		385
341	$self->_shutdown	386	$self->_shutdown
342	if $fatal;	387	if $fatal;
343		388
344	$! = $errno;	389	$! = $errno;
		390	$message \|\|= "$!";
345		391
346	if ($self->{on_error}) {	392	if ($self->{on_error}) {
347	$self->{on_error}($self, $fatal);	393	$self->{on_error}($self, $fatal, $message);
348	} elsif ($self->{fh}) {	394	} elsif ($self->{fh}) {
349	Carp::croak "AnyEvent::Handle uncaught error: $!";	395	Carp::croak "AnyEvent::Handle uncaught error: $message";
350	}	396	}
351	}	397	}
352		398
353	=item $fh = $handle->fh	399	=item $fh = $handle->fh
354		400
…		…
413		459
414	eval {	460	eval {
415	local $SIG{__DIE__};	461	local $SIG{__DIE__};
416	setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];	462	setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
417	};	463	};
		464	}
		465
		466	=item $handle->on_starttls ($cb)
		467
		468	Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
		469
		470	=cut
		471
		472	sub on_starttls {
		473	$_[0]{on_starttls} = $_[1];
		474	}
		475
		476	=item $handle->on_stoptls ($cb)
		477
		478	Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
		479
		480	=cut
		481
		482	sub on_starttls {
		483	$_[0]{on_stoptls} = $_[1];
418	}	484	}
419		485
420	#############################################################################	486	#############################################################################
421		487
422	=item $handle->timeout ($seconds)	488	=item $handle->timeout ($seconds)
…		…
521	Scalar::Util::weaken $self;	587	Scalar::Util::weaken $self;
522		588
523	my $cb = sub {	589	my $cb = sub {
524	my $len = syswrite $self->{fh}, $self->{wbuf};	590	my $len = syswrite $self->{fh}, $self->{wbuf};
525		591
526	if ($len >= 0) {	592	if (defined $len) {
527	substr $self->{wbuf}, 0, $len, "";	593	substr $self->{wbuf}, 0, $len, "";
528		594
529	$self->{_activity} = AnyEvent->now;	595	$self->{_activity} = AnyEvent->now;
530		596
531	$self->{on_drain}($self)	597	$self->{on_drain}($self)
…		…
666		732
667	pack "w/a*", Storable::nfreeze ($ref)	733	pack "w/a*", Storable::nfreeze ($ref)
668	};	734	};
669		735
670	=back	736	=back
		737
		738	=item $handle->push_shutdown
		739
		740	Sometimes you know you want to close the socket after writing your data
		741	before it was actually written. One way to do that is to replace your
		742	C<on_drain> handler by a callback that shuts down the socket (and set
		743	C<low_water_mark> to C<0>). This method is a shorthand for just that, and
		744	replaces the C<on_drain> callback with:
		745
		746	sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
		747
		748	This simply shuts down the write side and signals an EOF condition to the
		749	the peer.
		750
		751	You can rely on the normal read queue and C<on_eof> handling
		752	afterwards. This is the cleanest way to close a connection.
		753
		754	=cut
		755
		756	sub push_shutdown {
		757	my ($self) = @_;
		758
		759	delete $self->{low_water_mark};
		760	$self->on_drain (sub { shutdown $_[0]{fh}, 1 });
		761	}
671		762
672	=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)	763	=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
673		764
674	This function (not method) lets you add your own types to C<push_write>.	765	This function (not method) lets you add your own types to C<push_write>.
675	Whenever the given C<type> is used, C<push_write> will invoke the code	766	Whenever the given C<type> is used, C<push_write> will invoke the code
…		…
823		914
824	if ($self->{_eof}) {	915	if ($self->{_eof}) {
825	if ($self->{on_eof}) {	916	if ($self->{on_eof}) {
826	$self->{on_eof}($self)	917	$self->{on_eof}($self)
827	} else {	918	} else {
828	$self->_error (0, 1);	919	$self->_error (0, 1, "Unexpected end-of-file");
829	}	920	}
830	}	921	}
831		922
832	# may need to restart read watcher	923	# may need to restart read watcher
833	unless ($self->{_rw}) {	924	unless ($self->{_rw}) {
…		…
1183	=cut	1274	=cut
1184		1275
1185	register_read_type json => sub {	1276	register_read_type json => sub {
1186	my ($self, $cb) = @_;	1277	my ($self, $cb) = @_;
1187		1278
1188	require JSON;	1279	my $json = $self->{json} \|\|=
		1280	eval { require JSON::XS; JSON::XS->new->utf8 }
		1281	\|\| do { require JSON; JSON->new->utf8 };
1189		1282
1190	my $data;	1283	my $data;
1191	my $rbuf = \$self->{rbuf};	1284	my $rbuf = \$self->{rbuf};
1192
1193	my $json = $self->{json} \|\|= JSON->new->utf8;
1194		1285
1195	sub {	1286	sub {
1196	my $ref = eval { $json->incr_parse ($self->{rbuf}) };	1287	my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1197		1288
1198	if ($ref) {	1289	if ($ref) {
…		…
1342	}	1433	}
1343	});	1434	});
1344	}	1435	}
1345	}	1436	}
1346		1437
		1438	our $ERROR_SYSCALL;
		1439	our $ERROR_WANT_READ;
		1440
		1441	sub _tls_error {
		1442	my ($self, $err) = @_;
		1443
		1444	return $self->_error ($!, 1)
		1445	if $err == Net::SSLeay::ERROR_SYSCALL ();
		1446
		1447	my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
		1448
		1449	# reduce error string to look less scary
		1450	$err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
		1451
		1452	if ($self->{_on_starttls}) {
		1453	(delete $self->{_on_starttls})->($self, undef, $err);
		1454	&_freetls;
		1455	} else {
		1456	&_freetls;
		1457	$self->_error (&Errno::EPROTO, 1, $err);
		1458	}
		1459	}
		1460
1347	# poll the write BIO and send the data if applicable	1461	# poll the write BIO and send the data if applicable
		1462	# also decode read data if possible
		1463	# this is basiclaly our TLS state machine
		1464	# more efficient implementations are possible with openssl,
		1465	# but not with the buggy and incomplete Net::SSLeay.
1348	sub _dotls {	1466	sub _dotls {
1349	my ($self) = @_;	1467	my ($self) = @_;
1350		1468
1351	my $tmp;	1469	my $tmp;
1352		1470
1353	if (length $self->{_tls_wbuf}) {	1471	if (length $self->{_tls_wbuf}) {
1354	while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {	1472	while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1355	substr $self->{_tls_wbuf}, 0, $tmp, "";	1473	substr $self->{_tls_wbuf}, 0, $tmp, "";
1356	}	1474	}
		1475
		1476	$tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
		1477	return $self->_tls_error ($tmp)
		1478	if $tmp != $ERROR_WANT_READ
		1479	&& ($tmp != $ERROR_SYSCALL \|\| $!);
1357	}	1480	}
1358		1481
1359	while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {	1482	while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1360	unless (length $tmp) {	1483	unless (length $tmp) {
1361	# let's treat SSL-eof as we treat normal EOF	1484	$self->{_on_starttls}
1362	delete $self->{_rw};	1485	and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
1363	$self->{_eof} = 1;
1364	&_freetls;	1486	&_freetls;
		1487
		1488	if ($self->{on_stoptls}) {
		1489	$self->{on_stoptls}($self);
		1490	return;
		1491	} else {
		1492	# let's treat SSL-eof as we treat normal EOF
		1493	delete $self->{_rw};
		1494	$self->{_eof} = 1;
		1495	}
1365	}	1496	}
1366		1497
1367	$self->{_tls_rbuf} .= $tmp;	1498	$self->{_tls_rbuf} .= $tmp;
1368	$self->_drain_rbuf unless $self->{_in_drain};	1499	$self->_drain_rbuf unless $self->{_in_drain};
1369	$self->{tls} or return; # tls session might have gone away in callback	1500	$self->{tls} or return; # tls session might have gone away in callback
1370	}	1501	}
1371		1502
1372	$tmp = Net::SSLeay::get_error ($self->{tls}, -1);	1503	$tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1373
1374	if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1375	if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1376	return $self->_error ($!, 1);	1504	return $self->_tls_error ($tmp)
1377	} elsif ($tmp == Net::SSLeay::ERROR_SSL ()) {	1505	if $tmp != $ERROR_WANT_READ
1378	return $self->_error (&Errno::EIO, 1);	1506	&& ($tmp != $ERROR_SYSCALL \|\| $!);
1379	}
1380
1381	# all other errors are fine for our purposes
1382	}
1383		1507
1384	while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {	1508	while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1385	$self->{wbuf} .= $tmp;	1509	$self->{wbuf} .= $tmp;
1386	$self->_drain_wbuf;	1510	$self->_drain_wbuf;
1387	}	1511	}
		1512
		1513	$self->{_on_starttls}
		1514	and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
		1515	and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
1388	}	1516	}
1389		1517
1390	=item $handle->starttls ($tls[, $tls_ctx])	1518	=item $handle->starttls ($tls[, $tls_ctx])
1391		1519
1392	Instead of starting TLS negotiation immediately when the AnyEvent::Handle	1520	Instead of starting TLS negotiation immediately when the AnyEvent::Handle
…		…
1409	If it an error to start a TLS handshake more than once per	1537	If it an error to start a TLS handshake more than once per
1410	AnyEvent::Handle object (this is due to bugs in OpenSSL).	1538	AnyEvent::Handle object (this is due to bugs in OpenSSL).
1411		1539
1412	=cut	1540	=cut
1413		1541
		1542	our %TLS_CACHE; #TODO not yet documented, should we?
		1543
1414	sub starttls {	1544	sub starttls {
1415	my ($self, $ssl, $ctx) = @_;	1545	my ($self, $ssl, $ctx) = @_;
1416		1546
1417	require Net::SSLeay;	1547	require Net::SSLeay;
1418		1548
1419	Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"	1549	Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1420	if $self->{tls};	1550	if $self->{tls};
1421		1551
		1552	$ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
		1553	$ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
		1554
1422	$ctx \|\|= $self->{tls_ctx};	1555	$ctx \|\|= $self->{tls_ctx};
1423		1556
1424	if ("HASH" eq ref $ctx) {	1557	if ("HASH" eq ref $ctx) {
1425	require AnyEvent::TLS;	1558	require AnyEvent::TLS;
1426		1559
1427	local $Carp::CarpLevel = 1; # skip ourselves when creating a new context	1560	local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
		1561
		1562	if ($ctx->{cache}) {
		1563	my $key = $ctx+0;
		1564	$ctx = $TLS_CACHE{$key} \|\|= new AnyEvent::TLS %$ctx;
		1565	} else {
1428	$ctx = new AnyEvent::TLS %$ctx;	1566	$ctx = new AnyEvent::TLS %$ctx;
		1567	}
1429	}	1568	}
1430		1569
1431	$self->{tls_ctx} = $ctx \|\| TLS_CTX ();	1570	$self->{tls_ctx} = $ctx \|\| TLS_CTX ();
1432	$self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self);	1571	$self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
1433		1572
1434	# basically, this is deep magic (because SSL_read should have the same issues)	1573	# basically, this is deep magic (because SSL_read should have the same issues)
1435	# but the openssl maintainers basically said: "trust us, it just works".	1574	# but the openssl maintainers basically said: "trust us, it just works".
1436	# (unfortunately, we have to hardcode constants because the abysmally misdesigned	1575	# (unfortunately, we have to hardcode constants because the abysmally misdesigned
1437	# and mismaintained ssleay-module doesn't even offer them).	1576	# and mismaintained ssleay-module doesn't even offer them).
…		…
1451	$self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());	1590	$self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1452	$self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());	1591	$self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1453		1592
1454	Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});	1593	Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1455		1594
		1595	$self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
		1596	if $self->{on_starttls};
		1597
1456	&_dotls; # need to trigger the initial handshake	1598	&_dotls; # need to trigger the initial handshake
1457	$self->start_read; # make sure we actually do read	1599	$self->start_read; # make sure we actually do read
1458	}	1600	}
1459		1601
1460	=item $handle->stoptls	1602	=item $handle->stoptls
…		…
1472	if ($self->{tls}) {	1614	if ($self->{tls}) {
1473	Net::SSLeay::shutdown ($self->{tls});	1615	Net::SSLeay::shutdown ($self->{tls});
1474		1616
1475	&_dotls;	1617	&_dotls;
1476		1618
1477	# we don't give a shit. no, we do, but we can't. no...	1619	# # we don't give a shit. no, we do, but we can't. no...#d#
1478	# we, we... have to use openssl :/	1620	# # we, we... have to use openssl :/#d#
1479	&_freetls;	1621	# &_freetls;#d#
1480	}	1622	}
1481	}	1623	}
1482		1624
1483	sub _freetls {	1625	sub _freetls {
1484	my ($self) = @_;	1626	my ($self) = @_;
1485		1627
1486	return unless $self->{tls};	1628	return unless $self->{tls};
1487		1629
1488	$self->{tls_ctx}->_put_session (delete $self->{tls});	1630	$self->{tls_ctx}->_put_session (delete $self->{tls});
1489		1631
1490	delete @$self{qw(_rbio _wbio _tls_wbuf)};	1632	delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1491	}	1633	}
1492		1634
1493	sub DESTROY {	1635	sub DESTROY {
1494	my ($self) = @_;	1636	my ($self) = @_;
1495		1637
…		…
1519	}	1661	}
1520		1662
1521	=item $handle->destroy	1663	=item $handle->destroy
1522		1664
1523	Shuts down the handle object as much as possible - this call ensures that	1665	Shuts down the handle object as much as possible - this call ensures that
1524	no further callbacks will be invoked and resources will be freed as much	1666	no further callbacks will be invoked and as many resources as possible
1525	as possible. You must not call any methods on the object afterwards.	1667	will be freed. You must not call any methods on the object afterwards.
1526		1668
1527	Normally, you can just "forget" any references to an AnyEvent::Handle	1669	Normally, you can just "forget" any references to an AnyEvent::Handle
1528	object and it will simply shut down. This works in fatal error and EOF	1670	object and it will simply shut down. This works in fatal error and EOF
1529	callbacks, as well as code outside. It does I<NOT> work in a read or write	1671	callbacks, as well as code outside. It does I<NOT> work in a read or write
1530	callback, so when you want to destroy the AnyEvent::Handle object from	1672	callback, so when you want to destroy the AnyEvent::Handle object from
…		…
1631	$handle->on_drain (sub {	1773	$handle->on_drain (sub {
1632	warn "all data submitted to the kernel\n";	1774	warn "all data submitted to the kernel\n";
1633	undef $handle;	1775	undef $handle;
1634	});	1776	});
1635		1777
		1778	If you just want to queue some data and then signal EOF to the other side,
		1779	consider using C<< ->push_shutdown >> instead.
		1780
		1781	=item I want to contact a TLS/SSL server, I don't care about security.
		1782
		1783	If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
		1784	simply connect to it and then create the AnyEvent::Handle with the C<tls>
		1785	parameter:
		1786
		1787	tcp_connect $host, $port, sub {
		1788	my ($fh) = @_;
		1789
		1790	my $handle = new AnyEvent::Handle
		1791	fh => $fh,
		1792	tls => "connect",
		1793	on_error => sub { ... };
		1794
		1795	$handle->push_write (...);
		1796	};
		1797
		1798	=item I want to contact a TLS/SSL server, I do care about security.
		1799
		1800	Then you should additionally enable certificate verification, including
		1801	peername verification, if the protocol you use supports it (see
		1802	L<AnyEvent::TLS>, C<verify_peername>).
		1803
		1804	E.g. for HTTPS:
		1805
		1806	tcp_connect $host, $port, sub {
		1807	my ($fh) = @_;
		1808
		1809	my $handle = new AnyEvent::Handle
		1810	fh => $fh,
		1811	peername => $host,
		1812	tls => "connect",
		1813	tls_ctx => { verify => 1, verify_peername => "https" },
		1814	...
		1815
		1816	Note that you must specify the hostname you connected to (or whatever
		1817	"peername" the protocol needs) as the C<peername> argument, otherwise no
		1818	peername verification will be done.
		1819
		1820	The above will use the system-dependent default set of trusted CA
		1821	certificates. If you want to check against a specific CA, add the
		1822	C<ca_file> (or C<ca_cert>) arguments to C<tls_ctx>:
		1823
		1824	tls_ctx => {
		1825	verify => 1,
		1826	verify_peername => "https",
		1827	ca_file => "my-ca-cert.pem",
		1828	},
		1829
		1830	=item I want to create a TLS/SSL server, how do I do that?
		1831
		1832	Well, you first need to get a server certificate and key. You have
		1833	three options: a) ask a CA (buy one, use cacert.org etc.) b) create a
		1834	self-signed certificate (cheap. check the search engine of your choice,
		1835	there are many tutorials on the net) or c) make your own CA (tinyca2 is a
		1836	nice program for that purpose).
		1837
		1838	Then create a file with your private key (in PEM format, see
		1839	L<AnyEvent::TLS>), followed by the certificate (also in PEM format). The
		1840	file should then look like this:
		1841
		1842	-----BEGIN RSA PRIVATE KEY-----
		1843	...header data
		1844	... lots of base64'y-stuff
		1845	-----END RSA PRIVATE KEY-----
		1846
		1847	-----BEGIN CERTIFICATE-----
		1848	... lots of base64'y-stuff
		1849	-----END CERTIFICATE-----
		1850
		1851	The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts. Then
		1852	specify this file as C<cert_file>:
		1853
		1854	tcp_server undef, $port, sub {
		1855	my ($fh) = @_;
		1856
		1857	my $handle = new AnyEvent::Handle
		1858	fh => $fh,
		1859	tls => "accept",
		1860	tls_ctx => { cert_file => "my-server-keycert.pem" },
		1861	...
		1862
		1863	When you have intermediate CA certificates that your clients might not
		1864	know about, just append them to the C<cert_file>.
		1865
1636	=back	1866	=back
1637		1867
1638		1868
1639	=head1 SUBCLASSING AnyEvent::Handle	1869	=head1 SUBCLASSING AnyEvent::Handle
1640		1870

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.132 by elmex, Thu Jul 2 22:25:13 2009 UTC vs. Revision 1.146 by root, Wed Jul 8 13:46:46 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.132 by elmex, Thu Jul 2 22:25:13 2009 UTC vs.
Revision 1.146 by root, Wed Jul 8 13:46:46 2009 UTC