| … | |
… | |
| 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 |
| … | |
… | |
| 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 |
