… | |
… | |
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.452; |
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; |
… | |
… | |
249 | |
249 | |
250 | A string used to identify the remote site - usually the DNS hostname |
250 | A string used to identify the remote site - usually the DNS hostname |
251 | (I<not> IDN!) used to create the connection, rarely the IP address. |
251 | (I<not> IDN!) used to create the connection, rarely the IP address. |
252 | |
252 | |
253 | Apart from being useful in error messages, this string is also used in TLS |
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>). |
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>. |
255 | |
257 | |
256 | =item tls => "accept" | "connect" | Net::SSLeay::SSL object |
258 | =item tls => "accept" | "connect" | Net::SSLeay::SSL object |
257 | |
259 | |
258 | 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 |
259 | 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 |
… | |
… | |
585 | Scalar::Util::weaken $self; |
587 | Scalar::Util::weaken $self; |
586 | |
588 | |
587 | my $cb = sub { |
589 | my $cb = sub { |
588 | my $len = syswrite $self->{fh}, $self->{wbuf}; |
590 | my $len = syswrite $self->{fh}, $self->{wbuf}; |
589 | |
591 | |
590 | if ($len >= 0) { |
592 | if (defined $len) { |
591 | substr $self->{wbuf}, 0, $len, ""; |
593 | substr $self->{wbuf}, 0, $len, ""; |
592 | |
594 | |
593 | $self->{_activity} = AnyEvent->now; |
595 | $self->{_activity} = AnyEvent->now; |
594 | |
596 | |
595 | $self->{on_drain}($self) |
597 | $self->{on_drain}($self) |
… | |
… | |
1780 | |
1782 | |
1781 | If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS, |
1783 | If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS, |
1782 | simply connect to it and then create the AnyEvent::Handle with the C<tls> |
1784 | simply connect to it and then create the AnyEvent::Handle with the C<tls> |
1783 | parameter: |
1785 | parameter: |
1784 | |
1786 | |
|
|
1787 | tcp_connect $host, $port, sub { |
|
|
1788 | my ($fh) = @_; |
|
|
1789 | |
1785 | my $handle = new AnyEvent::Handle |
1790 | my $handle = new AnyEvent::Handle |
1786 | fh => $fh, |
1791 | fh => $fh, |
1787 | tls => "connect", |
1792 | tls => "connect", |
1788 | on_error => sub { ... }; |
1793 | on_error => sub { ... }; |
1789 | |
1794 | |
1790 | $handle->push_write (...); |
1795 | $handle->push_write (...); |
|
|
1796 | }; |
1791 | |
1797 | |
1792 | =item I want to contact a TLS/SSL server, I do care about security. |
1798 | =item I want to contact a TLS/SSL server, I do care about security. |
1793 | |
1799 | |
1794 | Then you #x##TODO# |
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>). |
1795 | |
1803 | |
1796 | |
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>. |
1797 | |
1865 | |
1798 | =back |
1866 | =back |
1799 | |
1867 | |
1800 | |
1868 | |
1801 | =head1 SUBCLASSING AnyEvent::Handle |
1869 | =head1 SUBCLASSING AnyEvent::Handle |