NAME¶

Net::SSLGlue::Socket - socket which can be either SSL or plain IP (IPv4/IPv6)

SYNOPSIS¶

    use Net::SSLGlue::Socket;
    # SSL right from start
    my $ssl = Net::SSLGlue::Socket->new(
        PeerHost => ...,  # IPv4|IPv6 address
        PeerPort => ...,
        SSL => 1,
        SSL_ca_path => ...
    );
    # SSL through upgrade of plain connection
    my $plain = Net::SSLGlue::Socket->new(...);
    $plain->start_SSL( SSL_ca_path => ... );
    ...
    $plain->stop_SSL

DESCRIPTION¶

First, it is recommended to use IO::Socket::SSL directly instead of this module, since this kind of functionality is available in IO::Socket::SSL since version 1.994.

Net::SSLGlue::Socket implements a socket which can be either plain or SSL. If IO::Socket::IP or IO::Socket::INET6 are installed it will also transparently handle IPv6 connections.

A socket can be either start directly with SSL or it can be start plain and later be upgraded to SSL (because of a STARTTLS commando or similar) and also downgraded again.

It is possible but not recommended to use the socket in non-blocking mode, because in this case special care must be taken with SSL (see documentation of IO::Socket::SSL).

Additionally to the usual socket methods the following methods are defined or extended:

METHODS¶

new

The method "new" of Net::SSLGlue::Socket can have the argument SSL. If this is true the SSL upgrade will be done immediately. If not set any SSL_* args will still be saved and used at a later start_SSL call.

start_SSL

This will upgrade the plain socket to SSL. See IO::Socket::SSL for arguments to "start_SSL". Any SSL_* arguments given to new will be applied here too.

stop_SSL

This will downgrade the socket from SSL to plain.

peer_certificate ...

Once the SSL connection is established you can use this method to get information about the certificate. See the IO::Socket::SSL documentation.

can_read(timeout)

This will check for available data. For a plain socket this will only use "select" to check the socket, but for SSL it will check if there are any pending data before trying a select. Because SSL needs to read the whole frame before decryption can be done, a successful return of can_read is no guarantee that data can be read immediately, only that new data are either available or in the process of arriving.

SEE ALSO¶

IO::Socket::SSL

COPYRIGHT¶

This module is copyright (c) 2013..2015, Steffen Ullrich. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.