IO::Socket::SSL -- Nearly transparent SSL encapsulation for IO::Socket::INET.
use strict;
use IO::Socket::SSL;
my $client = IO::Socket::SSL->new("www.example.com:https")
|| warn "I encountered a problem: ".IO::Socket::SSL::errstr();
$client->verify_hostname( 'www.example.com','http' )
|| die "hostname verification failed";
print $client "GET / HTTP/1.0\r\n\r\n";
print <$client>;
This module is a true drop-in replacement for IO::Socket::INET that uses SSL to encrypt data before it is transferred to a remote server or client. IO::Socket::SSL supports all the extra features that one needs to write a full-featured SSL client or server application: multiple SSL contexts, cipher selection, certificate verification, and SSL version selection. As an extra bonus, it works perfectly with mod_perl.
If you have never used SSL before, you should read the appendix labelled 'Using SSL' before attempting to use this module.
If you have used this module before, read on, as versions 0.93 and above have several changes from the previous IO::Socket::SSL versions (especially see the note about return values).
If you are using non-blocking sockets read on, as version 0.98 added better support for non-blocking.
If you are trying to use it with threads see the BUGS section.
IO::Socket::SSL inherits its methods from IO::Socket::INET, overriding them as necessary. If there is an SSL error, the method or operation will return an empty list (false in all contexts). The methods that have changed from the perspective of the user are re-documented here:
Creates a new IO::Socket::SSL object. You may use all the friendly options that came bundled with IO::Socket::INET, plus (optionally) the ones that follow:
This can be given to specifiy the hostname used for SNI, which is needed if you have multiple SSL hostnames on the same IP address. If not given it will try to determine hostname from PeerAddr, which will fail if only IP was given or if this argument is used within start_SSL.
If you want to disable SNI set this argument to ''.
Currently only supported for the client side and will be ignored for the server side.
Sets the version of the SSL protocol used to transmit data. 'SSLv23' auto-negotiates between SSLv2 and SSLv3, while 'SSLv2', 'SSLv3' or 'TLSv1' restrict the protocol to the specified version. All values are case-insensitive.
You can limit to set of supported protocols by adding !version separated by ':'.
The default SSL_version is 'SSLv23:!SSLv2' which means, that SSLv2, SSLv3 and TLSv1 are supported for initial protocol handshakes, but SSLv2 will not be accepted, leaving only SSLv3 and TLSv1. You can also use !TLSv11 and !TLSv12 to disable TLS versions 1.1 and 1.2 while allowing TLS version 1.0.
Setting the version instead to 'TLSv1' will probably break interaction with lots of clients which start with SSLv2 and then upgrade to TLSv1. On the other side some clients just close the connection when they receive a TLS version 1.1 request. In this case setting the version to 'SSLv23:!SSLv2:!TLSv11:!TLSv12' might help.
If this option is set the cipher list for the connection will be set to the given value, e.g. something like 'ALL:!LOW:!EXP:!ADH'. Look into the OpenSSL documentation (http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS) for more details.
If this option is not set 'ALL:!LOW' will be used. To use OpenSSL builtin default (whatever this is) set it to ''.
If this option is true the cipher order the server specified is used instead of the order proposed by the client. To mitigate BEAST attack you might use something like
SSL_honor_cipher_order => 1, SSL_cipher_list => 'RC4-SHA:ALL:!ADH:!LOW',
If this is set, it forces IO::Socket::SSL to use a certificate and key, even if you are setting up an SSL client. If this is set to 0 (the default), then you will only need a certificate and key if you are setting up a server.
SSL_use_cert will implicitly be set if SSL_server is set. For convinience it is also set if it was not given but a cert was given for use (SSL_cert_file or similar).
Use this, if the socket should be used as a server. If this is not explicitly set it is assumed, if Listen with given when creating the socket.
If your RSA private key is not in default place (certs/server-key.pem for servers, certs/client-key.pem for clients), then this is the option that you would use to specify a different location. Keys should be PEM formatted, and if they are encrypted, you will be prompted to enter a password before the socket is formed (unless you specified the SSL_passwd_cb option).
This is an EVP_PKEY* and can be used instead of SSL_key_file. Useful if you don't have your key in a file but create it dynamically or get it from a string (see openssl PEM_read_bio_PrivateKey etc for getting a EVP_PKEY* from a string).
If your SSL certificate is not in the default place (certs/server-cert.pem for servers, certs/client-cert.pem for clients), then you should use this option to specify the location of your certificate. Note that a key and certificate are only required for an SSL server, so you do not need to bother with these trifling options should you be setting up an unauthenticated client.
This is an X509* or an array of X509*. The first X509* is the internal representation of the certificate while the following ones are extra certificates. Useful if you create your certificate dynamically (like in a SSL intercepting proxy) or get it from a string (see openssl PEM_read_bio_X509 etc for getting a X509* from a string).
If you want Diffie-Hellman key exchange you need to supply a suitable file here or use the SSL_dh parameter. See dhparam command in openssl for more information.
Like SSL_dh_file, but instead of giving a file you use a preloaded or generated DH*.
If your private key is encrypted, you might not want the default password prompt from Net::SSLeay. This option takes a reference to a subroutine that should return the password required to decrypt your private key.
If you want to verify that the peer certificate has been signed by a reputable certificate authority, then you should use this option to locate the file containing the certificate(s) of the reputable certificate authorities if it is not already in the file certs/my-ca.pem. If you definitly want no SSL_ca_file used you should set it to undef.
If you are unusually friendly with the OpenSSL documentation, you might have set yourself up a directory containing several trusted certificates as separate files as well as an index of the certificates. If you want to use that directory for validation purposes, and that directory is not ca/, then use this option to point IO::Socket::SSL to the right place to look. If you definitly want no SSL_ca_path used you should set it to undef.
This option sets the verification mode for the peer certificate. The default (0x00) does no authentication. You may combine 0x01 (verify peer), 0x02 (fail verification if no peer certificate exists; ignored for clients), and 0x04 (verify client once) to change the default.
See OpenSSL man page for SSL_CTX_set_verify for more information.
If you want to verify certificates yourself, you can pass a sub reference along with this parameter to do so. When the callback is called, it will be passed:
